generating-custom-object

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

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

创建新的自定义对象
生成自定义对象元数据XML
配置对象共享和安全设置
设置对象功能与特性
排查与自定义对象相关的部署错误

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

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

.object-meta.xml

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

文件扩展名：

.object-meta.xml

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.

Agent必须根据对象的预期用例选择启用哪些功能。

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

B. 对象描述

<description>
: Mandatory. Every object must contain a professional summary.

If the intent is vague, generate a summary:

"Object used to track and manage [Intent] within the organization."

<description>
：必填。每个对象都必须包含专业的摘要。

如果用途不明确，生成如下摘要：

"用于在组织内跟踪和管理[用途]的对象。"

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或自定义字段的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`
Custom Object	以 `__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
```
结尾？
验证规则名称是否符合字母数字+下划线的模式？

Architectural Checks

架构检查

Is
```
<description>
```
present with a meaningful summary?
Are
```
<enableSearch>
```
and
```
<enableReports>
```
set to
```
true
```
if user-facing?
Does the filename match the intended API name?

是否存在
```
<description>
```
且包含有意义的摘要？
若面向用户，
```
<enableSearch>
```
和
```
<enableReports>
```
是否设置为
```
true
```
？
文件名是否与预期API名称匹配？