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:

| Concern | GlobalValueSet | StandardValueSet |

|---------|----------------|------------------|

| Folder | globalValueSets/ | standardValueSets/ |

| File suffix | .globalValueSet-meta.xml | .standardValueSet-meta.xml |

| Root element | <GlobalValueSet> | <StandardValueSet> |

| Name source | filename (dev name) | <fullName> = fixed catalog name |

| Value element | <customValue> | <standardValue> |

| Can add NEW values? | Yes | No — modify existing only |

| Can create a new NAME? | Yes | No — only the fixed catalog |

| * wildcard in package.xml | Supported | Not supported |

---

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

| Element | Requirement | Notes |

|---------|-------------|-------|

| <masterLabel> | Required | UI label for the value set |

| <sorted> | Required | true = alphabetize values in the UI; false = preserve listed order |

| <customValue> | Required (≥1) | One per value (see below) |

<customValue> Sub-Elements

| Sub-element | Requirement | Notes |

|-------------|-------------|-------|

| <fullName> | Required | The value's API name. Use the value text as the user spelled it — spaces are allowed and must be preserved (e.g. Closed Won, not Closed_Won). Must start with a letter. This is a value name, NOT a field API name, so do not append __c or replace spaces with underscores. |

| <default> | Optional | At most one value true. Omit it (or use false) on the rest — it is not required on every value. |

| <label> | Required | UI label for the value |

| <color> | Optional | Hex color, e.g. #FF0000 |

| <isActive> | Optional | Omit (active) or false to deactivate |

| <description> | Optional | Per-value description |

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

| Sub-element | Modifiable? | Notes |

|-------------|-------------|-------|

| <fullName> | Identifies the value (must already exist) | Cannot introduce a new one |

| <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 (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:

| Violation | Action / Message |

|-----------|------------------|

| Add a NEW value to a StandardValueSet | Reject. "Standard value sets cannot accept new values. Create a GlobalValueSet (reusable) or an inline picklist on a CustomField instead." |

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

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

| Error / Symptom | Cause | Fix |

|-----------------|-------|-----|

| Value not added to standard picklist | Tried to ADD a value to a StandardValueSet | Standard sets are fixed; use GlobalValueSet or inline CustomField picklist |

| 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

• [ ] 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?