Metadata Component
A Metadata Component in Salesforce is a single configurable element of an org''s configuration: an Apex Class, a Custom Object, a Workflow Rule, a Lightning Page, a Permission Set, a Profile, a Validation Rule, or any of the hundreds of other configuration types Salesforce exposes via the Metadata API.
Definition
A Metadata Component in Salesforce is a single configurable element of an org''s configuration: an Apex Class, a Custom Object, a Workflow Rule, a Lightning Page, a Permission Set, a Profile, a Validation Rule, or any of the hundreds of other configuration types Salesforce exposes via the Metadata API. Every change an admin or developer makes to a Salesforce org modifies one or more metadata components. The Metadata API is the programmatic interface for retrieving, deploying, and modifying these components; the Salesforce CLI, DevOps Center, Change Sets, and CI/CD pipelines all operate on metadata components.
Metadata Components are the unit of versioning, deployment, and source-control in modern Salesforce DX projects. The SFDX source format stores each component as a file (or set of files) in a folder structure organized by component type. Change Sets bundle components for sandbox-to-production deployment. Managed packages distribute components for installation in subscriber orgs. Understanding which components are needed for a given change is the foundation of accurate Salesforce deployment planning.
The Metadata Component model behind every Salesforce configuration
Hundreds of component types
Salesforce exposes hundreds of metadata component types. Common types: ApexClass, ApexTrigger, CustomObject, CustomField, Flow, Profile, PermissionSet, ValidationRule, WorkflowRule, EmailTemplate, LightningPage, AuraDefinitionBundle, LightningComponentBundle, Layout, ListView, Report, Dashboard, Approval Process, Connected App, Named Credential, Custom Metadata, Custom Label. The Metadata API documentation lists every type.
The Metadata API
The Metadata API is the programmatic interface for working with metadata components. Customers and tooling use the API to retrieve component XML from an org, deploy component XML to an org, and modify components programmatically. The Salesforce CLI wraps the API for command-line workflows; DevOps Center wraps it for declarative deployments.
Source format vs. metadata format
Salesforce supports two file formats for metadata components. The legacy Metadata API format produces large XML files per object (all fields in one CustomObject.object file). The modern SFDX source format splits each component into separate files (one file per CustomField). Source format is designed for git, scratch orgs, and CI/CD; metadata format is the format the platform actually consumes.
Manifest files
Manifest files (package.xml, destructiveChanges.xml) declare which metadata components are part of a retrieve or deploy operation. The manifest specifies the component type and the named members of that type. Wildcards (*) include every component of a type; explicit names target specific ones.
Metadata Coverage Report
Not every Salesforce feature is supported by the Metadata API. Some configurations are UI-only (no API support), some are partially supported (retrievable but not deployable), some are fully supported. The Metadata Coverage Report documents the support level per component type per release; check it before assuming a feature can be migrated through the API.
Change Sets as a metadata wrapper
Change Sets are Salesforce''s declarative deployment tool. Admins pick metadata components in the UI, build a Change Set, and deploy from sandbox to production. Behind the scenes, Change Sets are a wrapper around the Metadata API; the same components, the same XML, just with a UI for picking and a workflow for approval.
Managed packages and Metadata Components
AppExchange packages bundle metadata components for installation in customer orgs. Each managed package declares the components it contains; installing the package adds those components to the customer''s org with a namespace prefix. The package metadata is the same set of types as direct deployments, just with packaging-specific declarations.
Work with Metadata Components in modern Salesforce DX
Metadata Components are the unit of work in any Salesforce deployment. The day-to-day workflow uses SFDX CLI and source-format projects.
- Retrieve components from an org
Run sf project retrieve start -m ApexClass:MyClass -m CustomObject:Account -o my-org. The CLI pulls the listed components into the local project in source format.
- Edit in VS Code
Open the SFDX project. Edit the component source files. The Salesforce Extensions Pack provides syntax highlighting, validation, and IntelliSense.
- Deploy to an org
Run sf project deploy start -m ApexClass:MyClass -o my-org. The CLI deploys the listed components. Use -x manifest/package.xml for larger sets.
- Version-control with git
Commit changes to git. Open pull requests. The SFDX source format produces clean diffs at the file level.
- Check the Metadata Coverage Report
Before assuming a configuration can be deployed, verify the component type is supported by the Metadata API.
- Build CI/CD pipelines
Modern pipelines (Copado, AutoRabit, Gearset, GitHub Actions) generate manifest files from git diffs and deploy automatically.
- Not every configuration is API-supported. Check the Metadata Coverage Report before planning a migration.
- Source format and metadata format are different. Modern tools default to source format; legacy projects may need conversion.
- Deployments may fail due to dependencies. Component A may require component B; deploying out of order fails. Group related components in the same manifest.
- Some metadata types behave differently in managed packages. Test before relying on cross-org package deployments.
Trust & references
Cross-checked against the following references.
- Metadata API Developer GuideSalesforce Developers
- Metadata Coverage ReportSalesforce Developers
Straight from the source - Salesforce's reference material on Metadata Component.
- Salesforce DX Developer GuideSalesforce Developers
Hands-on resources to go deeper on Metadata Component.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Metadata Component?
Q2. How can metadata components be deployed?
Q3. Do all component types support deployment?
Discussion
Loading discussion…