platform-value-set-generate

File: standardValueSets/<Name>.standardValueSet-meta.xml

HARD CONSTRAINTS — read before generating

1. A StandardValueSet name must come from the fixed catalog of named standard value sets. You cannot create a new StandardValueSet name. You can add a new value to an existing standard set, but copy the full attribute pattern of an existing value in that set (for example closed, forecastCategory, probability and won on OpportunityStage), because omitted attributes are filled with platform defaults that can be wrong.
2. The root carries a <fullName> whose value is the fixed enum name (e.g. Industry), NOT a masterLabel. The filename must match this name.
3. Values are <standardValue> entries — not <customValue>.
4. A StandardValueSet write REPLACES the whole set. Send every existing value and change only what the request names. Read the current set first (grounding MCP or a retrieve), then include a <standardValue> block for every existing value, with the requested activations, deactivations, relabels or additions applied. A value you leave out is deactivated on the field: a deploy that named only Web in CaseOrigin left Email, Phone and Agentforce inactive. Never send only the named values, even when the set is large (for example all 30+ Industry entries). Request wording such as "keep only X active" means set X active and every other value inactive, so state that intent in the result. Verify by reading the set back and diffing it against the read taken before the write.

<standardValue> — Modifiable Sub-Elements

Sub-element	Modifiable?	Notes
<fullName>	Identifies the value	An existing value, or a new one you are adding
<label>	Yes	Relabel the value's UI text
<isActive>	Yes	false deactivates; omit or true keeps active
<default>	Yes	At most one value true
<groupingString>	Yes	Category grouping (used by some standard picklists)

Canonical StandardValueSet Names (partial)

Industry, LeadSource, OpportunityStage, OpportunityType, AccountType, AccountRating, LeadStatus, CaseStatus, CaseOrigin, CasePriority, CaseReason, TaskStatus, TaskPriority, QuoteStatus, Product2Family, Salutation, AccountOwnership, ContractStatus, OrderStatus, PartnerRole.

Full appendix: the complete list of valid standard value set names is at https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/standardvalueset_names.htm. If the name is not in that appendix, it is not a StandardValueSet — it is either a GlobalValueSet or an inline CustomField picklist.

CORRECT — StandardValueSet (the complete set, with the requested change applied)

<?xml version="1.0" encoding="UTF-8"?>
<StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Industry</fullName>
    <standardValue>
        <fullName>Technology</fullName>
        <default>false</default>
        <label>Technology</label>
        <isActive>true</isActive>
    </standardValue>
    <standardValue>
        <fullName>Agriculture</fullName>
        <default>false</default>
        <label>Agriculture</label>
        <isActive>false</isActive>   <!-- deactivated, but kept in the set -->
    </standardValue>
    <!-- ... every other existing standardValue entry repeated unchanged ... -->
</StandardValueSet>

INCORRECT — StandardValueSet

<StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Industry</masterLabel>     <!-- WRONG: StandardValueSet uses <fullName>, not masterLabel -->
    <customValue>                           <!-- WRONG: uses <standardValue>, not customValue -->
        <fullName>Renewable Energy</fullName>
        <label>Renewable Energy</label>
    </customValue>
</StandardValueSet>

Errors: unknown element masterLabel/customValue for a StandardValueSet.

---

4. Never Invent Values — Verify, Don't Hallucinate CRITICAL

When customizing a StandardValueSet (or extending a shared GlobalValueSet), never invent the existing value list of a standard picklist. Existing values must be repeated exactly as the org has them, and a new value is added only when the request names it.

For well-known standard picklists you already know the canonical values (e.g. Industry, LeadSource, OpportunityStage). When you are unsure which values exist, you can confirm them against the live org — but treat lookup as a confirmation step, not a required first call:

• Grounding MCP (if available) exposes search_metadata and query_metadata to look up live metadata. Use them to read the complete current set, because a write must repeat every existing value with its exact <fullName>/<label>.
• CLI fallback — query the Tooling API directly:

sf data query --use-tooling-api \
  --query "SELECT MasterLabel, Metadata FROM StandardValueSet WHERE MasterLabel = '<name>'"

The point is the output, not the lookup: the written set must contain every existing value unchanged, plus only the changes the request names. Do not invent values the request did not ask for. (This pairs with rule 4 in §3: a write replaces the whole set.)

---

5. Referencing a Value Set from a CustomField

A picklist/multi-select CustomField references a value set via <valueSetName> inside <valueSet> (instead of an inline <valueSetDefinition>).

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Priority__c</fullName>
    <label>Priority</label>
    <type>Picklist</type>
    <valueSet>
        <restricted>true</restricted>
        <valueSetName>Priority_Levels</valueSetName>  <!-- bare developer name, NO __gvs; see §2 -->
    </valueSet>
</CustomField>

• For a GlobalValueSet, <valueSetName> is the bare developer name (e.g. Priority_Levels) — never add __gvs. The suffix is an org-storage display artifact; the Metadata API uses the bare name for both deploy and retrieve (see §2).
• A field bound to a value set must not also declare an inline <valueSetDefinition> — choose one or the other.

---

6. Validation Rules

The agent must reject and explain — not silently "fix" by inventing metadata — the following:

Violation	Action / Message
Create a NEW StandardValueSet name	Reject. The name must be in the standard catalog appendix. Otherwise it is a GlobalValueSet.
Value set developer name with spaces / invalid chars	Convert spaces to underscores; must start with a letter; alphanumeric + underscore only. Priority Levels → Priority_Levels. (This applies to the value SET name and the field API name — NOT to individual <customValue><fullName> values, which keep spaces as written.)
Duplicate value fullName within one set	Reject. Each fullName must be unique within the value set.
More than one <default>true</default>	Reject. At most one default value per set.

Adding a value to a standard set

"Add a Cryptocurrency value to the Industry picklist."

This is allowed. Read the complete current Industry set, then write it back with every existing value unchanged plus one new <standardValue> for Cryptocurrency. Copy the attribute pattern of an existing value in the set, because omitted attributes get platform defaults that can be wrong.

---

7. Deployment Ordering

A value set must deploy before any CustomField that references it.

• Deploy the GlobalValueSet / StandardValueSet first, then the CustomField whose <valueSetName> points at it.
• A field referencing a value set that does not yet exist fails with valueSetName ... does not exist (or a "not found" error).
• In package.xml: GlobalValueSet supports the * wildcard; StandardValueSet does not — list each standard set member explicitly.

---

8. Common Deployment Errors

Error / Symptom	Cause	Fix
Other values of a standard picklist became inactive after a deploy	The deploy listed only some values, and a write replaces the whole set	Resend the complete set with every existing value (§3 rule 4)
Required field missing: sorted	GlobalValueSet missing <sorted>	Add <sorted>true</sorted> or <sorted>false</sorted>
Unknown element masterLabel (StandardValueSet)	Used masterLabel instead of fullName	StandardValueSet root uses <fullName> = catalog name
Unknown element customValue (StandardValueSet)	Used customValue instead of standardValue	Use <standardValue> in standard sets
valueSetName ... does not exist	Field deployed before its value set, or __gvs wrongly added to the reference	Deploy the value set first; reference it by the bare developer name with NO __gvs (§2)
Duplicate value name	Two <customValue> entries share a fullName	Make each fullName unique within the set (spaces in a value name are allowed — do NOT underscore them)

---

Verification Checklist

Before generating value-set XML, verify:

Type Selection

• Is this a reusable set shared across fields (GlobalValueSet) or a built-in standard picklist (StandardValueSet)?
• If StandardValueSet: is the name in the standard catalog appendix? If not, it must be a GlobalValueSet or inline picklist.

GlobalValueSet Checks

• Is the root <GlobalValueSet> with namespace http://soap.sforce.com/2006/04/metadata?
• Is <masterLabel> present?
• Is <sorted> present (true or false)?
• Is there at least one <customValue>, each with <fullName> and <label> (at most one carrying <default>true</default>)?
• Is there NO root <fullName> (name comes from the filename)?
• When referencing from a field, is <valueSetName> the bare developer name with NO __gvs suffix?

StandardValueSet Checks CRITICAL

• Did you read the complete current set (grounding search_metadata/query_metadata / Tooling API / retrieve) so every existing value is repeated exactly?
• Is the root <StandardValueSet> with the correct namespace?
• Does the root use <fullName> set to the fixed catalog name (NOT masterLabel)?
• Are values <standardValue> entries (NOT customValue)?
• Does the written set contain every existing value, with only the changes the request names applied?
• Did you avoid a new set name, and for any new value did you copy the attribute pattern of an existing value?

Shared Checks

• At most one value has <default>true</default>?
• Are all value fullNames unique within the set? (Spaces in a value name are fine — preserve them as written; only the value-SET developer name and field API name use underscores.)
• Does the value set deploy BEFORE any CustomField that references it?
• Does the filename match the intended name?