platform-value-set-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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>

本技能可生成并验证两种可复用选择列表值集元数据类型：GlobalValueSet（可跨字段共享的全新可复用值集）和StandardValueSet（对Industry或Lead Source等内置目录选择列表进行定制），并通过

<valueSetName>

将CustomField与其中一种值集关联。

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

适用场景：创建GlobalValueSet、定制StandardValueSet、从字段引用上述任一值集，以及相关的部署错误处理。
不适用场景：单个字段上不可复用的一次性内联选择列表→请使用**
```
platform-custom-field-generate
```
**（内联
```
<valueSetDefinition>
```
）。生成引用值集的字段也属于
```
platform-custom-field-generate
```
的职责范围；本技能仅负责生成值集本身。

两种不同的元数据类型——请勿混淆：

关注点	GlobalValueSet	StandardValueSet
文件夹	`globalValueSets/`	`standardValueSets/`
文件后缀	`.globalValueSet-meta.xml`	`.standardValueSet-meta.xml`
根元素	`<GlobalValueSet>`	`<StandardValueSet>`
名称来源	文件名（开发者名称）	`<fullName>` = 固定目录名称
值元素	`<customValue>`	`<standardValue>`
是否可添加新值？	是	否——仅可修改现有值
是否可创建新名称？	是	否——仅可使用固定目录中的名称
package.xml中的 `*` 通配符	支持	不支持

Specification

规范说明

1. Purpose

1. 目的

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.

本文档定义了生成值集元数据XML的强制约束条件。Agent在输出XML前必须验证这些约束，以避免Metadata API部署错误。

GlobalValueSet — 一种可复用的命名选择列表值集，只需定义一次，即可被任意数量的选择列表/多选字段引用。当同一值列表需要跨多个字段共享时使用。
StandardValueSet — Salesforce定义的标准选择列表（如Industry、Lead Source等）背后的值列表。您仅能修改固定命名目录集中的值；无法创建新的集合或添加全新值。

2. GlobalValueSet — Syntactic Essentials

2. GlobalValueSet — 语法要点

File:

globalValueSets/<DeveloperName>.globalValueSet-meta.xml

The developer name comes from the filename, not a

<fullName>

tag.

文件路径：

globalValueSets/<DeveloperName>.globalValueSet-meta.xml

开发者名称来自文件名，而非

<fullName>

标签。

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)

元素	要求	说明
`<masterLabel>`	必填	值集的UI标签
`<sorted>`	必填	`true` = 在UI中按字母顺序排列值； `false` = 保留列出的顺序
`<customValue>`	必填（至少1个）	每个值对应一个该元素（详见下文）

<customValue>

Sub-Elements

<customValue>

子元素

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

子元素	要求	说明
`<fullName>`	必填	值的API名称。请完全按照用户拼写的内容使用值文本——允许包含空格且必须保留（例如 `Closed Won` ，而非 `Closed_Won` ）。必须以字母开头。这是值的名称，而非字段API名称，因此请勿追加 `__c` 或用下划线替换空格。
`<default>`	可选	最多只能有一个值设为 `true` 。其余值可省略该元素（或设为 `false` ）——无需为每个值添加该元素。
`<label>`	必填	值的UI标签
`<color>`	可选	十六进制颜色值，例如 `#FF0000`
`<isActive>`	可选	省略则表示激活；设为 `false` 则表示停用
`<description>`	可选	单个值的描述信息

The

__gvs

Suffix — do NOT use it in metadata

__gvs

后缀——请勿在元数据中使用

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.

规则：使用裸开发者名称引用GlobalValueSet。切勿添加
__gvs
。

在API 57.0+版本的组织中，平台内部会为GlobalValueSet的开发者名称添加

__gvs

后缀进行存储/显示，但Metadata API（部署和检索）始终使用裸名称——例如

<valueSetName>Priority_Levels</valueSetName>

，而非

Priority_Levels__gvs

。该后缀曾在Winter '23的一次更新中被输出，导致部署失败，随后已被修复。因此：

文件路径为

globalValueSets/Priority_Levels.globalValueSet-meta.xml

——文件名中无
__gvs
。

字段引用时使用

<valueSetName>Priority_Levels</valueSetName>

——无
__gvs
。

如果检索时组织中显示
```
Priority_Levels__gvs
```
，或您看到“从组织返回但在本地项目中未找到”的警告，这是组织存储显示的正常现象——请保持本地元数据使用裸名称。

CORRECT — GlobalValueSet

正确示例——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>

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

错误示例——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.

xml

<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Priority_Levels</fullName>      <!-- 错误：名称来自文件名 -->
    <masterLabel>Priority Levels</masterLabel>
    <!-- 错误：缺少必填的<sorted>元素 -->
    <standardValue>                            <!-- 错误：GVS使用<customValue>，而非<standardValue> -->
        <fullName>Critical</fullName>
    </standardValue>
</GlobalValueSet>

错误原因：缺少必填的

sorted

元素；存在未知元素

standardValue

；根元素的

fullName

会被拒绝，因为名称由文件名派生。

3. StandardValueSet — Syntactic Essentials CRITICAL

3. StandardValueSet — 语法要点（关键）

File:

standardValueSets/<Name>.standardValueSet-meta.xml

文件路径：

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.

您仅能修改固定标准值集目录内的值。您无法添加全新值，也无法创建新的StandardValueSet名称。Metadata API会拒绝这两种操作。
根元素包含
```
<fullName>
```
，其值为固定枚举名称（例如
```
Industry
```
），而非
```
masterLabel
```
。文件名必须与该名称匹配。
值为
```
<standardValue>
```
条目——而非
```
<customValue>
```
。
仅输出请求明确提及的值——进行精准、最小化修改。为用户要求激活、停用、重命名或重新排序的每个值添加一个
```
<standardValue>
```
块，其余内容请勿包含。请勿枚举完整的选择列表，或为请求未提及的值输出
```
<standardValue>
```
条目。StandardValueSet部署是部分更新：未列出的值将保持其当前组织状态不变。重现所有值（例如30多个Industry条目）属于冗余操作，且可能破坏组织状态——即使请求说“仅保持X激活”，也意味着“设置指定的值；其余值保持原样”，而非“枚举并停用所有其他值”。如果使用grounding MCP发现现有值，仅用它确认指定值存在并获取其准确的
```
<fullName>
```
/
```
<label>
```
——而非重现完整列表。

<standardValue>

— Modifiable Sub-Elements

<standardValue>

——可修改的子元素

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)

子元素	是否可修改？	说明
`<fullName>`	用于标识值（必须已存在）	无法引入新值
`<label>`	是	修改值的UI文本
`<isActive>`	是	`false` 表示停用；省略或设为 `true` 表示保持激活
`<default>`	是	最多只能有一个值设为 `true`
`<groupingString>`	是	类别分组（部分标准选择列表使用）

Canonical StandardValueSet Names (partial)

标准StandardValueSet名称（部分）

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.

Industry

LeadSource

OpportunityStage

OpportunityType

AccountType

AccountRating

LeadStatus

CaseStatus

CaseOrigin

CasePriority

CaseReason

TaskStatus

TaskPriority

QuoteStatus

Product2Family

Salutation

AccountOwnership

ContractStatus

OrderStatus

PartnerRole

完整附录：有效标准值集名称的完整列表可查看
https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/standardvalueset_names.htm
. 如果名称不在该附录中，则不是StandardValueSet——它要么是GlobalValueSet，要么是内联CustomField选择列表。

CORRECT — StandardValueSet (modify existing values only)

正确示例——StandardValueSet（仅修改现有值）

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>

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>   <!-- 已停用，但仍保留在集合中 -->
    </standardValue>
</StandardValueSet>

INCORRECT — StandardValueSet

错误示例——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.

xml

<StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Industry</masterLabel>     <!-- 错误：StandardValueSet使用<fullName>，而非masterLabel -->
    <customValue>                           <!-- 错误：使用<standardValue>，而非customValue -->
        <fullName>Renewable Energy</fullName> <!-- 错误：无法向标准集合添加新值 -->
        <label>Renewable Energy</label>
    </customValue>
</StandardValueSet>

错误原因：存在未知元素

masterLabel

customValue

；添加标准目录中不存在的值会导致部署失败。

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

4. 切勿凭空生成值——验证而非臆造（关键）

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

在定制StandardValueSet（或扩展共享的GlobalValueSet）时，仅修改已存在的值——切勿凭空生成标准选择列表的值列表。核心规则是关于输出内容：

<standardValue>

的

<fullName>

若不是真实目录中的值，将导致部署失败。

对于知名的标准选择列表，您已了解其标准值（例如

Industry

、

LeadSource

、

OpportunityStage

）。当您不确定某个指定值是否存在时，可在实时组织中确认——但请将查询视为确认步骤，而非必需的前置操作：

Grounding MCP（若可用）提供
```
search_metadata
```
和
```
query-metadata
```
功能，可查询实时元数据。仅用它确认指定值的准确
```
<fullName>
```
/
```
<label>
```
——而非拉取完整列表进行重现。
CLI备选方案——直接查询Tooling API：

bash

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

核心是输出内容，而非查询过程：仅对您确认存在的值进行修改。生成的StandardValueSet若包含未见过的值，属于臆造内容，会导致部署失败。（这与第3节中的最小范围规则相辅相成：确认指定的值；请勿枚举整个集合。）

5. Referencing a Value Set from a CustomField

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

选择列表/多选CustomField通过

<valueSet>

内的

<valueSetName>

引用值集（而非内联

<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>  <!-- 裸开发者名称，无__gvs；详见第2节 -->
    </valueSet>
</CustomField>

对于GlobalValueSet，
```
<valueSetName>
```
为裸开发者名称（例如
```
Priority_Levels
```
）——切勿添加
```
__gvs
```
。该后缀是组织存储显示的产物；Metadata API在部署和检索时均使用裸名称（详见第2节）。
绑定到值集的字段不得同时声明内联
```
<valueSetDefinition>
```
——二选一即可。

6. Validation Rules

6. 验证规则

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.

Agent必须拒绝并解释以下情况——而非默默“修复”或凭空生成元数据：

违规情况	操作/提示信息
向StandardValueSet添加新值	拒绝。“标准值集无法接受新值。请创建GlobalValueSet（可复用）或在CustomField上使用内联选择列表。”
创建新的StandardValueSet名称	拒绝。名称必须属于标准目录附录。否则应使用GlobalValueSet。
值集开发者名称包含空格/无效字符	将空格转换为下划线；必须以字母开头；仅允许字母、数字和下划线。例如 `Priority Levels` → `Priority_Levels` 。（此规则适用于值集名称和字段API名称——不适用于单个 `<customValue><fullName>` 值，这些值需保留用户输入的空格。）
同一集合内存在重复的 `fullName` 值	拒绝。每个 `fullName` 在值集内必须唯一。
存在多个 `<default>true</default>`	拒绝。每个集合最多只能有一个默认值。

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.

“向Industry选择列表添加
Cryptocurrency
值。”

请勿输出

<standardValue>

且

fullName

为

Cryptocurrency

的内容。应回复用户：标准值集是固定目录，建议使用GlobalValueSet（若需跨字段复用）或单个CustomField上的内联受限选择列表。

7. Deployment Ordering

7. 部署顺序

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.

值集必须在所有引用它的CustomField之前部署。

先部署
```
GlobalValueSet
```
/
```
StandardValueSet
```
，再部署
```
<valueSetName>
```
指向该值集的CustomField。
引用不存在的值集的字段会部署失败，错误信息为
```
valueSetName ... does not exist
```
（或“未找到”错误）。
在
```
package.xml
```
中：
```
GlobalValueSet
```
支持
```
*
```
通配符；
```
StandardValueSet
```
不支持——需显式列出每个标准集合成员。

8. Common Deployment Errors

8. 常见部署错误

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)

错误/症状	原因	修复方案
值未添加到标准选择列表	尝试向 `StandardValueSet` 添加值	标准集合是固定的；请使用GlobalValueSet或内联CustomField选择列表
`Required field missing: sorted`	GlobalValueSet缺少 `<sorted>` 元素	添加 `<sorted>true</sorted>` 或 `<sorted>false</sorted>`
未知元素 `masterLabel` （StandardValueSet）	使用了 `masterLabel` 而非 `fullName`	StandardValueSet根元素使用 `<fullName>` =目录名称
未知元素 `customValue` （StandardValueSet）	使用了 `customValue` 而非 `standardValue`	在标准集合中使用 `<standardValue>`
`valueSetName ... does not exist`	字段在值集之前部署，或引用时错误添加了 `__gvs`	先部署值集；使用裸开发者名称引用，无 `__gvs` （第2节）
值名称重复	两个 `<customValue>` 条目共享同一个 `fullName`	确保每个 `fullName` 在集合内唯一（值名称中允许包含空格——请勿替换为下划线）

Verification Checklist

验证清单

Before generating value-set XML, verify:

生成值集XML前，请验证以下内容：

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）还是内置标准选择列表（StandardValueSet）？
如果是StandardValueSet：名称是否在标准目录附录中？若不在，则必须是GlobalValueSet或内联选择列表。

GlobalValueSet Checks

GlobalValueSet检查

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?

根元素是否为

<GlobalValueSet>

且命名空间为

http://soap.sforce.com/2006/04/metadata

？

是否存在
```
<masterLabel>
```
？
是否存在
```
<sorted>
```
（值为
```
true
```
或
```
false
```
）？
是否至少有一个
```
<customValue>
```
，且每个
```
<customValue>
```
都包含
```
<fullName>
```
和
```
<label>
```
（最多一个包含
```
<default>true</default>
```
）？
是否没有根元素
```
<fullName>
```
（名称来自文件名）？
从字段引用时，
```
<valueSetName>
```
是否为裸开发者名称且无
```
__gvs
```
后缀？

StandardValueSet Checks CRITICAL

StandardValueSet检查（关键）

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?

是否仅对确认存在的值进行修改（通过已知标准目录确认，或不确定时通过grounding
```
search_metadata
```
/
```
query-metadata
```
/Tooling API确认）——从未臆造值？
根元素是否为
```
<StandardValueSet>
```
且命名空间正确？
根元素是否使用
```
<fullName>
```
且值为固定目录名称（而非
```
masterLabel
```
）？
值是否为
```
<standardValue>
```
条目（而非
```
customValue
```
）？
是否仅修改已存在的值（无新的
```
fullName
```
）？
是否未添加全新值或新集合名称？

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?

是否最多只有一个值的
```
<default>
```
为
```
true
```
？
集合内所有值的
```
fullName
```
是否唯一？（值名称中允许包含空格——按用户输入保留；仅值集开发者名称和字段API名称使用下划线。）
值集是否在所有引用它的CustomField之前部署？
文件名是否与预期名称匹配？