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

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

xml

<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

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.
The root carries a
```
<fullName>
```
whose value is the fixed enum name (e.g.
```
Industry
```
), NOT a
```
masterLabel
```
. The filename must match this name.
Values are
```
<standardValue>
```
entries — not
```
<customValue>
```
.
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

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

xml

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

bash

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>

xml

<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
```
fullName
```
s 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?