はじめに
「SFDCメタデータ構造チェック Advent Calendar 2026」は、よく使うメタデータを1日1種類ずつ、retrieve結果のXML構造とハマりどころで整理するシリーズです。
Day2は CustomObject です。本体の object-meta.xml と、フォルダ分解される子メタデータの関係に絞ります(項目の詳細は次回)。
- 対象APIバージョン: v68.0(Winter '27、執筆時点の最新)
- CLI: sf CLI(v2)
※個人の整理メモです。XMLサンプルはDeveloper Guideの定義とretrieve結果の一般的な形から構成しています。要素の有無や順序はAPIバージョン・組織設定で変わるため、手元のretrieve結果で確認してください。
CustomObjectとは
CustomObjectは、カスタムオブジェクト(Xxx__c)の定義を表すメタデータ型です。表示ラベル、名前項目、共有モデル、レポートや検索の可否など、Setupの「オブジェクトの設定」で決める内容が入ります。
標準オブジェクト(Account など)も同じ型で扱えますが、変更できる設定は限られ、retrieveされる内容も一部異なります。
初めての方向け:ざっくり理解
詳細に入る前に、Salesforceのメタデータに初めて触れる方向けに全体像を整理します。
CustomObjectは、Salesforceのオブジェクトの「設計図」にあたるものです。
例えば「案件」というカスタムオブジェクトを作ると、次のような設定が管理されます。
- オブジェクト本体:表示名、共有設定、検索・レポートの利用可否など
- カスタム項目:「案件名」「ステータス」などの項目の定義
- 関連する設定:リストビューや入力規則など
Salesforceからソース形式で取得すると、これらは1つのXMLではなく、複数のファイルに分かれて保存されます。
また、ユーザーごとのアクセス権限や画面レイアウトなどは、別のメタデータで管理されます。
つまり、CustomObjectを理解するポイントは、「オブジェクトの設定が、どのファイルに保存されているか」を知ることです。
この関係を押さえておくと、設定変更やdeploy(Salesforce環境への反映)の際に、確認すべきファイルを見つけやすくなります。
ソース形式でのファイルパス
ソース形式(sf project retrieve start の既定)では、オブジェクト1つがフォルダ1つになり、本体は次のパスに置かれます。
force-app/main/default/objects/Project__c/Project__c.object-meta.xml
mdapi形式では項目なども1つの .object に入れ子でしたが、ソース形式では 子要素ごとにフォルダ・ファイルへ分解 されます。
ほかに businessProcesses / fieldSets / sharingReasons などもあります。
👉 ページレイアウト(Layout)やApexトリガは objects/ の外にある別の型です。
本体XMLのサンプル
名前項目をテキスト型としたカスタムオブジェクトについて、本体XMLの構造を示す例です。実組織のretrieve結果そのものではなく、説明用に構成しています。設定値は一例で、actionOverrides の一部は省略しています。構造理解を目的とした例のため、そのままのdeploy成功を保証するものではありません。
<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
<actionOverrides>
<actionName>View</actionName>
<type>Default</type>
</actionOverrides>
<!-- 他の actionOverrides は省略 -->
<allowInChatterGroups>false</allowInChatterGroups>
<compactLayoutAssignment>SYSTEM</compactLayoutAssignment>
<deploymentStatus>Deployed</deploymentStatus>
<enableActivities>false</enableActivities>
<enableBulkApi>true</enableBulkApi>
<enableFeeds>false</enableFeeds>
<enableHistory>true</enableHistory>
<enableLicensing>false</enableLicensing>
<enableReports>true</enableReports>
<enableSearch>true</enableSearch>
<enableSharing>true</enableSharing>
<enableStreamingApi>true</enableStreamingApi>
<externalSharingModel>Private</externalSharingModel>
<label>案件</label>
<nameField>
<label>案件名</label>
<trackHistory>false</trackHistory>
<type>Text</type>
</nameField>
<pluralLabel>案件</pluralLabel>
<searchLayouts></searchLayouts>
<sharingModel>ReadWrite</sharingModel>
<visibility>Public</visibility>
</CustomObject>
要素はおおむねアルファベット順に出力されます。
押さえるべき主要要素
| 要素 | 内容 | メモ |
|---|---|---|
label / pluralLabel
|
単数・複数の表示ラベル | 日本語では同じ値になりがち |
nameField |
名前項目 |
Text か AutoNumber(後者は displayFormat を持つ) |
deploymentStatus |
Deployed / InDevelopment
|
開発中は一般ユーザに見えない |
sharingModel |
組織の共有設定(内部) |
Private / Read / ReadWrite / ControlledByParent 等 |
externalSharingModel |
外部ユーザ向け既定アクセス | 内部より緩くはできない |
enableHistory |
項目履歴管理 | 対象項目は各項目の trackHistory
|
enableReports / enableSearch
|
レポート・検索の可否 | 検索無効だとグローバル検索に出ない |
enableActivities |
活動の許可 | Metadata APIによる更新時の過去の問題報告あり(Tips 4) |
enableBulkApi / enableSharing / enableStreamingApi
|
「エンタープライズアプリケーション」の内訳 | 3つセットで扱われる |
ハマりどころ・Tips
1. 主従関係があると sharingModel が ControlledByParent に固定される
主従関係項目を持つ詳細側は sharingModel が ControlledByParent になり、単独では共有設定を変えられません。関係項目の型と本体の sharingModel は整合している必要があるため、参照→主従への変更時は 両ファイルの差分を同じコミット・同じdeployに含める と安全です。なお、既存レコードのすべてに親の値が入っていないと、主従関係への変更は失敗します。
また、関係項目に変更がなくても、詳細側の本体XML(sharingModel が ControlledByParent)をdeployする際は、主従関係項目も同じdeployに含めてください。含めないと、ControlledByParent に関するエラーでdeployが失敗することがあります。
2. 標準オブジェクトはpackage.xmlで名前指定が必要
<members>*</members> で取れるのはカスタムオブジェクトだけで、標準オブジェクトにはワイルドカードが使えません。Account などは 名前を列挙 します(* と名前指定は同じ <types> 内で併用できます)。
sf project retrieve start --metadata CustomObject:Account
3. オブジェクト権限・項目レベルセキュリティは含まれない
CRUD権限やFLSはProfile / PermissionSetの objectPermissions / fieldPermissions 側です。
👉 項目のdeployとは別に、対象ユーザへの項目アクセス権も確認してください。
4. 本体XMLを編集するときは意図しない差分に注意
項目だけを扱いたい場合は、CustomField 型と項目の完全名を指定すれば、本体XMLに触れずに取得・deployできます。以下は、Project__c の Status__c 項目を指定する例です。
sf project retrieve start --metadata "CustomField:Project__c.Status__c"
一方、本体の object-meta.xml を編集してdeployする場合は注意が必要です。不要に見える要素を削ると、その設定が既定値に戻る可能性があります。
過去には、Metadata APIによるカスタムオブジェクトの更新時に、活動やレポートの設定が無効化されるKnown Issueが報告されています(W-3035712、ステータス:Closed)。現行バージョンで同じ事象が発生するかは未確認です。
👉 本体XMLを編集する場合は、意図しない要素の削除・変更を避け、deploy前後で設定差分を確認してください。特に既存オブジェクトの設定を変更する際は注意が必要です。
retrieve用のpackage.xml断片
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types>
<members>*</members>
<members>Account</members>
<members>Opportunity</members>
<name>CustomObject</name>
</types>
<version>68.0</version>
</Package>
sf project retrieve start --manifest manifest/package.xml --target-org my-dev
ここまでの内容を1枚にまとめると、次のような関係です。CustomObject:Project__c を指定すると、対象組織に存在する子メタデータ(項目・リストビューなど)がまとめて取得対象になります。
まとめ
- ソース形式では 本体
object-meta.xml+ 子フォルダ に分解され、Layoutやトリガは別の型 - 主従関係の詳細側は
sharingModelがControlledByParentになり、関係項目とセットで管理する - 標準オブジェクトは名前指定、権限はProfile / PermissionSet側
👉 「オブジェクトに入るもの・入らないもの」を分けて捉えると整理しやすいです。
次回(Day3)は CustomField(カスタム項目) を取り上げ、データ型ごとのXMLの違いを整理する予定です。
参考
- Metadata API Developer Guide: CustomObject
- Metadata API Developer Guide: Metadata Types(一覧)
- Salesforce DX Developer Guide: Salesforce DX Project Structure and Source Format
- Salesforce CLI Command Reference: project retrieve start
- Metadata API Developer Guide: Profile
- Metadata API Developer Guide: PermissionSet
- Metadata API Developer Guide: Step 2: Build a Package.xml Manifest
- Trailhead: Set External Org-Wide Defaults
- Known Issue: EnableActivities and EnableReports settings are disabled on updating a custom object via MetaData API


