platform-custom-object-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Use This Skill

何时使用此技能

Use this skill when you need to:

Create new custom objects
Generate custom object metadata XML
Configure object sharing and security settings
Set up object features and capabilities
Troubleshoot deployment errors related to custom objects
Add, update, or delete a field OR a validation rule on an existing object — any of these may make the object's
```
<description>
```
stale, so you must refresh it (propose + confirm). This applies equally to validation-rule changes, not just fields. See Section 3.B.

当你需要以下操作时，请使用此技能：

创建新的自定义对象
生成自定义对象元数据XML
配置对象共享与安全设置
设置对象功能与特性
排查与自定义对象相关的部署错误
在现有对象上添加、更新或删除字段或验证规则 —— 这些操作可能会使对象的
```
<description>
```
失效，因此你必须刷新该描述（先提议，再确认）。此要求同样适用于验证规则的更改，而不仅仅是字段更改。请参阅第3.B节。

Specification

规范

1. Overview and Purpose

1. 概述与目的

This document defines the mandatory constraints for generating CustomObject metadata XML (

.object-meta.xml

file). The agent must verify these constraints before outputting XML to prevent Metadata API deployment errors.

File extension:

.object-meta.xml

🔔 Description freshness — applies to EVERY object change, fields AND validation rules: Whenever you add, update, or delete a field or a validation rule on an object, the
<description>
may now be stale. Before finishing, refresh it per Section 3.B (propose, confirm with the user, write). A validation-rule change counts exactly like a field change — the change is not done until the description has been reconciled. This is easy to forget on validation-rule edits/deletes — don't.

本文档定义了生成CustomObject元数据XML（

.object-meta.xml

文件）的强制约束条件。代理在输出XML前必须验证这些约束，以避免Metadata API部署错误。

文件扩展名：

.object-meta.xml

🔔 描述时效性 —— 适用于所有对象更改（字段和验证规则）： 无论何时在对象上添加、更新或删除字段或验证规则，
<description>
都可能失效。完成操作前，请按照第3.B节的要求刷新描述（提议、与用户确认、写入）。验证规则的更改与字段更改完全等效 —— 只有当描述更新完成后，更改才算真正完成。在编辑/删除验证规则时很容易忘记这一点，请务必留意。

2. Syntactic Essentials (Tier 1)

2. 语法要点（第一层级）

The following constraints must be true for the XML body to deploy successfully.

Note: The API Name (fullName) is NOT a tag; it is the filename (e.g.,

Vehicle__c.object-meta.xml

以下约束条件必须满足，XML主体才能成功部署。

注意： API名称（fullName）不是标签，而是文件名（例如：

Vehicle__c.object-meta.xml

）。

Required Elements

必填元素

Element	Requirement	Notes
`<label>`	Required	Singular UI name
`<pluralLabel>`	Required	Plural UI name
`<sharingModel>`	Required	See Sharing Model Rules below
`<deploymentStatus>`	Required	Always set to `Deployed`
`<nameField>`	Required	Primary record identifier (requires `<label>` and `<type>` )
`<visibility>`	Required	Always set to `Public`

元素	要求	说明
`<label>`	必填	单数UI名称
`<pluralLabel>`	必填	复数UI名称
`<sharingModel>`	必填	请参阅下文的共享模型规则
`<deploymentStatus>`	必填	始终设置为 `Deployed`
`<nameField>`	必填	主记录标识符（需要包含 `<label>` 和 `<type>` ）
`<visibility>`	必填	始终设置为 `Public`

Sharing Model Rules

共享模型规则

Default: Set

<sharingModel>

ReadWrite

Exception: If this object contains a Master-Detail relationship field,

<sharingModel>

MUST be

ControlledByParent

Decision Logic:

IF object has NO Master-Detail field → use
```
ReadWrite
```
IF object has Master-Detail field → use
```
ControlledByParent
```
IF a Master-Detail field is being added to an existing child object → that existing object's
```
<sharingModel>
```
must also be updated to
```
ControlledByParent
```

❌ INCORRECT — Will cause error:

Cannot set sharingModel to ReadWrite on a CustomObject with a MasterDetail relationship field

xml

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Order Line Item</label>
  <pluralLabel>Order Line Items</pluralLabel>
  <sharingModel>ReadWrite</sharingModel>  <!-- WRONG: Object has a M-D field -->
  <deploymentStatus>Deployed</deploymentStatus>
</CustomObject>

✅ CORRECT:

xml

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Order Line Item</label>
  <pluralLabel>Order Line Items</pluralLabel>
  <sharingModel>ControlledByParent</sharingModel>  <!-- CORRECT -->
  <deploymentStatus>Deployed</deploymentStatus>
</CustomObject>

默认值： 将

<sharingModel>

设置为

ReadWrite

。

例外情况： 如果该对象包含Master-Detail关系字段，则

<sharingModel>

必须设置为

ControlledByParent

。

决策逻辑：

如果对象没有Master-Detail字段 → 使用
```
ReadWrite
```
如果对象有Master-Detail字段 → 使用
```
ControlledByParent
```
如果向现有子对象添加Master-Detail字段 → 该现有对象的
```
<sharingModel>
```
也必须更新为
```
ControlledByParent
```

❌ 错误示例 —— 会导致错误：

Cannot set sharingModel to ReadWrite on a CustomObject with a MasterDetail relationship field

xml

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Order Line Item</label>
  <pluralLabel>Order Line Items</pluralLabel>
  <sharingModel>ReadWrite</sharingModel>  <!-- 错误：对象包含M-D字段 -->
  <deploymentStatus>Deployed</deploymentStatus>
</CustomObject>

✅ 正确示例：

xml

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Order Line Item</label>
  <pluralLabel>Order Line Items</pluralLabel>
  <sharingModel>ControlledByParent</sharingModel>  <!-- 正确 -->
  <deploymentStatus>Deployed</deploymentStatus>
</CustomObject>

3. Smart Defaults & Decision Logic (Tier 2)

3. 智能默认值与决策逻辑（第二层级）

The agent must choose which features to enable based on the object's intended use case.

代理必须根据对象的预期用例选择要启用的功能。

A. The Name Field Decision

A. 名称字段决策

Type	When to Use	Additional Requirements
Text	Default for human-named entities (Projects, Locations, Teams)	None
AutoNumber	Use for transactions, logs, or IDs (Invoices, Requests, Tickets)	Must include `<displayFormat>` (e.g., `INV-{0000}` ) and `<startingNumber>1</startingNumber>`

Text Name Field Example:

xml

<nameField>
  <label>Project Name</label>
  <type>Text</type>
</nameField>

AutoNumber Name Field Example:

xml

<nameField>
  <label>Invoice Number</label>
  <type>AutoNumber</type>
  <displayFormat>INV-{0000}</displayFormat>
  <startingNumber>1</startingNumber>
</nameField>

类型	使用场景	额外要求
Text	人类命名实体的默认类型（如项目、地点、团队）	无
AutoNumber	用于交易、日志或ID（如发票、请求、工单）	必须包含 `<displayFormat>` （例如： `INV-{0000}` ）和 `<startingNumber>1</startingNumber>`

Text类型名称字段示例：

xml

<nameField>
  <label>Project Name</label>
  <type>Text</type>
</nameField>

AutoNumber类型名称字段示例：

xml

<nameField>
  <label>Invoice Number</label>
  <type>AutoNumber</type>
  <displayFormat>INV-{0000}</displayFormat>
  <startingNumber>1</startingNumber>
</nameField>

B. Object Description (Enrichment)

B. 对象描述（丰富化）

<description>
: Mandatory — every Custom Object MUST have one. It must read like human-written documentation, never a generic template ("Object used to track and manage...") or a metadata dump ("Contains 8 fields including

Project_Name__c

...").

Always compose an enriched description — when creating the object, and again on any change to it: adding, updating, or deleting a field or a validation rule (so it never goes stale). The change — field or validation rule — is never "done" until you've refreshed the object's description. This is not optional; do not ask whether to add a description.

Confirm per change — every time. Propose and confirm on each field/rule change separately. A previous "keep current" applies only to that one change; it is never standing permission to skip the proposal on a later change. Do not infer a preference from an earlier answer — re-propose and re-ask for every new change.

Compose the description (steps below). If the object already has one, use it as a strong signal — preserve the business context it carries (domain, team, intent the schema can't reveal) and fold the new field/rule in rather than discarding it.

Then branch on whether a description already exists:

No existing description (brand-new object): there is nothing to overwrite — just write the composed description. Do not prompt.
An existing description (update, delete, or any re-enrichment): never overwrite it silently — you can't tell from the file whether it was hand-written by an admin or generated earlier. Show the proposal, ask, and STOP — wait for the user's reply before writing:
Proposed description for
```
{Object}
```
:
```
<the enriched description>
```
Current:
```
<the existing description>
```
Use this? (yes / keep current / edit)
You MUST NOT write the
<description>
until the user replies — showing the diff is not approval, even when the change looks obvious or minor. Then act: yes → write the proposed text · keep current → leave the existing one untouched (this applies to this change only — re-propose on the next one) · edit → use the user's wording.

Always end with a

<description>

written.

Composing the description:

Classify each field by how it appears in the description:
- Constrained (required, unique, externalId, restricted picklist) → selective parenthetical:
```
VIN (required, external ID)
```
  ,
```
Color (Red/Green only)
```
- Behavioral (formula, roll-up) → describe what it computes: "the Age Years field auto-calculates vehicle age"
- Relationship (master-detail, lookup) → woven context: "as a child of Account" (never "(Master-Detail to Account)")
- Standard → label only
Compose in this order, using field labels not API names:

Purpose → key fields → computed fields → validation rules (as business rules) → "Commonly used for {use cases}."
Count and trim before writing (required): count the words; aim ~45, hard ceiling 50. If over, tighten wording first, then drop whole sentences in priority order (use cases → rules → computed; never drop sentences 1–2). Recount. Do not write until ≤ 50.

Example (Car, 46 words):

xml

<description>The Car object tracks vehicle inventory and maintenance. It captures Year, VIN (required, external ID), Color (Red/Green only), and Location; the Age Years field auto-calculates vehicle age. VIN is required and Black cars cannot be sold. Commonly used for fleet management, inventory tracking, and service scheduling.</description>

→ For the full workflow and examples, read references/description-enrichment.md
.

<description>
：必填 —— 每个Custom Object都必须包含描述。描述必须像人工编写的文档，绝不能使用通用模板（如“用于跟踪和管理……的对象”）或元数据转储（如“包含8个字段，包括

Project_Name__c

……”）。

始终编写丰富的描述 —— 创建对象时需要，并且在对象发生任何更改时也需要：添加、更新或删除字段或验证规则（确保描述不会失效）。只有当你刷新了对象描述后，字段或验证规则的更改才算“完成”。这不是可选操作，不要询问是否添加描述。

每次更改都需确认。 对每一次字段/规则更改分别进行提议和确认。之前的“保持当前描述”仅适用于那次更改；绝不代表以后的更改可以跳过提议步骤。不要从之前的回答中推断用户偏好 —— 每次新更改都要重新提议并询问。

编写描述的步骤：

对每个字段进行分类，确定其在描述中的呈现方式：
- 约束型（必填、唯一、外部ID、受限选择列表）→ 使用选择性括号标注：
```
VIN (必填，外部ID)
```
  、
```
Color (仅红/绿)
```
- 行为型（公式、汇总）→ 描述其计算逻辑：“Age Years字段自动计算车辆使用年限”
- 关系型（Master-Detail、查找）→ 融入上下文：“作为Account的子对象”（绝不能写成“(Master-Detail关联Account)”）
- 标准型 → 仅显示标签
按以下顺序编写，使用字段标签而非API名称：

用途 → 关键字段 → 计算字段 → 验证规则（作为业务规则）→ “常用于{用例}。”
编写前需计数并精简（必填）： 统计单词数；目标约45个，上限50个。如果超过，先精简措辞，再按优先级删除整句（优先级：用例→规则→计算字段；绝不能删除前1-2句）。重新计数，直到单词数≤50再编写。

示例（Car对象，46个单词）：

xml

<description>The Car object tracks vehicle inventory and maintenance. It captures Year, VIN (required, external ID), Color (Red/Green only), and Location; the Age Years field auto-calculates vehicle age. VIN is required and Black cars cannot be sold. Commonly used for fleet management, inventory tracking, and service scheduling.</description>

→ 如需完整工作流和更多示例，请阅读**

references/description-enrichment.md

**。

C. Junction Object Naming

C. 关联对象命名

If the object is a many-to-many link between two parents, name the object by combining the two parent entities to ensure the schema remains intuitive.

Examples:

```
Position_Candidate__c
```
(links Position and Candidate)
```
Job_Application__c
```
(links Job and Application)

如果对象是两个父对象之间的多对多链接，请结合两个父实体的名称来命名该对象，以确保架构直观易懂。

示例：

```
Position_Candidate__c
```
（关联Position和Candidate）
```
Job_Application__c
```
（关联Job和Application）

D. Feature Enablement (Clean XML)

D. 功能启用（简洁XML）

To maintain "Clean XML," only include optional tags when deviating from the Salesforce platform default of

false

Scenario A: User-Facing Objects (Apps, Trackers, Business Entities)

Trigger: The object is intended for direct user interaction

Action: Set

<enableSearch>

<enableReports>

<enableActivities>

, and

<enableHistory>

true

Scenario B: System-Facing Objects (Junctions, Background Logs)

Trigger: The object exists for technical associations or background data
Action: Omit these tags to keep the UI clean and the XML lean

为保持“简洁XML”，仅当与Salesforce平台默认值

false

不同时才包含可选标签。

场景A：面向用户的对象（应用、跟踪器、业务实体）

触发条件：对象用于直接用户交互

操作：将

<enableSearch>

、

<enableReports>

、

<enableActivities>

和

<enableHistory>

设置为

true

场景B：面向系统的对象（关联对象、后台日志）

触发条件：对象用于技术关联或后台数据存储
操作：省略这些标签，以保持UI整洁和XML精简

4. Critical Constraints & Common Failures

4. 关键约束与常见错误

Reserved Words

保留字

Never use reserved words as API names for Custom Objects or Custom Fields:

Category	Reserved Words (Do Not Use as API Names)
SOQL/SQL	`Select` , `From` , `Where` , `Limit` , `Order` , `Group`
System	`User` , `External` , `View` , `Type`
Temporal	`Date` , `Number`

切勿将保留字用作Custom Object或Custom Field的API名称：

类别	保留字（请勿用作API名称）
SOQL/SQL	`Select` , `From` , `Where` , `Limit` , `Order` , `Group`
系统	`User` , `External` , `View` , `Type`
时间相关	`Date` , `Number`

Relationship Cap

关系上限

Do not create more than 2 Master-Detail relationships for a single object. If a third relationship is required, use a Lookup instead.

单个对象最多创建2个Master-Detail关系。如果需要第三个关系，请使用Lookup关系替代。

XML Root Element

XML根元素

Do NOT include the

<fullName>

tag at the root of the

.object-meta.xml

file. The API name is derived from the filename.

❌ INCORRECT:

xml

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Vehicle__c</fullName>  <!-- WRONG: Remove this -->
  <label>Vehicle</label>
</CustomObject>

✅ CORRECT:

xml

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Vehicle</label>
  <!-- fullName comes from filename: Vehicle__c.object-meta.xml -->
</CustomObject>

请勿在

.object-meta.xml

文件的根元素中包含

<fullName>

标签。API名称由文件名派生而来。

❌ 错误示例：

xml

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Vehicle__c</fullName>  <!-- 错误：请移除 -->
  <label>Vehicle</label>
</CustomObject>

✅ 正确示例：

xml

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Vehicle</label>
  <!-- fullName来自文件名：Vehicle__c.object-meta.xml -->
</CustomObject>

Validation Rule Naming Convention

验证规则命名规范

Validation rule names follow different conventions than custom fields.

Rules:

Must contain only alphanumeric characters and underscores
Must begin with a letter
Cannot end with an underscore
Cannot contain two consecutive underscores
Must NOT end with
__c
(unlike custom fields)

❌ INCORRECT:

xml

<validationRules>
  <fullName>Require_Start_Date__c</fullName>  <!-- WRONG: Has __c suffix -->
  <active>true</active>
  <errorMessage>Start Date is required.</errorMessage>
  <formula>ISBLANK(Start_Date__c)</formula>
</validationRules>

Error:

The validation name can only contain alphanumeric characters, must begin with a letter, cannot end with an underscore...

✅ CORRECT:

xml

<validationRules>
  <fullName>Require_Start_Date</fullName>  <!-- CORRECT: No __c suffix -->
  <active>true</active>
  <errorMessage>Start Date is required.</errorMessage>
  <formula>ISBLANK(Start_Date__c)</formula>
</validationRules>

Naming Pattern Reference:

Metadata Type	Naming Pattern	Example
Custom Fields	Ends with `__c`	`Start_Date__c`
Validation Rules	No suffix	`Require_Start_Date`
Custom Objects	Ends with `__c`	`Vehicle__c`

验证规则的命名规范与自定义字段不同。

规则：

只能包含字母数字字符和下划线
必须以字母开头
不能以下划线结尾
不能包含两个连续的下划线
不能以
__c
结尾（与自定义字段不同）

❌ 错误示例：

xml

<validationRules>
  <fullName>Require_Start_Date__c</fullName>  <!-- 错误：包含__c后缀 -->
  <active>true</active>
  <errorMessage>Start Date is required.</errorMessage>
  <formula>ISBLANK(Start_Date__c)</formula>
</validationRules>

错误提示：

The validation name can only contain alphanumeric characters, must begin with a letter, cannot end with an underscore...

✅ 正确示例：

xml

<validationRules>
  <fullName>Require_Start_Date</fullName>  <!-- 正确：无__c后缀 -->
  <active>true</active>
  <errorMessage>Start Date is required.</errorMessage>
  <formula>ISBLANK(Start_Date__c)</formula>
</validationRules>

命名模式参考：

元数据类型	命名模式	示例
自定义字段	以 `__c` 结尾	`Start_Date__c`
验证规则	无后缀	`Require_Start_Date`
自定义对象	以 `__c` 结尾	`Vehicle__c`

5. Verification Checklist

5. 验证清单

Before generating the Custom Object XML, verify:

生成Custom Object XML前，请验证以下内容：

Syntactic Checks

语法检查

Are both
```
<label>
```
and
```
<pluralLabel>
```
present?
Is
```
<deploymentStatus>
```
set to
```
Deployed
```
?
Is
```
<visibility>
```
set to
```
Public
```
?
Does
```
<nameField>
```
include both
```
<label>
```
and
```
<type>
```
?

<type>

AutoNumber

, are

<displayFormat>

and

<startingNumber>

included?

是否同时包含
```
<label>
```
和
```
<pluralLabel>
```
？
```
<deploymentStatus>
```
是否设置为
```
Deployed
```
？
```
<visibility>
```
是否设置为
```
Public
```
？
```
<nameField>
```
是否同时包含
```
<label>
```
和
```
<type>
```
？

如果

<type>

为

AutoNumber

，是否包含

<displayFormat>

和

<startingNumber>

？

Sharing Model Check (Critical)

共享模型检查（关键）

Does this object have a Master-Detail relationship field?
- If YES →
```
<sharingModel>
```
  MUST be
```
ControlledByParent
```
- If NO →
```
<sharingModel>
```
  should be
```
ReadWrite
```

该对象是否包含Master-Detail关系字段？
- 如果是 →
```
<sharingModel>
```
  必须设置为
```
ControlledByParent
```
- 如果否 →
```
<sharingModel>
```
  应设置为
```
ReadWrite
```

Constraint Checks

约束检查

Is the API name free of reserved words?
Are there 2 or fewer Master-Detail relationships?
Is
```
<fullName>
```
absent from the XML root?

API名称是否不含保留字？
Master-Detail关系数量是否≤2？
XML根元素中是否没有
```
<fullName>
```
？

Validation Rule Checks (if applicable)

验证规则检查（如适用）

Do validation rule names NOT end with
```
__c
```
?
Do validation rule names follow alphanumeric + underscore pattern?

验证规则名称是否不以
```
__c
```
结尾？
验证规则名称是否符合字母数字+下划线的模式？

Description Enrichment Quality Checks

描述丰富化质量检查

Architectural Checks

架构检查

Is
```
<description>
```
present? (Enriched per Section B — proposed and confirmed with the user before writing.)
Are
```
<enableSearch>
```
and
```
<enableReports>
```
set to
```
true
```
if user-facing?
Does the filename match the intended API name?

是否包含
```
<description>
```
？（按照第B节要求丰富化 —— 写入前已提议并与用户确认。）
如果是面向用户的对象，
```
<enableSearch>
```
和
```
<enableReports>
```
是否设置为
```
true
```
？
文件名是否与预期的API名称匹配？

Reference File Index

参考文件索引

File	When to read
`references/description-enrichment.md`	Composing or refreshing an object's `<description>` (on create, or when a field/rule changes) — full enrichment workflow, field-prioritization tiers, junction/child handling, edge cases, and more examples

文件	阅读场景
`references/description-enrichment.md`	编写或刷新对象的 `<description>` 时（创建对象时，或字段/规则更改时）—— 包含完整的丰富化工作流、字段优先级层级、关联/子对象处理、边缘情况及更多示例