platform-value-set-generate

Overview

Generates and validates the two reusable picklist value-set metadata types — GlobalValueSet (a new reusable set shared across fields) and StandardValueSet (customizing a built-in catalog picklist like Industry or Lead Source) — and wires a CustomField to one via <valueSetName>.

For authoritative Metadata API type, field, and enum details beyond this skill, use the platform-metadata-api-context-get skill.

Scope

• In scope: creating a GlobalValueSet, customizing a StandardValueSet, referencing either from a field, and the related deployment errors.
• Out of scope: a one-off inline picklist on a single field with no reuse → use platform-custom-field-generate (inline <valueSetDefinition>). Generating the field that references a value set is also platform-custom-field-generate's job; this skill produces the value set itself.

Two different metadata types — do not confuse them:

Specification

1. Purpose

This document defines the mandatory constraints for generating value-set metadata XML. The agent must verify these constraints before outputting XML to prevent Metadata API deployment errors.

• GlobalValueSet — a reusable, named set of picklist values defined once and referenced by any number of picklist/multi-select fields. Use when the same value list is shared across multiple fields.
• StandardValueSet — the value list behind a Salesforce-defined standard picklist (Industry, Lead Source, etc.). You can only customize the fixed catalog of named sets, so you cannot invent a new set name, but you can modify existing values and add new ones.

2. GlobalValueSet — Syntactic Essentials

File: globalValueSets/<DeveloperName>.globalValueSet-meta.xml

The developer name comes from the filename, not a <fullName> tag.

Required Elements

<customValue> Sub-Elements

The __gvs Suffix — do NOT use it in metadata

Rule: reference a GlobalValueSet by its bare developer name. Never add __gvs.

In API 57.0+ orgs the platform stores/displays a GlobalValueSet's developer name with a __gvs suffix internally, but the Metadata API (deploy and retrieve) always uses the bare name — <valueSetName>Priority_Levels</valueSetName>, not Priority_Levels__gvs. The suffix was briefly emitted by a Winter '23 change that caused deploy failures and was patched out. So:

• The file is globalValueSets/Priority_Levels.globalValueSet-meta.xml — no __gvs in the filename.
• A field references it as <valueSetName>Priority_Levels</valueSetName> — no __gvs.
• If a retrieve shows Priority_Levels__gvs in the org or you see a "returned from org but not found in local project" warning, that's the expected org-storage display — keep your local metadata on the bare name.

CORRECT — GlobalValueSet

<?xml version="1.0" encoding="UTF-8"?>
<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Priority Levels</masterLabel>
    <sorted>false</sorted>
    <customValue>
        <fullName>Critical</fullName>
        <default>false</default>
        <label>Critical</label>
    </customValue>
    <customValue>
        <fullName>High</fullName>
        <default>false</default>
        <label>High</label>
    </customValue>
    <customValue>
        <fullName>Medium</fullName>
        <default>true</default>
        <label>Medium</label>
    </customValue>
    <customValue>
        <fullName>Low</fullName>
        <default>false</default>
        <label>Low</label>
    </customValue>
</GlobalValueSet>

INCORRECT — GlobalValueSet

<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Priority_Levels</fullName>      <!-- WRONG: name comes from the filename -->
    <masterLabel>Priority Levels</masterLabel>
    <!-- WRONG: <sorted> is required and missing -->
    <standardValue>                            <!-- WRONG: GVS uses <customValue>, not <standardValue> -->
        <fullName>Critical</fullName>
    </standardValue>
</GlobalValueSet>

Errors: missing required sorted; unknown element standardValue; root fullName is rejected because the name is derived from the filename.

3. StandardValueSet — Syntactic Essentials CRITICAL

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

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:

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

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?