platform-value-set-generate

概要

再利用可能な2種類の選択リスト値セットメタデータ型、GlobalValueSet（複数の項目で共有する新しい再利用可能なセット）とStandardValueSet（Industry や Lead Source など、組み込みのカタログ選択リストをカスタマイズするもの）を生成および検証し、<valueSetName> を使って CustomField をいずれかに関連付けます。

このスキルの対象範囲を超える Metadata API の型、項目、列挙型の詳細については、platform-metadata-api-context-get スキルを使用してください。

対象範囲

• 対象: GlobalValueSet の作成、StandardValueSet のカスタマイズ、項目からのいずれかの参照、および関連するデプロイエラー。
• 対象外: 再利用しない、単一の項目だけに設定するインライン選択リスト → platform-custom-field-generate（インラインの <valueSetDefinition>）を使用してください。値セットを参照する 項目 の生成も platform-custom-field-generate の役割です。このスキルでは値セット自体を生成します。

異なる2種類のメタデータ型です。混同しないでください。

懸念事項	GlobalValueSet	StandardValueSet
フォルダー	globalValueSets/	standardValueSets/
ファイルの接尾辞	.globalValueSet-meta.xml	.standardValueSet-meta.xml
ルート要素	<GlobalValueSet>	<StandardValueSet>
名前の取得元	ファイル名（開発名）	<fullName> = 固定のカタログ名
値要素	<customValue>	<standardValue>
新しい値を追加できるか	はい	いいえ。既存の値のみ変更可能
新しい名前を作成できるか	はい	いいえ。固定のカタログのみ
package.xml の * ワイルドカード	対応	非対応

---

仕様

1. 目的

このドキュメントでは、値セットメタデータ XML を生成する際の必須制約を定めます。Metadata API のデプロイエラーを防ぐため、エージェントは XML を出力する前にこれらの制約を検証する必要があります。

• GlobalValueSet — 一度定義して任意の数の選択リスト／複数選択リスト項目から参照できる、再利用可能な名前付きの選択リスト値セットです。同じ値のリストを複数の項目で共有する場合に使用します。
• StandardValueSet — Salesforce 定義の標準選択リスト（Industry、Lead Source など）の値リストです。名前付きの固定セットのカタログにある値のみ変更できます。新しいセットを作成したり、まったく新しい値を追加したりすることはできません。

---

2. GlobalValueSet — 構文の基本

ファイル: globalValueSets/<DeveloperName>.globalValueSet-meta.xml

開発名は <fullName> タグではなく、ファイル名から取得します。

必須要素

要素	要件	備考
<masterLabel>	必須	値セットの UI ラベル
<sorted>	必須	true = UI で値をアルファベット順に並べます。false = 記載された順序を維持します
<customValue>	必須（1つ以上）	値ごとに1つ（以下を参照）

<customValue> のサブ要素

サブ要素	要件	備考
<fullName>	必須	値の API 名です。値のテキストはユーザーが入力したとおりに使用してください。スペースは使用可能で、保持する必要があります（例：Closed_Won ではなく Closed Won）。先頭は英字にしてください。これは値の名前であり、項目の API 名ではないため、__c を追加したり、スペースをアンダースコアに置き換えたりしないでください。
<default>	任意	true にできる値は最大1つです。それ以外では省略するか（または false を指定してください）。すべての値に指定する必要はありません。
<label>	必須	値の UI ラベル
<color>	任意	16進数の色。例：#FF0000
<isActive>	任意	省略（有効）するか、false を指定して無効化します
<description>	任意	値ごとの説明

__gvs 接尾辞 — メタデータでは使用しないでください

ルール：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 が表示される場合、または「組織から返されたがローカルプロジェクトで見つからない」という警告が表示される場合、これは想定どおりの組織ストレージ上の表示です — ローカルメタデータでは接尾辞なしの名前を使用してください。

正しい例 — 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>

誤った例 — GlobalValueSet

<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Priority_Levels</fullName>      
    <masterLabel>Priority Levels</masterLabel>
    
    <standardValue>                            
        <fullName>Critical</fullName>
    </standardValue>
</GlobalValueSet>

エラー： 必須の sorted がありません。不明な要素 standardValue があります。ルートの fullName は、名前がファイル名から導出されるため拒否されます。

---

3. StandardValueSet — 構文上の要点（重要）

ファイル： standardValueSets/<Name>.standardValueSet-meta.xml

厳守事項 — 生成前にお読みください

1. 変更できるのは、名前付きの標準値セットの固定カタログ内にある値のみです。 新しい値を追加したり、新しい StandardValueSet 名を作成したりすることはできません。Metadata API はどちらも拒否します。
2. ルートには <fullName> があり、その値は masterLabel ではなく固定の列挙名（例：Industry）です。ファイル名はこの名前と一致する必要があります。
3. 値には <standardValue> エントリーを使用します — <customValue> ではありません。
4. リクエストで明示的に指定された値のみを出力してください — 変更は必要最小限にします。 ユーザーが有効化、無効化、ラベル変更、または並べ替えを求めた値ごとに <standardValue> ブロックを含め、それ以外は一切含めないでください。リクエストで言及されていない値について、ピックリスト全体を列挙したり、<standardValue> エントリーを出力したりしないでください。StandardValueSet のデプロイは部分更新です。記載されていない値は、現在の組織の状態をそのまま維持します。すべての値（たとえば、30 件以上ある Industry のエントリーすべて）を再現するのは無駄なうえ、組織の状態を上書きするリスクがあり、「X のみを有効にしておく」というリクエストであっても誤りです。これは「指定された値を設定し、残りはそのままにする」という意味であり、「それ以外をすべて列挙して無効化する」という意味ではありません。グラウンディング MCP を使って既存の値を確認する場合は、指定された値の存在確認と、正確な <fullName>／<label> の取得にのみ使用してください。すべての値を列挙するために使用してはいけません。

<standardValue> — 変更可能なサブ要素

サブ要素	変更可能か	注記
<fullName>	値を識別します（既存の値である必要があります）	新しい値は追加できません
<label>	はい	値の UI テキストを変更します
<isActive>	はい	false は無効化します。省略するか true にすると有効のままです
<default>	はい	true にできる値は最大 1 つです
<groupingString>	はい	カテゴリーのグループ化（標準ピックリストの一部で使用）

標準的な StandardValueSet 名（一部）

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 ピックリストのいずれかです。

正しい例 — StandardValueSet（既存の値のみを変更）

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

誤り — StandardValueSet

<StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Industry</masterLabel>     
    <customValue>                           
        <fullName>Renewable Energy</fullName> 
        <label>Renewable Energy</label>
    </customValue>
</StandardValueSet>

エラー： 不明な要素 masterLabel／customValue。標準カタログに存在しない値を追加すると、デプロイに失敗します。

---

4. 値を決して捏造しない — 検証し、幻覚を起こさない（重要）

StandardValueSet をカスタマイズする場合（または共有の GlobalValueSet を拡張する場合）、すでに存在する値のみを変更してください。標準選択リストの値一覧を決して捏造してはいけません。厳守すべきルールは、出力する内容に関するものです。<fullName> が実際のカタログ値ではない <standardValue> は、デプロイに失敗します。

よく知られた標準選択リストについては、正規の値（例：Industry、LeadSource、OpportunityStage）をすでに把握しています。名前付きの値が存在するかどうか不明な場合は、稼働中の組織で確認できます。ただし、検索は確認の手順として扱い、最初に必ず呼び出す必要があるものではありません。

• Grounding MCP（利用可能な場合）は、稼働中のメタデータを検索するための search_metadata と query_metadata を提供します。これらは名前付きの値の正確な <fullName>／<label> を確認するためだけに使用し、再現するために全一覧を取得してはいけません。
• CLI の代替手段 — Tooling API を直接クエリします。

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

重要なのは検索ではなく出力です。 存在すると把握している値に対する変更のみを出力してください。未知の値を追加する StandardValueSet を生成するのは幻覚であり、デプロイに失敗します。（これは §3 の最小スコープのルールにも関係します。名前付きの値を確認し、セット全体を列挙しないでください。）

---

5. CustomField からの値セットの参照

選択リスト／複数選択リストの CustomField は、<valueSet> 内の <valueSetName> で値セットを参照します（インラインの <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>  
    </valueSet>
</CustomField>

• GlobalValueSet の場合、<valueSetName> にはベアの開発者名を指定します（例：Priority_Levels）。__gvs を決して追加しないでください。このサフィックスは組織のストレージ上の表示に過ぎません。Metadata API では、デプロイと取得のどちらでもベア名を使用します（§2 を参照）。
• 値セットに紐付けるフィールドでは、インラインの <valueSetDefinition> も宣言してはいけません。どちらか一方を選択してください。

---

6. 検証ルール

エージェントは次の違反を、メタデータを捏造して黙って「修正」するのではなく、拒否して理由を説明する必要があります。

違反	対応／メッセージ
StandardValueSet に新しい値を追加する	拒否します。「標準値セットには新しい値を追加できません。代わりに、GlobalValueSet（再利用可能）または CustomField 上のインライン選択リストを作成してください。」
新しい StandardValueSet 名を作成する	拒否します。名前は標準カタログの付録に含まれている必要があります。該当しない場合は GlobalValueSet です。
値セットの開発者名にスペース／無効な文字が含まれる	スペースをアンダースコアに変換します。先頭は英字で、英数字とアンダースコアのみを使用できます。Priority Levels → Priority_Levels。（これは値セット名とフィールド API 名に適用されます。スペースをそのまま保持する個々の <customValue><fullName> の値には適用されません。）
1 つのセット内で値の fullName が重複している	拒否します。値セット内で各 fullName は一意でなければなりません。
<default>true</default> が複数ある	拒否します。1 セットにつきデフォルト値は最大 1 つです。

誤り — 標準セットへの値の追加

「Industry 選択リストに Cryptocurrency の値を追加してください。」

fullName が Cryptocurrency の <standardValue> を出力してはいけません。標準値セットは固定カタログであると説明し、複数のフィールドで再利用する場合は GlobalValueSet、単一の CustomField で使う場合はインラインの制限付き選択リストを提案してください。

---

7. デプロイの順序

値セットは、それを参照する CustomField より先にデプロイする必要があります。

• 最初に GlobalValueSet／StandardValueSet をデプロイし、その後で <valueSetName> がそれを参照する CustomField をデプロイします。
• まだ存在しない値セットを参照するフィールドは、valueSetName ... does not exist（または「not found」）エラーで失敗します。
• package.xml では、GlobalValueSet は * ワイルドカードをサポートしますが、StandardValueSet はサポートしません。各標準セットのメンバーを個別に列挙してください。

---

8. よくあるデプロイエラー

エラー／症状	原因	修正方法
標準選択リストに値が追加されない	StandardValueSet に値を追加しようとした	標準セットは固定されています。GlobalValueSet またはインラインの CustomField 選択リストを使用してください
Required field missing: sorted	GlobalValueSet に <sorted> がない	<sorted>true</sorted> または <sorted>false</sorted> を追加してください
不明な要素 masterLabel（StandardValueSet）	fullName の代わりに masterLabel を使用した	StandardValueSet のルート要素では、カタログ名を <fullName> に指定します
不明な要素 customValue（StandardValueSet）	standardValue の代わりに customValue を使用した	標準セットでは <standardValue> を使用してください
valueSetName ... does not exist	値セットより先にフィールドをデプロイした、または参照に __gvs を誤って追加した	先に値セットをデプロイしてください。__gvs を付けず、開発者名のみで参照します（§2）
値名が重複している	2 つの <customValue> エントリで同じ fullName を使用している	セット内で各 fullName が一意になるようにしてください（値名にスペースを使用できます。アンダースコアに置き換えないでください）

---

検証チェックリスト

値セット XML を生成する前に、次の点を確認してください。

種類の選択

• これは複数のフィールドで共有する再利用可能なセット（GlobalValueSet）ですか、それとも組み込みの標準選択リスト（StandardValueSet）ですか？
• StandardValueSet の場合、名前は標準カタログの付録に記載されていますか？記載されていない場合は、GlobalValueSet またはインラインの選択リストを使用する必要があります。

GlobalValueSet の確認事項

• ルート要素は名前空間 http://soap.sforce.com/2006/04/metadata を持つ <GlobalValueSet> ですか？
• <masterLabel> はありますか？
• <sorted>（true または false）はありますか？
• <fullName> と <label> をそれぞれ持つ <customValue> が 1 つ以上ありますか（<default>true</default> を持つものは最大 1 つ）？
• ルートに <fullName> はありませんか（名前はファイル名から取得されます）？
• フィールドから参照する場合、<valueSetName> は __gvs 接尾辞を付けず、開発者名のみになっていますか？

StandardValueSet の確認事項（重要）

• 存在することが確認済みの値（既知の標準カタログで確認済みの値、または不明な場合は search_metadata／query_metadata や Tooling API で実際のデータを確認した値）のみを変更していますか。値を作り出していませんか？
• ルート要素は正しい名前空間を持つ <StandardValueSet> ですか？
• ルート要素では、固定されたカタログ名を <fullName> に設定していますか（masterLabel ではありません）？
• 値のエントリには <customValue> ではなく <standardValue> を使用していますか？
• 既存の値のみを変更していますか（新しい fullName は追加していませんか）？
• 新しい値や新しいセット名を追加していませんか？

共通の確認事項

• <default>true</default> を持つ値は最大 1 つですか？
• セット内で、すべての値の fullName が一意ですか？（値名にスペースを使用しても問題ありません。記述どおりに保持してください。アンダースコアを使用するのは、値セットの開発者名とフィールド API 名のみです）
• 値セットは、それを参照する CustomField より先にデプロイされますか？
• ファイル名は意図した名前と一致していますか？