Salesforce Metadata API Skill

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.

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

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 assets/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.

Quick Start

To get information about a specific metadata type:

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

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)

JSON File Structure

Each metadata type is stored as a JSON file in assets/metadata_api/ with the following structure:

{
  "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).

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.

Token Optimization Strategies

CRITICAL: To minimize token usage and costs:

1. Load only the specific metadata type(s) you need, not the full corpus
2. 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):

1. Read the JSON file
2. Parse it into a data structure
3. Extract ONLY the sections you need (e.g., fields, description)
4. Ignore verbose sections (wsdl_segment, declarative_metadata_sample_definition)

What NOT to Do

❌ NEVER use the read_file tool on these JSON files:

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

❌ NEVER load all files:

read_file assets/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

When to Load Multiple Types

• Related types: CustomObject + CustomField + ValidationRule
• Permission sets: Profile + PermissionSet + PermissionSetGroup
• UI components: Layout + CompactLayout + QuickAction
• Automation: 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:

1. First, check available sections by reading just the sections array from the JSON
2. Extract only the sections you need (e.g., fields for field definitions, description for overview)
3. Skip WSDL segments unless you specifically need schema validation
4. 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.

Conceptual Approach to Using This Skill

Step 1: Identify Your Need

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)

Step 2: Find the Right Type

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

Step 3: Load Selectively (Section-Specific)

Decision Tree for Section Loading:

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

Step 4: Apply to Your Code

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

File Location

All metadata type JSON files are located in:

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

Path Resolution

When using this skill, files are referenced as:

• Absolute: assets/metadata_api/CustomObject.json
• Relative to skill root: ./assets/metadata_api/CustomObject.json

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

Metadata File Generation Requirements

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

XML Structure Requirements

All metadata files must:

1. Include XML declaration:

   <?xml version="1.0" encoding="UTF-8"?>

1. Use correct namespace:

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

1. Match root element to metadata type:

• CustomObject → <CustomObject>
• Flow → <Flow>
• Profile → <Profile>
• etc.

Namespace Declaration

The namespace is required and must be exactly:

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

Correct:

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

Incorrect:

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

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):

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

1. Validate XML syntax: Ensure well-formed XML (matching tags, proper nesting)
2. Check required fields: Verify all required fields are present
3. Verify namespaces: Namespace must be exact
4. Test field types: Ensure field values match expected types
5. 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.

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:

1. Metadata API XML structure for source/deployment authoring (this skill, e.g. .profile-meta.xml, .cls-meta.xml).
2. Enterprise/Data API runtime sObject/record reference (no dedicated skill currently — fall back to the Salesforce API family router).
3. 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.

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.

SOAP Envelope / Header Types (thin by design)

Two related patterns to recognize:

1. 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.
2. 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.

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)

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

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

When the fields section gives a complex type name like ProfileObjectPermissions[] or LayoutItem[] or 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:

# 1. Get the field type name from the fields section
jq '.fields.objectPermissions' assets/metadata_api/Profile.json
# → {"type": "ProfileObjectPermissions[]", ...}

# 2. Pull just the matching complexType from wsdl_segment using grep -A
jq -r '.wsdl_segment' assets/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.

XML Generation Errors

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)

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

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.