はじめに
「SFDCメタデータ構造チェック Advent Calendar 2026」は、よく使うSalesforceメタデータを1日1種類ずつ取り上げ、retrieveしたときのXML構造と実務上のハマりどころを整理するシリーズです。
Day1は導入回として、すべての回の土台になる package.xml と ソース形式(SFDX) の全体像を整理します。
- 対象APIバージョン:68.0(Winter '27、執筆時点の最新)
- CLI:sf CLI(v2)
※本記事は個人の整理メモです。CLIの挙動は公式ドキュメントに加え、Salesforce CLIの公式リポジトリ(forcedotcom/source-deploy-retrieve、salesforcecli/plugin-deploy-retrieve)のソースで確認しています。実際のSalesforce組織でのretrieve動作は未検証です。 バージョン依存の挙動は利用中のバージョンで再確認してください。
package.xmlとは何か
package.xmlは、Metadata APIに「どの型の、どのコンポーネントを」retrieve / deployするかを伝える マニフェスト(目録) です。sf CLIはこれを元に組織からメタデータを取得し、ローカルには ソース形式 で保存します。
package.xmlの構造
最小構成はこれだけです。
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types>
<members>*</members>
<name>ApexClass</name>
</types>
<types>
<members>Account</members>
<members>MyObject__c</members>
<name>CustomObject</name>
</types>
<version>68.0</version>
</Package>
| 要素 | 役割 | メモ |
|---|---|---|
Package |
ルート要素 | 名前空間 http://soap.sforce.com/2006/04/metadata
|
types |
メタデータ型ごとのまとまり | 型の数だけ繰り返す |
members |
取得するコンポーネントのフルネーム |
* でワイルドカード(対応型のみ) |
name |
メタデータ型名 |
CustomObject、ApexClass など |
version |
retrieve / deployで使うメタデータのAPIバージョン | CLI側の値との関係は後述 |
👉 members の書式は型ごとに違います(項目なら Account.Foo__c、レポートなら MyFolder/MyReport)。
Metadata API形式とソース形式の違い
ローカルに置く形式は2種類あります。
| 観点 | Metadata API形式(mdapi) | ソース形式(SFDX) |
|---|---|---|
| ルート |
package.xml を含むフォルダ |
force-app/main/default/ など |
| CustomObject |
Account.object 1ファイルに項目等を内包 |
objects/Account/ 配下の fields/、listViews/、recordTypes/、validationRules/ などへ 分解
|
| XMLのみの型 | Account.object |
Account.object-meta.xml(-meta.xml 付き) |
| Apex等 |
.cls + .cls-meta.xml
|
同じ |
CustomObjectの分解先は、businessProcesses / compactLayouts / fields / fieldSets / indexes / listViews / recordTypes / sharingReasons / validationRules / webLinks の10種類です(CLIのメタデータレジストリ定義より)。
👉 分解のおかげで、項目追加のPRは fields/Foo__c.field-meta.xml 1ファイルの差分になり、レビューしやすくなります。
主要コマンド(sf CLI v2)
# ローカルのソースからpackage.xmlを生成
sf project generate manifest --source-dir force-app --output-dir manifest
# 組織に存在するメタデータからpackage.xmlを生成
sf project generate manifest --from-org my-org --output-dir manifest
# package.xmlを指定してソース形式でretrieve
sf project retrieve start --manifest manifest/package.xml --target-org my-org
# ソース形式 → Metadata API形式(出力先に package.xml も生成される)
sf project convert source --root-dir force-app --output-dir mdapi_out
# Metadata API形式 → ソース形式(--root-dir は package.xml があるフォルダを指す)
sf project convert mdapi --root-dir mdapi_out --output-dir force-app
Metadata API形式のまま取りたい場合は --target-metadata-dir を付けます。
# Metadata API形式でretrieveし、zipを展開する
sf project retrieve start --manifest manifest/package.xml --target-org my-org --target-metadata-dir mdapi_retrieved --unzip
このとき、zipは unpackaged.zip という名前で保存され、--unzip で mdapi_retrieved/unpackaged/unpackaged/ に展開されます(unpackaged が二重になる点に注意)。続けて convert mdapi する場合は --root-dir mdapi_retrieved/unpackaged/unpackaged を指定します。
ハマりどころ・Tips
1. 標準オブジェクトは * では取れない
CustomObject の * で取れるのはカスタムオブジェクト側だけで、Account などの 標準オブジェクトは含まれません。標準オブジェクトやその上のカスタム項目が必要なら、<members>Account</members> のように 明示指定 します。標準オブジェクトもカスタムオブジェクトと同じ <name>CustomObject</name> の types に書きます。
また、フォルダ型(Report、Dashboard、EmailTemplate、Document)は フォルダ名/名前 での列挙が基本です。たとえばReportは、公式ドキュメントで「package.xmlで * は使えない」と明記されています。* 対応可否は、Metadata API Developer Guideの型ごとのページで確認するのが確実です。
2. Profileは「一緒に取ったもの」によって取得内容が変わる
Profileをretrieveしたときに返る内容のうち、FLSやオブジェクト権限など他のコンポーネントに紐づく設定は、同じリクエストで一緒に取得したコンポーネント に左右されます。
たとえば項目レベルセキュリティ(FLS)は、同じリクエストで取得したオブジェクトの項目に関する設定が対象になります。Profileだけを取得すると、FLSなどが含まれない場合があります。
一方、PermissionSetは挙動が異なります。 API 40.0以降では、PermissionSetをretrieveすると、同じリクエストで関連コンポーネントを指定しなくても、そのPermissionSetのメタデータを取得できます。
※API 39.0以前のPermissionSetには、同時取得したコンポーネントに依存する仕様がありました。
この違いはDay12(PermissionSet)・Day14(Profile)で詳しく扱います。
3. version とCLIのAPIバージョンは別物として意識する
sf CLIのretrieveでは、2種類のバージョンが別々に決まります。
-
メタデータのバージョン:
--manifestを使う場合は、package.xmlの<version>の値が使われます。返ってくるXMLの形(要素の有無)はこちらに依存します -
SOAP APIのバージョン:リクエストに使うAPIのバージョンです。
--api-versionで上書きできます。指定しなければorg-api-versionの設定値、それもなければ接続先組織がサポートする最新バージョンが使われます
package.xmlに <version> がない場合や --source-dir 指定時は、sfdx-project.json の sourceApiVersion がメタデータのバージョンとして使われます。それもなければ、SOAP APIと同じバージョンになります。retrieve時には次のようなログが出るので、両方の値を確認する習慣をつけると安心です。
Retrieving v68.0 metadata from user@example.com using the v68.0 SOAP API
※上記の解決順は、執筆時点のCLIのソースコードで確認したものです。CLIのバージョンによって細部が変わる可能性があるため、package.xmlには <version> を明示しておくのがおすすめです。
4. 分解のされ方は型ごとに違う
CustomLabelsは、デフォルトでは分解されず、labels/CustomLabels.labels-meta.xml の1ファイルに集約されます。PermissionSetも、デフォルトでは1ファイルです。
一部の型は、sfdx-project.json の sourceBehaviorOptions で分解を オプトイン できます。執筆時点のCLIで指定できる値は次のとおりで、いずれも名前に Beta が付いています。
-
decomposePermissionSetBeta/decomposePermissionSetBeta2 -
decomposeCustomLabelsBeta/decomposeCustomLabelsBeta2 decomposeSharingRulesBetadecomposeWorkflowBetadecomposeExternalServiceRegistrationBeta
有効化には sf project convert source-behavior --behavior <値> を使います。このコマンドは sfdx-project.json を書き換え、既存のローカルファイルも変換します。まず --dry-run で影響を確認するのが安全です。
retrieve用のpackage.xml断片
シリーズで使う「まず一通り取る」用の断片です。
※以下はpackage.xmlのtypes部分の抜粋です。実際に利用する際は、Packageルート要素とversionを含めてください。
<types>
<members>*</members>
<members>Account</members>
<members>Contact</members>
<name>CustomObject</name>
</types>
<types>
<members>*</members>
<name>ApexClass</name>
</types>
<types>
<members>*</members>
<name>PermissionSet</name>
</types>
👉 * と標準オブジェクト名は、同じ types 内に併記できます(CustomObjectは「ワイルドカードと名前の併用」に対応する型です)。
まとめ
- package.xmlは
types(members+name)とversionだけのシンプルな目録。ただしmembersの書式とワイルドカード対応は型ごとに違う - 標準オブジェクトは
*に含まれないため明示指定が必要 - ソース形式はCustomObjectなどを分解し、XMLのみの型に
-meta.xmlを付ける。形式間はsf project convert source / mdapiで行き来できる
シリーズ目次(予定)
| Day | テーマ | Day | テーマ |
|---|---|---|---|
| 1 | package.xmlとソース形式の全体像(本記事) | 14 | Profile |
| 2 | CustomObject | 15 | Flow |
| 3 | CustomField | 16 | ApexClass / ApexTrigger |
| 4 | RecordType | 17 | LightningComponentBundle |
| 5 | ValidationRule | 18 | CustomLabels |
| 6 | ListView | 19 | CustomMetadata(カスタムメタデータ型) |
| 7 | Layout | 20 | GlobalValueSet / StandardValueSet |
| 8 | CompactLayout | 21 | EmailTemplate(フォルダ型) |
| 9 | FlexiPage(Lightningページ) | 22 | Report / Dashboard |
| 10 | CustomTab | 23 | SharingRules |
| 11 | CustomApplication | 24 | NamedCredential / ExternalCredential |
| 12 | PermissionSet | 25 | destructiveChangesと総まとめ |
| 13 | PermissionSetGroup |
※予定は変更になる場合があります。
次回Day2は CustomObject です。分解後の objects/<オブジェクト名>/ 配下と、本体の *.object-meta.xml に残る要素を見ていきます。
初めての方向け:ざっくり理解
Salesforceのメタデータを扱う際によく登場する3つの用語を、簡単に整理します。
- package.xml(パッケージ):Salesforceから取得したい設定情報を指定する「目録(リスト)」です。例えば、どのオブジェクトやApexクラスを取得するかを記載します。
- retrieve(リトリーブ):Salesforce組織にある設定情報を、ローカル環境(自分のPCなど)へ取得する操作です。
- ソース形式(SFDX):取得した設定情報を、種類ごとにファイルやフォルダへ分けて保存する形式です。変更箇所を確認・管理しやすいのが特徴です。
例えば、「案件」オブジェクトの設定を取得する場合は、次の流れになります。
- package.xmlで取得したい設定情報を指定する
- retrieveでSalesforceから設定情報を取得する
- ソース形式でファイルやフォルダに整理して保存する
つまり、「package.xmlで指定 → retrieveで取得 → ソース形式で保存」という関係です。
この流れを覚えておくと、Salesforceの設定情報をファイルとして管理する仕組みが理解しやすくなります。
参考
- Metadata API Developer Guide
- Metadata API Developer Guide:Sample package.xml Manifest Files
- Metadata API Developer Guide:Metadata Types
- Salesforce DX Developer Guide:Salesforce DX Project Structure and Source Format
- Salesforce CLI Command Reference:project Commands
- Metadata API Developer Guide:Profile
- Metadata API Developer Guide:PermissionSet
- Metadata API Developer Guide:Report
- Salesforce DX Developer Guide:Salesforce DX Project Configuration(sourceBehaviorOptions)
- GitHub:forcedotcom/source-deploy-retrieve(メタデータレジストリ、APIバージョン解決ロジック)
-
GitHub:salesforcecli/plugin-deploy-retrieve(
project retrieve/convert/generate manifestコマンド)


