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>.

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 modify the values in a fixed catalog of named sets; you cannot invent a new set or add brand-new values.

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. You can ONLY modify values inside the fixed catalog of named standard value sets. You cannot add a brand-new value, and you cannot create a new StandardValueSet name. The Metadata API will reject both.
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. Emit ONLY the values the request explicitly names — a surgical, minimal change. Include a <standardValue> block for each value the user asks you to activate, deactivate, relabel, or reorder, and nothing else. Do not enumerate the full picklist or emit <standardValue> entries for values the request did not mention. A StandardValueSet deployment is a partial update: unlisted values keep their current org state untouched. Reproducing every value (e.g. all 30+ Industry entries) is noise and risks clobbering org state — it is wrong even when the request says "keep only X active," which means "set the named ones; leave the rest as-is," not "enumerate and deactivate everything else." If you use the grounding MCP to discover existing values, use it only to confirm the named values exist and to get their exact <fullName>/<label> — not as a list to reproduce in full.

<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 (modify existing values only)

<?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>
</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> <!-- WRONG: cannot ADD a new value to a standard set -->
        <label>Renewable Energy</label>
    </customValue>
</StandardValueSet>

Errors: unknown element masterLabel/customValue; adding a value not already in the standard catalog fails deployment.

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

When customizing a StandardValueSet (or extending a shared GlobalValueSet), only modify values that already exist — never invent the value list of a standard picklist. The hard rule is about what you EMIT: a <standardValue> whose <fullName> is not a real catalog value will fail deployment.

For well-known standard picklists you already know the canonical values (e.g. Industry, LeadSource, OpportunityStage). When you are unsure a named value exists, you can confirm it 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 only to confirm a named value's exact <fullName>/<label> — not to pull the full list to reproduce.
• 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: emit modifications ONLY to values you know exist. A generated StandardValueSet that introduces unseen values is a hallucination and will fail deployment. (This pairs with the minimal-scope rule in §3: confirm the named values; don't enumerate 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:

INCORRECT — adding a value to a standard set

"Add a Cryptocurrency value to the Industry picklist."

Do not emit a <standardValue> with fullName Cryptocurrency. Respond that standard value sets are a fixed catalog and propose a GlobalValueSet (if reused across fields) or an inline restricted picklist on a single CustomField.

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

• Are you emitting modifications ONLY to values you know exist (confirmed from known standard catalogs, or via grounding search_metadata/query-metadata / Tooling API if unsure) — never invented values?
• 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)?
• Are you ONLY modifying values that already exist (no new fullName)?
• Did you avoid adding a brand-new value or a new set name?

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?