getting-metadata-api-context

Salesforce Metadata API スキル

このスキルでは、604 種類すべての Salesforce Metadata API タイプに関する包括的なドキュメントを提供します。このスキルを使って、Salesforce DX プロジェクトで Salesforce メタデータ XML ファイルを作成、理解、変更できます。

概要

Salesforce Metadata API を使用すると、組織のカスタマイズを取得、デプロイ、作成、更新、削除できます。このスキルでは、各メタデータタイプについて、以下を含む詳細なドキュメントを参照できます。

• フィールド定義とデータ型
• 必須フィールドと任意フィールド
• WSDL スキーマ定義
• XML のサンプル構造
• ファイルの命名規則
• Salesforce DX プロジェクト内のディレクトリの場所

このスキルの使用方法

⚡ 重要：セクション単位で読み込む

JSON ファイル全体ではなく、必要なセクションだけを必ず読み込んでください。

重要：data/metadata_api/*.json ファイルでは、jq またはプログラムによる JSON 解析を常に使用して、必要なセクションだけを抽出してください。 Read、cat、read_file、またはファイル全体を読み込むその他のツールを使って、これらのファイルを丸ごと読み込まないでください。ファイルには冗長な WSDL セグメントなどのセクションが含まれており、トークンの 60～80％を無駄に消費します。（この SKILL.md やインデックス表のような小さなファイルを Read で読み込むのは問題ありません。このルールは、大きなメタデータタイプの JSON ファイルにのみ適用されます。）

各 JSON ファイルには複数のセクション（fields、description、wsdl_segment など）が含まれています。ほとんどの用途では、必要なのは 1～2 セクションだけです。

• フィールド定義の場合：fields セクションだけを読み込みます
• 用途を理解する場合：description セクションだけを読み込みます
• XML の例の場合：declarative_metadata_sample_definition セクションだけを読み込みます
• デフォルトでは読み込み不要：wsdl_segment（冗長なスキーマ）、file_information、directory_location

これにより、ファイルごとのトークン消費を 60～80％削減できます。

クイックスタート

特定のメタデータタイプについて情報を得るには、次のようにします。

1. セクションを指定する（最適）：「CustomObject.json の 'fields' セクションだけを表示してください」
2. 複数のセクションを指定する：「Flow.json の 'fields' と 'description' を表示してください」
3. ファイル全体の読み込みを避ける：「CustomObject メタデータタイプについて」と依頼せず、セクションを指定してください

クエリの例（セクション単位）

• ✅ 「CustomObject.json の 'fields' セクションだけを表示してください」
• ✅ 「Profile.json の 'fields' セクションにはどのフィールドがありますか？」
• ✅ 「Flow.json の 'description' と 'fields' セクションを読み込んでください」
• ✅ 「ApexClass.json の 'declarative_metadata_sample_definition' だけを提示してください」
• ❌ 「CustomObject メタデータタイプを表示してください」（範囲が広すぎます。ファイル全体が対象になります）
• ❌ 「CustomObject.json を読み込んでください」（不要な WSDL やその他のセクションも含まれます）

JSON ファイルの構造

各メタデータタイプは、次の構造を持つ JSON ファイルとして data/metadata_api/ に格納されています。

{
  "sections": ["title", "description", "fields", "wsdl_segment", ...],
  "title": "MetadataTypeName - Metadata API",
  "description": "Plain-text description of the metadata type.",
  "fields": {
    "fieldName": {
      "type": "string",
      "description": "Field description",
      "required": true
    }
  },
  "file_information": ".object",
  "directory_location": "objects",
  "wsdl_segment": "<xsd:complexType>...</xsd:complexType>",
  "declarative_metadata_sample_definition": [
    {
      "description": "Example description",
      "code": "<?xml version=\"1.0\"?>\n<MetadataType>...\n</MetadataType>"
    }
  ]
}

注： 文字列値（title、description、file_information、directory_location、wsdl_segment）は、Markdown の見出し（#／##）やコードフェンスのないプレーンテキストとして格納されています。file_information にはファイルの接尾辞（例：.object、.ai）だけが、directory_location には SFDX フォルダー名（例：objects、aiApplications）だけが格納されています。

利用可能なセクション

sections 配列は、各ファイルに含まれるトップレベルのキーを示します。一般的なセクションは次のとおりです。

• title：メタデータ型名とヘッダー
• description：メタデータ型が表す内容
• fields：その型独自のフィールドと、各フィールドの型および説明
• sub_types：（複合型のみ）参照されるサブタイプ名 → そのサブタイプのフィールドのマップ。例：Flow → sub_types.FlowActionCall
• file_information：ファイル名の規則と拡張子
• directory_location：SFDX プロジェクト内でのファイルの保存場所
• wsdl_segment：WSDL の XML スキーマ定義
• declarative_metadata_sample_definition：XML コードの例

メタデータ型によっては、その機能に固有の追加セクションがあります。詳しくは、インデックステーブルをご覧ください。

詳細情報： トークン最適化が重要な理由の背景、実際の使用例、一般的なワークフロー、全セクションの用語集、バージョン管理とサポートに関する注意事項については、references/usage_guide.mdをご覧ください。必要な場合にのみ、Read ツールで読み込んでください。

トークン最適化の戦略

重要：トークンの使用量とコストを最小限に抑えるには、次の点を守ってください。

1. コーパス全体ではなく、必要な特定のメタデータ型のみを読み込みます
2. 各ファイル全体ではなく、必要な特定のセクションのみを読み込みます

セクション単位の読み込み（ベストプラクティス）

⚠️ 重大な警告：これらの JSON ファイルに read_file ツール（またはファイル全体を読み込むツール）を使用しないでください！

read_file はファイル全体の内容をコンテキストに読み込むため、セクション単位で読み込む目的が損なわれます。不要な WSDL セグメントや冗長なセクションの読み込みにより、トークン予算の 60～80％が無駄になります。（この SKILL.md やインデックステーブルのような小さなファイルに Read を使用するのは問題ありません。このルールは、大きなメタデータ型 JSON ファイルにのみ適用されます。）

方法：ファイル全体を読み込むツールではなく、コードを使って JSON ファイルをプログラムで解析し、必要なセクションのみを抽出します。

実際に動作するコード例：

複数の言語で、完全に動作するコード例を用意しています。

• Python：examples/python_section_loading.py — セクション抽出を伴う json.load() の使用例
• JavaScript/Node.js：examples/javascript_section_loading.js — セクション抽出を伴う JSON.parse() の使用例
• Bash + jq：examples/bash_section_loading.sh — jq によるコマンドライン JSON 処理の例

詳しい説明と使用手順については、examples/README.mdをご覧ください。

基本的な手順（使用する言語に合わせて調整してください）：

1. JSON ファイルを読み込みます
2. データ構造に解析します
3. 必要なセクション（例：fields、description）のみを抽出します
4. 冗長なセクション（wsdl_segment、declarative_metadata_sample_definition）は無視します

避けるべきこと

❌ これらの JSON ファイルに read_file ツールを絶対に使用しないでください：

read_file data/metadata_api/CustomObject.json  # Loads entire file into context!
read_file data/metadata_api/Flow.json          # Wastes 60-80% tokens!

❌ ファイルをすべて読み込まないでください：

read_file data/metadata_api/*.json  # This loads ~15MB of data!

トークンへの影響：

• セクション単位：メタデータ型あたり 50～200 トークン
• ファイル全体：メタデータ型あたり 500～2000 トークン
• 削減量：ファイルあたり 60～80％

複数の型を読み込む場合

• 関連する型：CustomObject + CustomField + ValidationRule
• 権限セット：Profile + PermissionSet + PermissionSetGroup
• UI コンポーネント：Layout + CompactLayout + QuickAction
• 自動化：Flow + WorkflowRule + ApexTrigger

特定のセクションを読み込むタイミング（強く推奨）

多くのメタデータタイプには、大きな WSDL セグメントや広範なフィールド一覧が含まれています。ファイル全体を読み込むのではなく、各 JSON ファイルから必要な特定のセクションだけを必ず読み込んでください。

1. まず、利用可能なセクションを確認します。JSON の sections 配列だけを読み込みます
2. 必要なセクションだけを抽出します（例：フィールド定義には fields、概要には description）
3. スキーマ検証が特に必要な場合を除き、WSDL セグメントはスキップします
4. 完全な XML の例が必要な場合を除き、declarative_metadata_sample_definition はスキップします

この方法では、冗長な WSDL 定義や長い例を除外することで、ファイルごとのトークン消費量を 60～80% 削減できます。

このスキルを使用するための概念的なアプローチ

ステップ 1：必要なことを特定する

次の点を自問してください。

• 何を作成または変更しようとしていますか？
• どの Salesforce メタデータタイプを扱っていますか？
• 具体的にどの情報が必要ですか？
  • フィールド定義だけですか？→ fields セクションを読み込みます
  • 何をするものか知りたいですか？→ description セクションを読み込みます
  • XML の例ですか？→ declarative_metadata_sample_definition セクションを読み込みます
  • スキーマ検証ですか？→ wsdl_segment セクションを読み込みます（必要になることはほとんどありません）

ステップ 2：適切なタイプを見つける

次のいずれかの方法を使用します。

• 直接参照：タイプ名がわかっている場合（例：「CustomObject」）
• インデックス検索：関連するタイプについて references/metadata_index_table.md を確認します
• 一般的なタイプ：以下の「クイックリファレンス：一般的なメタデータタイプ」セクションを参照します

ステップ 3：選択して読み込む（セクション別）⚡

セクション読み込みの判断ツリー：

Need field definitions?
  → Load ONLY 'fields' section (~50-200 tokens)

Need to understand what the type does?
  → Load ONLY 'description' section (~20-100 tokens)

Need XML structure example?
  → Load ONLY 'declarative_metadata_sample_definition' (~100-300 tokens)

Need all three?
  → Load 'fields' + 'description' + 'declarative_metadata_sample_definition'
  → Still skip 'wsdl_segment', 'file_information', 'directory_location'
  → Savings: ~60-70% vs loading entire file

Need schema validation?
  → Only then load 'wsdl_segment' (this is verbose)

リクエスト形式：

• 単一のセクション（最適）：「ApexClass.json から 'fields' セクションだけを表示してください」
• 複数のセクション：「CustomObject.json から 'fields' と 'description' を読み込んでください」
• 冗長なセクションをスキップ：明示的に必要とされない限り、wsdl_segment は読み込まないでください

ステップ 4：コードに適用する

読み込んだ情報を次の用途に使用します。

• 新しいメタデータ XML ファイルを作成する
• プロジェクト内の既存ファイルを理解する
• フィールド名と型を検証する
• 適切な名前空間を含む正しい XML 構造を生成する

ファイルの場所

すべてのメタデータタイプ JSON ファイルは、次の場所にあります。

data/metadata_api/
├── CustomObject.json
├── Flow.json
├── ApexClass.json
├── Profile.json
└── ... (600 more files)

パスの解決

このスキルでは、ファイルを次のように指定します。

• 絶対パス：data/metadata_api/CustomObject.json
• スキルルートからの相対パス：./data/metadata_api/CustomObject.json

スキルは、作業ディレクトリに基づいてパスを自動的に解決します。

メタデータファイル生成の要件

有効でデプロイ可能なファイルを生成するため、Salesforce メタデータ XML ファイルを生成する際は、次の要件に従ってください。

XML 構造の要件

すべてのメタデータファイルは、次の要件を満たす必要があります。

1. XML 宣言を含める：

   <?xml version="1.0" encoding="UTF-8"?>
   

2. 正しい名前空間を使用する：

   <CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
   

3. ルート要素をメタデータタイプに一致させる：

   • CustomObject → <CustomObject>
   • Flow → <Flow>
   • Profile → <Profile>
   • など

名前空間の宣言

名前空間は必須で、次のとおり正確に指定する必要があります。

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

正しい例：

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">

誤った例：

<CustomObject>  
<CustomObject xmlns="http://salesforce.com/metadata">  

必須フィールドと任意フィールド

メタデータの種類ごとに、フィールドの要件は異なります。

• スキーマ上必須（JSON で required: true）：WSDL でそのフィールドが必須として指定されています。
• 実質的に必須（必須と指定されていないものの、実際には必要）：多くの場合、WSDL で必須とされるフィールドは、作成時の実際の要件より少なくなっています。代表例は CustomObject です。JSON では externalDataSource、externalName、nameField のみが required: true とされています（最初の 2 つは外部オブジェクト固有の例外です）が、通常の __c CustomObject をデプロイするには、label、pluralLabel、deploymentStatus、sharingModel も必要です。必ず declarative_metadata_sample_definition の例と照合してください。
• 条件付きで必須：特定の機能が有効な場合にのみ必須となるフィールドもあります。
• 任意：ほとんどのフィールドは、必要なければ省略できます。

CustomObject の例（注：実際の作成には required: true で指定されているフィールド以外も必要です）：

{
  "fields": {
    "nameField": {
      "type": "CustomField",
      "description": "The name field for the custom object",
      "required": true
    },
    "label": {
      "type": "string",
      "description": "The label for the custom object (effectively required for normal __c objects)",
      "required": false
    },
    "sharingModel": {
      "type": "SharingModel (enumeration)",
      "description": "The sharing model for the object (effectively required for normal __c objects)",
      "required": false
    },
    "enableHistory": {
      "type": "boolean",
      "description": "Enable field history tracking",
      "required": false
    }
  }
}

検証のヒント

デプロイする前に、次の点を確認してください。

1. XML 構文を検証する：整形式の XML であることを確認します（タグが一致し、適切にネストされていること）。
2. 必須フィールドを確認する：すべての必須フィールドが指定されていることを確認します。
3. 名前空間を確認する：名前空間が正確であることを確認します。
4. フィールドの型をテストする：フィールド値が想定される型と一致していることを確認します。
5. Salesforce CLI を使用する：sf project deploy validate を実行して、エラーを検出します。

**詳細：**フィールド型から XML へのマッピング表、ファイル名／2 ファイル構成／子型の規則、整形式ファイルの完全な例については、references/usage_guide.md を参照してください。

重複する型名と曖昧な型名

一部の Metadata API 型名は、Enterprise/Data API または Tooling API のオブジェクト名としても使われています。例として、ApexClass、ApexTrigger、CustomField、CustomObject、EmailTemplate、Layout、Profile、PermissionSet、RecordType、StaticResource、WebLink、ValidationRule、Flow があります。

プロンプトが曖昧な場合（例：「Profile について教えて」や「ApexClass にはどのフィールドがありますか」）、次のどれを求めているかユーザーに確認してください。

1. ソース／デプロイ用の作成に使う Metadata API の XML 構造（このスキル。例：.profile-meta.xml、.cls-meta.xml）。
2. Enterprise/Data API の実行時 sObject／レコード参照（現時点で専用スキルはありません。Salesforce API ファミリールーターにフォールバックしてください）。
3. Tooling API の開発者向けツールレコード参照（現時点で専用スキルはありません。Salesforce API ファミリールーターにフォールバックしてください）。

確認せずに曖昧さを解消できる場合が多いヒューリスティック：

• package.xml、force-app/、sfdx、.meta.xml、「deploy」、「retrieve」、「authoring」、「blueprint」、「template」、「class definition」、またはデプロイの意味での「permissions」への言及 → Metadata API（このスキル）。
• 「X にはどのフィールドがあるか」／「どの列」／「DML」／「SOQL」／「query」／「REST」／「sObject」／「record」／「runtime」 → Enterprise/Data API または Tooling API（別のスキル）。
• Tooling 固有の手がかり：「Tooling API」、ApexCodeCoverage、EntityDefinition、TraceFlag、「code coverage」、「compile errors」、SymbolTable、デバッグログ → Tooling API。

手がかりがない場合のデフォルトルール：プロンプトに上記の手がかりがなく、このスキル（getting-metadata-api-context）が名前で直接呼び出された場合は、Metadata API の解釈をデフォルトとし、その前提をユーザーに明示してください（例：「.cls-meta.xml の作成に使う Metadata API の型として解釈しています。Tooling API のレコード、または Enterprise/Data の sObject を意図している場合はお知らせください」）。スキルが呼び出されたという状況自体が、作成／デプロイの意図を示す手がかりです。

トラブルシューティング

ファイルが見つかりません

問題: メタデータ型ファイルが見つかりません

解決策:

• ファイル名は区切り文字を使わない大文字始まりのパスカルケースです（例：CustomObject.json。customobject.json、Custom_Object.json、Custom-Object.jsonではありません）。
• 「見つからない」と判断する前に、references/metadata_index_table.mdを確認してください。インデックスに対して、次の2段階の復旧アルゴリズムを使用します。
  1. 正規化して部分一致を検索（大文字・小文字や区切り文字の違いに対応）：英数字以外の文字を取り除き、検索語と各インデックスエントリーを小文字に変換してから、部分一致を検索します。次のように解決されます：customobject、Custom_Object、Custom-Object → CustomObject。
  2. 見つからない場合は、あいまい一致を検索（文字抜けの誤入力に対応）：difflib.get_close_matches(query_normalized, index_normalized, n=3, cutoff=0.7)またはレーベンシュタイン距離が2以下のものを使用します。次のように解決されます：customfeld → CustomField、apxclass → ApexClass。部分一致だけでは、文字の削除には対応できません。
• 複数候補がある場合の判定方法：正規化して部分一致を検索した結果、複数の候補がある場合（例：customobjectがCustomObjectとCustomObjectTranslationの両方に一致）、正規化した長さが正規化した検索語の長さと等しいエントリーを優先します。それ以外の場合は、最も短い一致を優先します。
• 一部の型には、予想外の命名規則があります（アンダースコア、スペース、「OAuth」のような略語を使わないなど）。インデックスを正としてください。

SOAP エンベロープ／ヘッダー型（意図的に最小限）

次の2つの関連パターンを認識してください。

1. 結果型（AsyncResult、SaveResult、DeleteResult、UpsertResult、Error、DescribeMetadataResultなど） — fieldsは空で、wsdl_segmentに値が設定されています。これらはSOAPレスポンスのラッパーであり、スキーマ全体はwsdl_segmentにあります。構造が必要な場合は、そのセクションを参照してください。デプロイ可能なソースファイルではありません。
2. SOAPリクエストヘッダー（AllOrNoneHeader、SessionHeader、CallOptions、DebuggingHeader、OwnerChangeOptionsなど） — fieldsには最小限の項目が1～2個あり、wsdl_segmentはありません。これらはSOAPリクエストの動作を設定するものであり、呼び出し時のオプションであって、作成またはデプロイするメタデータではありません。

いずれの場合も、JSON出力が簡素なのは正しい状態です。これらの型にはソースファイル形式がないため、.AsyncResult-meta.xmlを作成しようとしないでください。

セクションがありません

問題: JSONファイルに想定したセクションがありません

解決策:

• sections配列を確認して、利用可能なセクションを確認してください
• すべてのメタデータ型にすべてのセクションがあるわけではありません
• セクションによっては型固有のものがあります（インデックステーブルに記載）

フィールド情報が不完全です

問題: フィールド定義に詳細情報がありません

解決策:

• 完全なスキーマ定義はwsdl_segmentで確認してください
• 一部のフィールドには、WSDLで定義された複合型があります
• 列挙値については、Salesforceのドキュメントと照合してください

サブタイプポインターをたどる（例：ProfileObjectPermissions[]）

fieldsセクションにProfileObjectPermissions[]、LayoutItem[]、ApprovalStep[]のような複合型名がある場合、そのネストされた型のサブフィールドはfieldsセクションにはありません。該当する複合型のwsdl_segmentにあります。このスキルの「デフォルトではwsdl_segmentをスキップする」というルールは、単純なフィールドの処理でトークンを節約するためのものです。ネストされた型の場合は、詳細を確認する必要があります。

実例 — ProfileのobjectPermissionsのサブフィールドを確認します。

# 1. Get the field type name from the fields section
jq '.fields.objectPermissions' data/metadata_api/Profile.json
# → {"type": "ProfileObjectPermissions[]", ...}

# 2. Pull just the matching complexType from wsdl_segment using grep -A
jq -r '.wsdl_segment' data/metadata_api/Profile.json   | grep -A 30 'complexType name="ProfileObjectPermissions"'

grep -A Nを使うと、トークンコストを約150トークンに抑えられます。大きな型では5Kトークンを超えることがあるwsdl_segment全体を読み込まずに済みます。fieldsにFoo[]型があり、Fooのサブフィールドが必要な場合は、いつでもこのパターンを使用してください。

XML生成エラー

問題: 生成したXMLの検証に失敗します

解決策:

• 名前空間が正確に次のとおりであることを確認してください：http://soap.sforce.com/2006/04/metadata
• 必須フィールドがすべて含まれていることを確認してください
• フィールド値が想定された型と一致することを確認してください
• XML構文（終了タグ、正しいネスト）を検証してください

デプロイの失敗

問題：メタデータファイルをデプロイできません

解決策：

• まず sf project deploy validate を実行します
• Salesforce API バージョンとの互換性を確認します
• ファイル名が命名規則に従っていることを確認します
• ディレクトリ構造が SFDX 形式に準拠していることを確認します

クイックリファレンス：よく使われるメタデータ型

以下は、最もよく使われるメタデータ型です。

• CustomObject：フィールド、リレーションシップ、設定など、カスタム sObject のスキーマを定義します
• Flow：要素とコネクタを配置したビジュアルキャンバスを使用して、ビジネスプロセスを自動化します
• ApexClass：コンパイル済みの Apex サーバーサイドクラスです。本文、API バージョン、ステータスを含みます
• ApexTrigger：特定の sObject で DML イベントの前後に実行される Apex コードです
• Profile：ユーザープロファイルのオブジェクト／項目の権限、アプリの表示、ログイン設定を制御します
• PermissionSet：プロファイルとは独立してユーザーに付与される、追加の権限セットです
• CustomField：型、選択リスト値、数式など、標準オブジェクトまたはカスタムオブジェクトの項目を定義します
• Layout：レコードの詳細／編集ページにおける項目と関連リストの配置を制御します
• ValidationRule：数式条件が true の場合に保存を防ぎ、データ品質を維持します
• ApexPage：コントローラー参照とマークアップを含む、Visualforce ページ定義です
• ApexComponent：ページに埋め込める再利用可能な Visualforce コンポーネントです
• CustomTab：カスタムオブジェクト、Visualforce ページ、または Web URL を指すタブを定義します
• CustomApplication：アプリのタブバー、ナビゲーション項目、ブランディングを定義します
• LightningComponentBundle：JS、HTML、メタデータ記述子を含む LWC バンドルです
• AuraDefinitionBundle：コンポーネント、コントローラー、ヘルパーファイルを含む Aura（Lightning）コンポーネントバンドルです
• StaticResource：Visualforce と LWC からアクセスできるアップロード済みファイル（JS、CSS、画像、ZIP）です
• EmailTemplate：ワークフロールール、Process Builder、または Apex で使用するメールテンプレートです
• Report：フィルター、グループ化、列を含む保存済みレポート定義です
• Dashboard：レポートを基盤とするダッシュボードコンポーネントのコレクションです

すべてのメタデータ型の一覧については、インデックステーブルを参照してください。