platform-metadata-api-context-get

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Salesforce Metadata API Skill

Salesforce Metadata API 技能文档

This skill provides comprehensive documentation for all 604 Salesforce Metadata API types. Use this skill to create, understand, and modify Salesforce metadata XML files in your Salesforce DX projects.

本技能文档提供所有604种Salesforce Metadata API类型的完整说明。您可以使用本技能在Salesforce DX项目中创建、理解和修改Salesforce元数据XML文件。

Overview

概述

The Salesforce Metadata API allows you to retrieve, deploy, create, update, or delete customizations for your org. This skill gives you access to detailed documentation for each metadata type, including:

Field definitions and data types
Required vs. optional fields
WSDL schema definitions
Sample XML structures
File naming conventions
Directory locations in Salesforce DX projects

Salesforce Metadata API允许您检索、部署、创建、更新或删除组织中的自定义内容。本技能提供每种元数据类型的详细说明，包括：

字段定义和数据类型
必填字段与可选字段
WSDL模式定义
XML示例结构
文件命名规范
Salesforce DX项目中的目录位置

How to Use This Skill

如何使用本技能

⚡ CRITICAL: Section-Specific Consumption

⚡ 重要提示：按需加载特定章节

ALWAYS consume only the specific sections you need from JSON files, NOT entire files.

CRITICAL: For
data/metadata_api/*.json
files, always use
jq
or programmatic JSON parsing to extract only the specific sections you need. Do not load these files whole via

Read

cat

read_file

, or any other tool that injects the complete file — they contain verbose WSDL segments and other sections that waste 60-80% of tokens. (Loading small files like this SKILL.md or the index table with

Read

is fine; the rule applies specifically to the large metadata-type JSON files.)

Each JSON file contains multiple sections (fields, description, wsdl_segment, etc.). Most use cases only require 1-2 sections:

For field definitions: Load only the
```
fields
```
section
For understanding purpose: Load only the
```
description
```
section
For XML examples: Load only the
```
declarative_metadata_sample_definition
```
section

Skip by default:

wsdl_segment

(verbose schema),

file_information

directory_location

This reduces token consumption by 60-80% per file.

始终仅从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%。

Quick Start

快速入门

To get information about a specific metadata type:

Section-specific (BEST): "Show me only the 'fields' section from CustomObject.json"
Multiple sections: "Show me 'fields' and 'description' from Flow.json"
Avoid loading entire files: Don't ask for "the CustomObject metadata type" - specify sections

要获取特定元数据类型的信息：

按需加载特定章节（最佳方式）："仅展示CustomObject.json中的'fields'章节"
加载多个章节："展示Flow.json中的'fields'和'description'章节"
避免加载整个文件：不要请求"CustomObject元数据类型"——请指定具体章节

Example Queries (Section-Specific)

示例查询（按需加载特定章节）

✅ "Show me only the 'fields' section from CustomObject.json"
✅ "What fields are in the 'fields' section of Profile.json?"
✅ "Load the 'description' and 'fields' sections from Flow.json"
✅ "Give me just the 'declarative_metadata_sample_definition' from ApexClass.json"
❌ "Show me the CustomObject metadata type" (too broad - entire file)
❌ "Load CustomObject.json" (includes unnecessary WSDL and other sections)

✅ "仅展示CustomObject.json中的'fields'章节"
✅ "Profile.json的'fields'章节中有哪些字段？"
✅ "加载Flow.json中的'description'和'fields'章节"
✅ "仅提供ApexClass.json中的'declarative_metadata_sample_definition'"
❌ "展示CustomObject元数据类型"（范围过广——会加载整个文件）
❌ "加载CustomObject.json"（包含不必要的WSDL和其他章节）

JSON File Structure

JSON文件结构

Each metadata type is stored as a JSON file in

data/metadata_api/

with the following structure:

json

{
  "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>"
    }
  ]
}

Note: string values (
title
,
description
,
file_information
,
directory_location
,
wsdl_segment
) are stored as plain text — no markdown headers (
#
/
##
) or code fences.
file_information
holds just the file suffix (e.g.
.object
,
.ai
) and
directory_location
just the SFDX folder name (e.g.
objects
,
aiApplications
).

每种元数据类型都存储为

data/metadata_api/

目录下的JSON文件，结构如下：

json

{
  "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
）。

Available Sections

可用章节

The

sections

array indicates which top-level keys are present in each file. Common sections include:

```
title
```
: The metadata type name and header
```
description
```
: What the metadata type represents
```
fields
```
: The type's own fields, with types and descriptions
```
sub_types
```
: (composite types only) a map of referenced sub-type name → that sub-type's fields, e.g.
```
Flow
```
→
```
sub_types.FlowActionCall
```
```
file_information
```
: File naming conventions and extensions
```
directory_location
```
: Where files are stored in SFDX projects
```
wsdl_segment
```
: XML schema definition from the WSDL
```
declarative_metadata_sample_definition
```
: Example XML code

Some metadata types have additional sections specific to their functionality. See the Index Table for a complete breakdown.

More detail: background on why token optimization matters, worked usage examples, common workflows, a full section glossary, and versioning/support notes live in
references/usage_guide.md
. Load it with the
Read
tool only when needed.

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
工具加载该文件。

Token Optimization Strategies

令牌优化策略

CRITICAL: To minimize token usage and costs:

Load only the specific metadata type(s) you need, not the full corpus
Load only specific sections from each file, not entire files

重要提示：为最小化令牌使用和成本：

仅加载您需要的特定元数据类型，而非全部
仅加载每个文件中的特定章节，而非整个文件

Section-Specific Loading (BEST PRACTICE)

按需加载特定章节（最佳实践）

⚠️ CRITICAL WARNING: DO NOT use the
read_file
tool (or any whole-file reading tool) on these JSON files!

read_file

loads the entire file content into your context, defeating the purpose of section-specific consumption. You will waste 60-80% of your token budget loading unnecessary WSDL segments and verbose sections. (Using

Read

on small files such as this SKILL.md or the index table is fine — this rule is only about the large metadata-type JSON files.)

Approach: Programmatically parse the JSON file and extract ONLY the sections you need using code, not whole-file reading tools.

Working Examples Available:

We provide complete, working code examples in multiple languages:

Python:

examples/python_section_loading.py

- Shows

json.load()

with section extraction

JavaScript/Node.js:

examples/javascript_section_loading.js

- Shows

JSON.parse()

with section extraction

Bash + jq:
```
examples/bash_section_loading.sh
```
- Shows
```
jq
```
command-line JSON processing

See

examples/README.md

for complete documentation and usage instructions.

Quick Pattern (adapt to your language):

Read the JSON file
Parse it into a data structure
Extract ONLY the sections you need (e.g.,
```
fields
```
,
```
description
```
)

Ignore verbose sections (

wsdl_segment

declarative_metadata_sample_definition

)

⚠️ 重要警告：请勿对这些JSON文件使用
read_file
工具（或任何加载整个文件的工具）！

read_file

会将整个文件内容加载到上下文环境中，违背了按需加载特定章节的目的。您会浪费60-80%的令牌预算加载不必要的WSDL片段和冗长章节。（加载像本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

获取完整文档和使用说明。

快速模式（适配您使用的语言）：

读取JSON文件
将其解析为数据结构
仅提取您需要的章节（例如
```
fields
```
、
```
description
```
）

忽略冗长章节（

wsdl_segment

、

declarative_metadata_sample_definition

）

What NOT to Do

禁止操作

❌ NEVER use the
read_file
tool on these JSON files:

text

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

❌ NEVER load all files:

text

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

Token Impact:

Section-specific: 50-200 tokens per metadata type
Entire file: 500-2000 tokens per metadata type
Savings: 60-80% per file

❌ 永远不要对这些JSON文件使用
read_file
工具：

text

read_file data/metadata_api/CustomObject.json  # 将整个文件加载到上下文环境中！
read_file data/metadata_api/Flow.json          # 浪费60-80%的令牌！

❌ 永远不要加载所有文件：

text

read_file data/metadata_api/*.json  # 这会加载约15MB的数据！

令牌影响：

按需加载特定章节：每个元数据类型50-200个令牌
加载整个文件：每个元数据类型500-2000个令牌
节省：每个文件60-80%

When to Load Multiple Types

何时加载多种类型

Related types: CustomObject + CustomField + ValidationRule
Permission sets: Profile + PermissionSet + PermissionSetGroup
UI components: Layout + CompactLayout + QuickAction
Automation: Flow + WorkflowRule + ApexTrigger

相关类型：CustomObject + CustomField + ValidationRule
权限集：Profile + PermissionSet + PermissionSetGroup
UI组件：Layout + CompactLayout + QuickAction
自动化：Flow + WorkflowRule + ApexTrigger

When to Load Specific Sections (STRONGLY RECOMMENDED)

何时加载特定章节（强烈推荐）

Many metadata types have large WSDL segments or extensive field lists. Always load only the specific sections you need from each JSON file rather than consuming the entire file:

First, check available sections by reading just the
```
sections
```
array from the JSON
Extract only the sections you need (e.g.,
```
fields
```
for field definitions,
```
description
```
for overview)
Skip WSDL segments unless you specifically need schema validation
Skip declarative_metadata_sample_definition unless you need complete XML examples

This approach can reduce token consumption by 60-80% per file by excluding verbose WSDL definitions and lengthy examples.

许多元数据类型包含大型WSDL片段或大量字段列表。始终仅从每个JSON文件中加载您需要的特定章节，而非加载整个文件：

首先，检查可用章节：仅读取JSON文件中的
```
sections
```
数组
仅提取您需要的章节（例如，获取字段定义加载
```
fields
```
章节，获取概述加载
```
description
```
章节）
跳过WSDL片段：除非您特别需要模式验证
跳过declarative_metadata_sample_definition：除非您需要完整的XML示例

通过排除冗长的WSDL定义和示例，这种方法可以将每个文件的令牌消耗减少60-80%。

Conceptual Approach to Using This Skill

使用本技能的思路

Step 1: Identify Your Need

步骤1：明确需求

Ask yourself:

What am I trying to build or modify?
Which Salesforce metadata type(s) am I working with?
Which specific information do I need?
- Field definitions only? → Load
```
fields
```
  section
- Understanding what it does? → Load
```
description
```
  section
- XML example? → Load
```
declarative_metadata_sample_definition
```
  section
- Schema validation? → Load
```
wsdl_segment
```
  section (rarely needed)

自问：

我要构建或修改什么？
我正在使用哪些Salesforce元数据类型？
我需要哪些具体信息？
- 仅需要字段定义？→ 加载
```
fields
```
  章节
- 需要了解该类型的作用？→ 加载
```
description
```
  章节
- 需要XML结构示例？→ 加载
```
declarative_metadata_sample_definition
```
  章节
- 需要模式验证？→ 加载
```
wsdl_segment
```
  章节（很少需要）

Step 2: Find the Right Type

步骤2：找到正确的类型

Use one of these methods:

Direct reference: If you know the type name (e.g., "CustomObject")
Index search: Check
```
references/metadata_index_table.md
```
for related types
Common types: See the "Quick Reference: Common Metadata Types" section below

使用以下方法之一：

直接引用：如果您知道类型名称（例如"CustomObject"）
索引搜索：查看
```
references/metadata_index_table.md
```
查找相关类型
常见类型：查看下方的“快速参考：常见元数据类型”部分

Step 3: Load Selectively (Section-Specific) ⚡

步骤3：选择性加载（按需加载特定章节）⚡

Decision Tree for Section Loading:

text

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)

Request format:

Single section (BEST): "Show me only the 'fields' section from ApexClass.json"
Multiple sections: "Load 'fields' and 'description' from CustomObject.json"
Skip verbose sections: Never load
```
wsdl_segment
```
unless explicitly needed

章节加载决策树：

text

需要字段定义？
  → 仅加载'fields'章节（约50-200个令牌）

需要了解该类型的作用？
  → 仅加载'description'章节（约20-100个令牌）

需要XML结构示例？
  → 仅加载'declarative_metadata_sample_definition'（约100-300个令牌）

需要以上三者？
  → 加载'fields' + 'description' + 'declarative_metadata_sample_definition'
  → 仍跳过'wsdl_segment'、'file_information'、'directory_location'
  → 节省：比加载整个文件少约60-70%

需要模式验证？
  → 仅在此时加载'wsdl_segment'（内容冗长）

请求格式：

单个章节（最佳）："仅展示ApexClass.json中的'fields'章节"
多个章节："加载CustomObject.json中的'fields'和'description'章节"
跳过冗长章节：除非明确需要，否则永远不要加载
```
wsdl_segment
```

Step 4: Apply to Your Code

步骤4：应用到代码中

Use the loaded information to:

Create new metadata XML files
Understand existing files in your project
Validate field names and types
Generate correct XML structure with proper namespaces

使用加载的信息：

创建新的元数据XML文件
理解项目中的现有文件
验证字段名称和类型
生成带有正确命名空间的XML结构

File Location

文件位置

All metadata type JSON files are located in:

text

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

所有元数据类型JSON文件位于：

text

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

Path Resolution

路径解析

When using this skill, files are referenced as:

Absolute:
```
data/metadata_api/CustomObject.json
```
Relative to skill root:
```
./data/metadata_api/CustomObject.json
```

The skill will automatically resolve paths based on the working directory.

使用本技能时，文件引用方式：

绝对路径：
```
data/metadata_api/CustomObject.json
```
相对于技能根目录：
```
./data/metadata_api/CustomObject.json
```

技能会根据工作目录自动解析路径。

Metadata File Generation Requirements

元数据文件生成要求

When generating Salesforce metadata XML files, follow these requirements to ensure valid, deployable files.

生成Salesforce元数据XML文件时，请遵循以下要求以确保文件有效且可部署。

XML Structure Requirements

XML结构要求

All metadata files must:

Include XML declaration:
xml
```
<?xml version="1.0" encoding="UTF-8"?>
```

Use correct namespace:

xml

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

Match root element to metadata type:
- CustomObject →
```
<CustomObject>
```
- Flow →
```
<Flow>
```
- Profile →
```
<Profile>
```
- etc.

所有元数据文件必须：

包含XML声明：
xml
```
<?xml version="1.0" encoding="UTF-8"?>
```

使用正确的命名空间：

xml

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

根元素与元数据类型匹配：
- CustomObject →
```
<CustomObject>
```
- Flow →
```
<Flow>
```
- Profile →
```
<Profile>
```
- 等等

Namespace Declaration

命名空间声明

The namespace is required and must be exactly:

text

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

Correct:

xml

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

Incorrect:

xml

<CustomObject>  <!-- Missing namespace -->
<CustomObject xmlns="http://salesforce.com/metadata">  <!-- Wrong namespace -->

命名空间是必填项，且必须完全为：

text

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

正确示例：

xml

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

错误示例：

xml

<CustomObject>  <!-- 缺少命名空间 -->
<CustomObject xmlns="http://salesforce.com/metadata">  <!-- 错误的命名空间 -->

Required vs. Optional Fields

必填字段与可选字段

Each metadata type has different field requirements:

Schema-required (
```
required: true
```
in the JSON): the WSDL marks the field as required.
Effectively required (not flagged but practically needed): in many cases the WSDL marks fewer fields as required than the authoring contract actually demands. CustomObject is the canonical example — the JSON marks only
```
externalDataSource
```
,
```
externalName
```
,
```
nameField
```
as
```
required: true
```
(the first two are external-object-only quirks), but a normal
```
__c
```
CustomObject also needs
```
label
```
,
```
pluralLabel
```
,
```
deploymentStatus
```
, and
```
sharingModel
```
to deploy. Always cross-check with the
```
declarative_metadata_sample_definition
```
examples.
Conditionally required: some fields are required only when certain features are enabled.
Optional: most fields can be omitted if not needed.

Example from CustomObject (note: practical authoring needs more than what

required: true

marks):

json

{
  "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
    }
  }
}

每种元数据类型有不同的字段要求：

模式必填（JSON中
```
required: true
```
）：WSDL标记该字段为必填。
实际必填（未标记但实际需要）：在许多情况下，WSDL标记的必填字段数量少于实际编写合约所需的数量。CustomObject是典型示例——JSON仅标记
```
externalDataSource
```
、
```
externalName
```
、
```
nameField
```
为
```
required: true
```
（前两者仅适用于外部对象），但普通的
```
__c
```
自定义对象还需要
```
label
```
、
```
pluralLabel
```
、
```
deploymentStatus
```
和
```
sharingModel
```
才能部署。请始终与
```
declarative_metadata_sample_definition
```
示例交叉验证。
条件必填：某些字段仅在启用特定功能时才需要。
可选：大多数字段如果不需要可以省略。

CustomObject示例（注意：实际编写需要的字段比

required: true

标记的更多）：

json

{
  "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
    }
  }
}

Validation Tips

验证提示

Before deploying:

Validate XML syntax: Ensure well-formed XML (matching tags, proper nesting)
Check required fields: Verify all required fields are present
Verify namespaces: Namespace must be exact
Test field types: Ensure field values match expected types
Use Salesforce CLI: Run
```
sf project deploy validate
```
to catch errors

More detail: field-type→XML mapping tables, file-naming/two-file/child-type conventions, and full well-formed-file examples are in
references/usage_guide.md
.

部署前：

验证XML语法：确保XML格式正确（标签匹配、嵌套正确）
检查必填字段：确认所有必填字段都已包含
验证命名空间：命名空间必须完全正确
测试字段类型：确保字段值与预期类型匹配
使用Salesforce CLI：运行
```
sf project deploy validate
```
捕获错误

更多细节：字段类型→XML映射表、文件命名/双文件/子类型规范，以及完整的有效文件示例，请查阅
references/usage_guide.md
。

Duplicate and Ambiguous Type Names

重复和模糊的类型名称

Some Metadata API type names also exist as Enterprise/Data API or Tooling API object names. Examples include ApexClass, ApexTrigger, CustomField, CustomObject, EmailTemplate, Layout, Profile, PermissionSet, RecordType, StaticResource, WebLink, ValidationRule, and Flow.

When the prompt is ambiguous (e.g., "tell me about Profile" or "what fields are on ApexClass"), ask whether the user wants:

Metadata API XML structure for source/deployment authoring (this skill, e.g.
```
.profile-meta.xml
```
,
```
.cls-meta.xml
```
).
Enterprise/Data API runtime sObject/record reference (no dedicated skill currently — fall back to the Salesforce API family router).
Tooling API developer tooling record reference (no dedicated skill currently — fall back to the Salesforce API family router).

Heuristics that resolve most ambiguity without asking:

Mentions of
```
package.xml
```
,
```
force-app/
```
,
```
sfdx
```
,
```
.meta.xml
```
, "deploy", "retrieve", "authoring", "blueprint", "template", "class definition", or "permissions" in a deployment sense → Metadata API (this skill).
"What fields are on X" / "what columns" / "DML" / "SOQL" / "query" / "REST" / "sObject" / "record" / "runtime" → Enterprise/Data or Tooling API (other skill).
Tooling-specific signals: "Tooling API",
```
ApexCodeCoverage
```
,
```
EntityDefinition
```
,
```
TraceFlag
```
, "code coverage", "compile errors",
```
SymbolTable
```
, debug logging → Tooling API.

Default-when-no-signals rule: if the prompt has none of the signals above AND this skill (

platform-metadata-api-context-get

) was invoked directly by name, default to the Metadata API interpretation and explicitly disclose the assumption to the user (e.g., "Interpreting this as the Metadata API type for

.cls-meta.xml

authoring; let me know if you meant the Tooling API record or Enterprise/Data sObject"). The skill-invocation context itself is a signal of authoring/deployment intent.

某些Metadata API类型名称同时也是Enterprise/Data API或Tooling API对象名称。例如ApexClass、ApexTrigger、CustomField、CustomObject、EmailTemplate、Layout、Profile、PermissionSet、RecordType、StaticResource、WebLink、ValidationRule和Flow。

当提示模糊时（例如“告诉我关于Profile的信息”或“ApexClass有哪些字段”），请询问用户需要的是：

Metadata API：用于源代码/部署编写的XML结构（本技能，例如
```
.profile-meta.xml
```
、
```
.cls-meta.xml
```
）。
Enterprise/Data API：运行时sObject/记录参考（目前无专用技能——请使用Salesforce API系列路由工具）。
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或Tooling API（其他技能）。
Tooling特定信号：“Tooling API”、
```
ApexCodeCoverage
```
、
```
EntityDefinition
```
、
```
TraceFlag
```
、“code coverage”、“compile errors”、
```
SymbolTable
```
、调试日志→Tooling API。

无信号时的默认规则：如果提示没有上述任何信号，且本技能（

platform-metadata-api-context-get

）是通过名称直接调用的，则默认采用Metadata API解释，并明确向用户披露此假设（例如：“将此解释为用于

.cls-meta.xml

编写的Metadata API类型；如果您指的是Tooling API记录或Enterprise/Data sObject，请告知我”）。技能调用上下文本身就是编写/部署意图的信号。

Troubleshooting

故障排除

File Not Found

文件未找到

Problem: Cannot find metadata type file

Solutions:

File names are case-sensitive PascalCase with no separators (e.g.,
```
CustomObject.json
```
, NOT
```
customobject.json
```
,
```
Custom_Object.json
```
, or
```
Custom-Object.json
```
).
Before declaring "not found", consult
```
references/metadata_index_table.md
```
. Use this two-pass recovery algorithm against the index:
1. Normalize-and-substring (handles case + separator variants): strip non-alphanumeric characters and lowercase both the query and each index entry, then look for substring matches. Resolves:
```
customobject
```
  ,
```
Custom_Object
```
  ,
```
Custom-Object
```
  →
```
CustomObject
```
  .
2. On miss, fuzzy-match (handles missing-letter typos): use
```
difflib.get_close_matches(query_normalized, index_normalized, n=3, cutoff=0.7)
```
  or Levenshtein distance ≤ 2. Resolves:
```
customfeld
```
  →
```
CustomField
```
  ,
```
apxclass
```
  →
```
ApexClass
```
  . Pure substring matching cannot recover character deletions.
Multi-hit tiebreaker: when normalize-and-substring returns multiple matches (e.g.,
```
customobject
```
matches both
```
CustomObject
```
and
```
CustomObjectTranslation
```
), prefer the entry whose normalized length equals the normalized query length; otherwise prefer the shortest match.
Some types have unexpected naming conventions (no underscores, no spaces, no abbreviations like "OAuth"); the index is the source of truth.

问题：无法找到元数据类型文件

解决方案：

文件名区分大小写，采用帕斯卡命名法（PascalCase），无分隔符（例如
```
CustomObject.json
```
，而非
```
customobject.json
```
、
```
Custom_Object.json
```
或
```
Custom-Object.json
```
）。
在声明“未找到”之前，请查阅
```
references/metadata_index_table.md
```
。使用以下两步恢复算法对照索引：
1. 标准化并匹配子串（处理大小写和分隔符变体）：去除非字母数字字符，将查询内容和每个索引条目转换为小写，然后查找子串匹配。可解决：
```
customobject
```
  、
```
Custom_Object
```
  、
```
Custom-Object
```
  →
```
CustomObject
```
  。
2. 未匹配时，模糊匹配（处理漏字拼写错误）：使用
```
difflib.get_close_matches(query_normalized, index_normalized, n=3, cutoff=0.7)
```
  或Levenshtein距离≤2。可解决：
```
customfeld
```
  →
```
CustomField
```
  、
```
apxclass
```
  →
```
ApexClass
```
  。纯子串匹配无法恢复字符删除错误。
多匹配时的决胜规则：当标准化并匹配子串返回多个匹配（例如
```
customobject
```
同时匹配
```
CustomObject
```
和
```
CustomObjectTranslation
```
），优先选择标准化后长度与查询内容长度相等的条目；否则优先选择最短的匹配。
某些类型的命名规则出乎意料（无下划线、无空格、无缩写如“OAuth”）；索引是权威来源。

SOAP Envelope / Header Types (thin by design)

SOAP信封/头类型（设计上精简）

Two related patterns to recognize:

Result types (
```
AsyncResult
```
,
```
SaveResult
```
,
```
DeleteResult
```
,
```
UpsertResult
```
,
```
Error
```
,
```
DescribeMetadataResult
```
, etc.) —
```
fields
```
is empty AND
```
wsdl_segment
```
is populated. These are SOAP response wrappers; their schema lives entirely in
```
wsdl_segment
```
. Consume that section if you need their structure. They are not deployable source files.
SOAP request headers (
```
AllOrNoneHeader
```
,
```
SessionHeader
```
,
```
CallOptions
```
,
```
DebuggingHeader
```
,
```
OwnerChangeOptions
```
, etc.) —
```
fields
```
has 1–2 minimal entries, no
```
wsdl_segment
```
. These configure SOAP request behavior; they are call-time options, not metadata you author or deploy.

In both cases, the thin JSON output is correct. Don't try to author a

.AsyncResult-meta.xml

— these types have no source-file form.

需要识别两种相关模式：

结果类型（
```
AsyncResult
```
、
```
SaveResult
```
、
```
DeleteResult
```
、
```
UpsertResult
```
、
```
Error
```
、
```
DescribeMetadataResult
```
等）——
```
fields
```
为空且
```
wsdl_segment
```
已填充。这些是SOAP响应包装器；其模式完全位于
```
wsdl_segment
```
中。如果需要其结构，请加载该章节。它们不是可部署的源代码文件。
SOAP请求头（
```
AllOrNoneHeader
```
、
```
SessionHeader
```
、
```
CallOptions
```
、
```
DebuggingHeader
```
、
```
OwnerChangeOptions
```
等）——
```
fields
```
有1-2个最小条目，无
```
wsdl_segment
```
。这些用于配置SOAP请求行为；它们是调用时的选项，而非您编写或部署的元数据。

在这两种情况下，精简的JSON输出是正确的。不要尝试编写

.AsyncResult-meta.xml

——这些类型没有源代码文件形式。

Missing Section

章节缺失

Problem: Expected section not in JSON file

Solutions:

Check the
```
sections
```
array to see what's available
Not all metadata types have all sections
Some sections are type-specific (noted in index table)

问题：JSON文件中缺少预期章节

解决方案：

检查
```
sections
```
数组查看可用章节
并非所有元数据类型都包含所有章节
某些章节是特定类型独有的（索引表中有说明）

Incomplete Field Information

字段信息不完整

Problem: Field definition lacks details

Solutions:

Check
```
wsdl_segment
```
for complete schema definition
Some fields have complex types defined in WSDL
Cross-reference with Salesforce documentation for enumerations

问题：字段定义缺少详细信息

解决方案：

查看
```
wsdl_segment
```
获取完整模式定义
某些字段的复杂类型在WSDL中定义
对照Salesforce文档验证枚举类型

Following Sub-Type Pointers (e.g.,

ProfileObjectPermissions[]

)

跟踪子类型指针（例如

ProfileObjectPermissions[]

）

When the

fields

section gives a complex type name like

ProfileObjectPermissions[]

LayoutItem[]

ApprovalStep[]

, the sub-fields of that nested type are NOT in the

fields

section — they live in

wsdl_segment

for that complex type. The skill's "skip wsdl_segment by default" rule is for token economy on the simple-field path; for nested types you need to drill in.

Worked example — find the sub-fields of

objectPermissions

on Profile:

bash

undefined

当

fields

章节给出复杂类型名称如

ProfileObjectPermissions[]

、

LayoutItem[]

或

ApprovalStep[]

时，该嵌套类型的子字段不在

fields

章节中——它们位于该复杂类型的

wsdl_segment

中。技能的“默认跳过wsdl_segment”规则是为了在获取简单字段时节省令牌；对于嵌套类型，您需要深入查看。

示例操作——查找Profile的

objectPermissions

的子字段：

bash

undefined

1. Get the field type name from the fields section

1. 从fields章节获取字段类型名称

jq '.fields.objectPermissions' data/metadata_api/Profile.json

→ {"type": "ProfileObjectPermissions[]", ...}

2. Pull just the matching complexType from wsdl_segment using grep -A

2. 使用grep -A从wsdl_segment中提取匹配的complexType

jq -r '.wsdl_segment' data/metadata_api/Profile.json | grep -A 30 'complexType name="ProfileObjectPermissions"'


The `grep -A N` window keeps token cost ~150 tokens instead of loading the whole `wsdl_segment` (which can be 5K+ tokens on large types). Use this pattern any time `fields` returns a `Foo[]` type and you need Foo's sub-fields.

jq -r '.wsdl_segment' data/metadata_api/Profile.json | grep -A 30 'complexType name="ProfileObjectPermissions"'


`grep -A N`窗口可将令牌成本控制在约150个，而非加载整个`wsdl_segment`（大型类型可能超过5000个令牌）。每当`fields`返回`Foo[]`类型且您需要Foo的子字段时，请使用此模式。

XML Generation Errors

XML生成错误

Problem: Generated XML fails validation

Solutions:

Verify namespace is exactly:
```
http://soap.sforce.com/2006/04/metadata
```
Check all required fields are present
Ensure field values match expected types
Validate XML syntax (closing tags, proper nesting)

问题：生成的XML验证失败

解决方案：

验证命名空间是否完全为：
```
http://soap.sforce.com/2006/04/metadata
```
检查所有必填字段是否存在
确保字段值与预期类型匹配
验证XML语法（闭合标签、嵌套正确）

Deployment Failures

部署失败

Problem: Metadata file won't deploy

Solutions:

Run
```
sf project deploy validate
```
first
Check Salesforce API version compatibility
Verify file naming matches conventions
Ensure directory structure matches SFDX format

问题：元数据文件无法部署

解决方案：

先运行
```
sf project deploy validate
```
检查Salesforce API版本兼容性
验证文件命名是否符合规范
确保目录结构符合SFDX格式

Quick Reference: Common Metadata Types

快速参考：常见元数据类型

Here are the most frequently used metadata types:

CustomObject: defines the schema for a custom sObject, including fields, relationships, and settings
Flow: automates business processes using a visual canvas of elements and connectors
ApexClass: compiled Apex server-side class; includes body, API version, and status
ApexTrigger: Apex code that executes before/after DML events on a specific sObject
Profile: controls object/field permissions, app visibility, and login settings for a user profile
PermissionSet: additive set of permissions granted to users independently of their profile
CustomField: defines a field on a standard or custom object, including type, picklist values, and formula
Layout: controls the arrangement of fields and related lists on a record detail/edit page
ValidationRule: enforces data quality by preventing saves when a formula condition is true
ApexPage: Visualforce page definition, including controller reference and markup
ApexComponent: reusable Visualforce component that can be embedded in pages
CustomTab: defines a tab pointing to a custom object, Visualforce page, or web URL
CustomApplication: defines an app's tab bar, nav items, and branding
LightningComponentBundle: LWC bundle including JS, HTML, and metadata descriptor
AuraDefinitionBundle: Aura (Lightning) component bundle with component, controller, helper files
StaticResource: uploaded file (JS, CSS, image, ZIP) accessible from Visualforce and LWC
EmailTemplate: email template for use in workflow rules, Process Builder, or Apex
Report: saved report definition including filters, groupings, and columns
Dashboard: collection of dashboard components backed by reports

For a complete list of all metadata types, see Index Table.

以下是最常用的元数据类型：

CustomObject：定义自定义sObject的模式，包括字段、关系和设置
Flow：使用元素和连接器的可视化画布自动化业务流程
ApexClass：已编译的Apex服务器端类；包含代码主体、API版本和状态
ApexTrigger：在特定sObject的DML事件前后执行的Apex代码
Profile：控制用户配置文件的对象/字段权限、应用可见性和登录设置
PermissionSet：独立于用户配置文件授予用户的附加权限集
CustomField：定义标准或自定义对象上的字段，包括类型、选择列表值和公式
Layout：控制记录详情/编辑页面上字段和相关列表的排列
ValidationRule：通过在公式条件为真时阻止保存来确保数据质量
ApexPage：Visualforce页面定义，包括控制器引用和标记
ApexComponent：可嵌入页面的可重用Visualforce组件
CustomTab：定义指向自定义对象、Visualforce页面或Web URL的标签
CustomApplication：定义应用的标签栏、导航项和品牌标识
LightningComponentBundle：LWC包，包含JS、HTML和元数据描述符
AuraDefinitionBundle：Aura（Lightning）组件包，包含组件、控制器、助手文件
StaticResource：上传的文件（JS、CSS、图片、ZIP），可从Visualforce和LWC访问
EmailTemplate：用于工作流规则、Process Builder或Apex的电子邮件模板
Report：保存的报表定义，包括筛选条件、分组和列
Dashboard：由报表支持的仪表板组件集合

如需所有元数据类型的完整列表，请查看索引表。

platform-metadata-api-context-get

Original

Translation

Salesforce Metadata API Skill

Salesforce Metadata API 技能文档

Overview

概述

How to Use This Skill

如何使用本技能

⚡ CRITICAL: Section-Specific Consumption

⚡ 重要提示：按需加载特定章节

Quick Start

快速入门

Example Queries (Section-Specific)

示例查询（按需加载特定章节）

JSON File Structure

JSON文件结构

Available Sections

可用章节

Token Optimization Strategies

令牌优化策略

Section-Specific Loading (BEST PRACTICE)

按需加载特定章节（最佳实践）

What NOT to Do

禁止操作

When to Load Multiple Types

何时加载多种类型

When to Load Specific Sections (STRONGLY RECOMMENDED)

何时加载特定章节（强烈推荐）

Conceptual Approach to Using This Skill

使用本技能的思路

Step 1: Identify Your Need

步骤1：明确需求

Step 2: Find the Right Type

步骤2：找到正确的类型

Step 3: Load Selectively (Section-Specific) ⚡

步骤3：选择性加载（按需加载特定章节）⚡

Step 4: Apply to Your Code

步骤4：应用到代码中

File Location

文件位置

Path Resolution

路径解析

Metadata File Generation Requirements

元数据文件生成要求

XML Structure Requirements

XML结构要求

Namespace Declaration

命名空间声明

Required vs. Optional Fields

必填字段与可选字段

Validation Tips

验证提示

Duplicate and Ambiguous Type Names

重复和模糊的类型名称

Troubleshooting

故障排除

File Not Found

文件未找到

SOAP Envelope / Header Types (thin by design)

SOAP信封/头类型（设计上精简）

Missing Section

章节缺失

Incomplete Field Information

字段信息不完整

Following Sub-Type Pointers (e.g., ProfileObjectPermissions[])

跟踪子类型指针（例如ProfileObjectPermissions[]）

1. Get the field type name from the fields section

1. 从fields章节获取字段类型名称

→ {"type": "ProfileObjectPermissions[]", ...}

→ {"type": "ProfileObjectPermissions[]", ...}

2. Pull just the matching complexType from wsdl_segment using grep -A

2. 使用grep -A从wsdl_segment中提取匹配的complexType

XML Generation Errors

XML生成错误

Deployment Failures

部署失败

Quick Reference: Common Metadata Types

快速参考：常见元数据类型

Following Sub-Type Pointers (e.g.,
`ProfileObjectPermissions[]`
)

跟踪子类型指针（例如
`ProfileObjectPermissions[]`
）