Platform Metadata API Context Get

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)

Recommended:

• "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"

Avoid:

• "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"?>

2. Use correct namespace:

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

3. 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.