Metadata
Metadata in Salesforce is the data that describes the org's configuration, customizations, and structure rather than the business records the org operates on.
Definition
Metadata in Salesforce is the data that describes the org's configuration, customizations, and structure rather than the business records the org operates on. It includes definitions of objects, fields, page layouts, validation rules, Apex classes, Flows, Permission Sets, Profiles, Sharing Rules, Reports, Dashboards, and every other component that makes up the Salesforce environment. Metadata is what gets deployed between orgs through Change Sets, Salesforce DX, or DevOps Center, and it is the foundation of source-driven development on the platform.
Understanding the metadata concept is essential to any non-trivial Salesforce work because every customization the admin or developer makes produces or modifies metadata. When you create a custom field, you create CustomField metadata. When you write Apex code, you create ApexClass metadata. When you build a Flow, you create Flow metadata. The Salesforce Metadata API treats all of these as instances of metadata types, with a unified deploy and retrieve interface. The shift from clicks-only configuration to source-driven development through metadata is one of the most significant Salesforce platform evolutions of the past decade.
Metadata in the Salesforce platform model
Data versus Metadata
The distinction between data and metadata is fundamental. Data is the business records the org operates on: Accounts, Contacts, Opportunities, Cases, and the custom object records the customer creates. Metadata is the configuration that defines what these records look like and how they behave: the fields on the Account object, the validation rules that fire when an Opportunity is saved, the Flow that runs when a Case status changes. Data is migrated through Data Loader; metadata is migrated through Change Sets, SFDX, or DevOps Center. Both are first-class concepts in Salesforce, with distinct APIs (Object API for data, Metadata API for metadata) and distinct deployment paths.
Metadata types and their structure
Every piece of metadata belongs to a metadata type: CustomObject, CustomField, ApexClass, Flow, PermissionSet, ValidationRule, Profile, Layout, EmailTemplate, and over 200 others. Each type has its own structure, expressed as an XML schema or JSON schema depending on the API surface. A CustomObject definition includes fields, validation rules, record types, page layouts. An ApexClass includes the Apex source code and metadata about its API version and access modifier. The Metadata API operates on these types as units of deploy and retrieve, with conventions for how each type's structure is represented on disk.
Source format and metadata format
Salesforce supports two on-disk representations of metadata. Metadata format is the original flat structure where each metadata type is a single XML file (Account.object containing all fields, validation rules, layouts inline). Source format, used by Salesforce DX, breaks the same metadata into smaller files: each field, validation rule, and record type becomes its own XML file under the parent object's folder. Source format produces cleaner Git diffs, easier merges, and better per-component history. Most modern projects use source format; legacy projects on metadata format can convert as part of a DevOps modernization effort.
The package.xml manifest
The package.xml file is the canonical manifest for Metadata API operations. It lists metadata types and their members: <types><members>Account</members><name>CustomObject</name></types>. A wildcard members entry (asterisk) requests every member of that type. For deploy operations, package.xml specifies what to deploy; for retrieve operations, it specifies what to retrieve. Building the right package.xml is a fundamental DevOps skill: too narrow and the deploy misses dependencies, too wide and it includes more than intended and risks overwriting unrelated customizations. SFDX tools generate package.xml automatically from source folders, but understanding what it contains remains essential for debugging.
Versioning and API versions
Every metadata component has an API version, the Salesforce release at which the component was last edited. The platform honors backward compatibility, so components built against older API versions continue to work even as newer versions of the platform release. When new functionality is added to a metadata type (new fields on a built-in element, new sub-elements), only components built against the new API version see the new functionality. This versioning is what lets Salesforce evolve the platform without breaking existing customizations. Best practice is to keep ApexClass and LWC component API versions current to ensure access to the latest platform features.
Metadata API versus Tooling API
Salesforce exposes metadata operations through two complementary APIs. The Metadata API is the deploy-and-retrieve interface optimized for moving metadata between orgs and source control. The Tooling API is the granular interface optimized for development tools that need to read and write individual metadata components. Salesforce DX and DevOps Center use both APIs depending on the operation. For most customer DevOps work, the Metadata API is what matters; the Tooling API is what makes tools like the Developer Console and VS Code extensions work but is rarely used directly by customers.
Custom Metadata Types: a specific feature versus the general concept
Custom Metadata Types (CMT) is a specific Salesforce feature for storing configuration data inside the org as queryable records that behave like metadata: they migrate through deploys, can be referenced from formulas and validation rules, and are not subject to the usual record-level DML. The naming is confusing because Custom Metadata Type uses the word metadata but is a different concept from the general Metadata API. The Metadata API operates on platform-defined metadata types; Custom Metadata Types is a customer-defined feature that creates new addressable metadata-like records. Both use the word metadata but they refer to different abstractions. Knowing which one is being discussed in any given conversation requires context.
Metadata cleanup and technical debt
Over years of operating a Salesforce org, metadata accumulates. Old workflow rules that nobody remembers what they do. Custom fields nobody uses. Profiles cloned five times and slightly modified each. Apex classes that reference long-removed objects but persist because they happen to compile. Validation rules that fire on records the business no longer creates. Each piece of dead metadata adds friction to every deploy, every code review, every new admin trying to understand the org. The cumulative effect is technical debt that slows the team down and increases the risk that any change breaks something unexpected. Mature Salesforce programs invest in periodic metadata cleanup: a quarterly sprint that identifies and removes dead metadata, with appropriate caution to avoid removing anything still in use. Tools like Salesforce Optimizer help identify candidates for removal: unused fields, unused workflow rules, unused Apex classes. The cleanup work is rarely glamorous and never delivers immediate business value, but the long-term effect is a healthier org that supports faster delivery of new features. Programs that skip the cleanup work eventually find themselves unable to make changes safely; the technical debt has accumulated to the point where every change risks breaking something else. The right operating discipline is to budget cleanup work alongside feature work, treating the metadata footprint as a long-term asset that needs maintenance like any other infrastructure.
Work with metadata effectively
Working effectively with Salesforce metadata combines knowing the metadata types involved in your changes, using the right tools for deploy and retrieve, and following source-control discipline. The workflow below covers the standard sequence for a metadata-based development project.
- Set up a Salesforce DX project
Install the Salesforce CLI and the Salesforce Extensions for VS Code. Initialize a new SFDX project (sf project generate). Set up the project structure with packageDirectories for each logical grouping of metadata. Authorize the relevant orgs (Dev Hub, sandboxes, production). Configure source tracking on the development sandbox if available. Commit the initial project structure to source control before any changes.
- Retrieve existing metadata into source
For changes to existing metadata, retrieve the current state from the org into your local project (sf project retrieve start). Choose between retrieving everything (broad but slow) or specific metadata types and members (targeted but requires knowing what to retrieve). Inspect the retrieved files in source format. Commit the baseline before making any edits, so the diff between baseline and your changes is clear.
- Make and test changes locally
Edit the metadata files locally. For each change, document what is changing and why. Run any local validation. Push the changes to a scratch org or dev sandbox (sf project deploy start). Test the changes against representative data. Iterate until the changes work as expected. Commit each logical change as a separate commit so the source history tells the story of what was done.
- Deploy through the pipeline to production
After local testing, deploy through the standard pipeline. For SFDX-based pipelines, push the source branch and let CI/CD build and validate. For Change Set-based pipelines, package the changes and promote. For DevOps Center, follow the work-item promotion flow. At each stage, run tests and validate the metadata deploys cleanly. Resolve any conflicts or dependencies. Document the production deployment in the team's release log.
- Source format and metadata format are not interchangeable in a single project. Pick one and stick with it.
- Profile and PermissionSet deploys often fail because of references to removed components. Audit before deploying.
- Wildcard package.xml entries do not work for all metadata types. Some require explicit member lists.
- Custom Metadata Types (the feature) are not the same as metadata types (the platform concept). Be precise about which you mean.
- Some metadata types are not deployable through change sets. Check the Metadata Coverage Report.
Trust & references
Cross-checked against the following references.
- Metadata API Developer GuideSalesforce Developer Docs
Straight from the source - Salesforce's reference material on Metadata.
- Metadata APISalesforce Developer Docs
- Salesforce DXSalesforce Developer Docs
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. Where would a developer typically work with Metadata?
Q2. What is required before deploying Metadata-related code to production?
Q3. What skill set is typically needed to work with Metadata?
Discussion
Loading discussion…