Metadata Type
A Metadata Type in Salesforce is a category of platform configuration that the Metadata API understands as a single unit of deployable, retrievable, and version-controlled material.
Definition
A Metadata Type in Salesforce is a category of platform configuration that the Metadata API understands as a single unit of deployable, retrievable, and version-controlled material. Examples include CustomObject, ApexClass, Layout, Flow, PermissionSet, ValidationRule, Profile, EmailTemplate, and well over 200 others as of recent releases. Each metadata type defines the shape of its data, the operations the Metadata API supports on it, and the rules for how it interacts with other types during deploy and retrieve.
The concept of a metadata type is fundamental to every DevOps workflow on the Salesforce platform. Every change set, every SFDX deploy, every metadata API package.xml manifest, and every source-tracked sandbox sync references metadata by type and full name. Understanding what each type contains, which types depend on others, and which types have idiosyncratic deploy behavior is the difference between a smooth release pipeline and a chronic source of mid-deploy failures.
How metadata types organize the platform
Type hierarchy: containers, items, and references
Salesforce metadata types fall into rough categories. Container types (CustomObject, Layout, Profile) hold child elements (fields, sections, permissions) that the API treats either as separately addressable members or as bundled children. Item types (ApexClass, EmailTemplate, StaticResource) are single self-contained files. Reference types (CustomField, ProfileFieldPermission) only make sense in the context of a parent. The hierarchy matters because the Metadata API has rules about whether you can deploy a child without its parent. A CustomField deploys with its parent CustomObject in source format but stands alone in metadata format, which catches developers off-guard the first few times.
The package.xml manifest
The package.xml file is the canonical manifest that tells the Metadata API which metadata to deploy or retrieve. It lists types and their members: <types><members>Account</members><name>CustomObject</name></types>. A wildcard members entry (*) requests every member of that type, with caveats: some types do not support wildcards (Profile, PermissionSet often need explicit member lists for the API to know what to compare). Building the right package.xml is fundamental to Salesforce DevOps; the SFDX CLI generates one automatically from source folders, but understanding what is in it remains a useful skill for debugging deploys.
Deployment dependencies and order
Some metadata types depend on others being deployed first. ApexClass that references a CustomField needs the CustomField to exist in the target org. Profile permission rows for an object only deploy if the CustomObject is present. The Metadata API resolves most of these dependencies automatically during a single deploy operation, but cross-deploy ordering still matters. If you deploy in two separate runs (object first, profile second), the order of the runs is your responsibility. SFDX tools and DevOps Center handle this transparently for source-tracked sandboxes, but the underlying logic is still about metadata-type dependencies.
Versioning and API versions
Every metadata type has a minimum API version at which it was introduced and a current API version. Components are stored with a specific API version in their metadata XML, and Salesforce honors that version for backward compatibility. When new functionality is added to a metadata type (new fields, new sub-elements), only components built against the new API version see the new functionality. This is the mechanism that lets the platform evolve metadata without breaking existing customizations, and it is why Salesforce strongly recommends keeping ApexClass, LWC, and Flow API versions current.
Source format versus metadata format
Salesforce supports two on-disk representations of metadata. Metadata format is the older flat structure where each metadata type is a single XML file (Account.object containing fields, validation rules, etc.). Source format, used by SFDX, 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 is friendlier to source control because diffs and merges work cleanly. Converting between the two formats is one of the standard SFDX operations and is required when going between source-format projects and Metadata-API-based legacy tooling.
Types that surprise builders
Several metadata types have quirks worth knowing. Profile and PermissionSet deploys often fail because the target object or field does not exist or because a profile references a removed component. CustomLabel deploys are append-only; you cannot remove a label through a normal deploy. Workflow rules and process builders deploy as full snapshots, not differential updates. Reports and Dashboards have their own folder semantics that work differently from other types. Each of these quirks is documented but unintuitive, and senior Salesforce developers carry a mental list of which types need special handling in their pipelines.
Custom Metadata Types versus the Metadata API
Custom Metadata Types (CMT) is a confusingly named feature that is not the same as the Metadata API concept of metadata types. CMTs are a feature for storing configuration data inside the org as queryable records that behave more like metadata than data: they migrate through deploys, can be referenced from formulas and validation rules, and are not subject to the usual record-level DML. Both concepts use the word "metadata" but in different senses. The Metadata API types are the platform's classification of deployable artifacts; CMTs are a specific tool for app-defined configuration.
Destructive changes and the cleanup story
Removing metadata is harder than adding it. The standard Metadata API supports a destructiveChanges.xml file alongside the package.xml that lists components to delete. Each entry specifies a metadata type and the full name of the member to remove. The deploy applies the destructive changes after the package changes complete, which is the right order: add the replacement, then delete the original. DevOps Center handles this well; raw SFDX requires you to author the destructiveChanges.xml manually. Several metadata types have restrictions on what can be deleted through the API: standard fields cannot be removed, system permissions cannot be revoked, and some objects have referential integrity that requires manual cleanup of dependent records first. Cleanup is also where the org accumulates the most cruft: old workflow rules, unused custom fields, orphaned page layouts. A quarterly cleanup sweep is worth the investment because deploys get slower and harder as the metadata footprint grows.
Metadata-driven release management strategies
Mature Salesforce orgs adopt a few common patterns for metadata-based release management. Per-feature branching: each feature gets its own branch and PR, with branch-level CI running validation deploys against an integration sandbox. Source-of-truth orgs: one designated sandbox is the canonical source, and all changes flow from sandbox to source control to other sandboxes and production. Promotion paths: changes promote through dev, test, UAT, and production sandboxes in sequence rather than jumping straight from dev to production. The success of each pattern depends less on tool choice and more on team discipline around metadata-type discipline: knowing which types travel with each change, when to use destructive changes, and when a manual configuration in the target org is faster than fighting the deploy pipeline. The platform makes metadata-based DevOps possible; the team's discipline makes it work in practice.
Work with metadata types in deployments
Understanding metadata types is one thing; using them well in a release pipeline is another. The workflow below covers the standard sequence for retrieving, modifying, and deploying metadata in an SFDX-based project, which is the modern way to work with the Metadata API.
- Identify the metadata types affected by your change
For each business change, list the metadata types involved. A new field involves CustomField, possibly Profile or PermissionSet, possibly Layout, possibly ValidationRule. A new Lightning page involves FlexiPage. A new Flow involves Flow and possibly Permission or Object dependencies. Make this list before writing code so you know what will travel through the pipeline. Surprises during deploy almost always trace back to a metadata type that was overlooked at this step.
- Retrieve from sandbox into your local source
Use sfdx force:source:retrieve --metadata Type:Name to pull the specific component into your local project, or use the source tracking commands to pull every change since your last sync. Inspect the resulting files in source format. Each metadata type becomes one or more XML files under its parent folder. Commit the retrieval before making your edits, so the diff between original and modified state is clean for code review.
- Make and commit your changes
Edit the XML or component files locally. Add new fields by adding new files (in source format) or new sub-elements (in metadata format). Update existing components by modifying the right files. Run any local validation (sfdx force:source:validate or build pipeline checks). Commit each logical change as a separate commit so the history tells the story of what changed and why. Push to your branch and open a pull request for review.
- Deploy to the target org with a validated package.xml
After approval, run sfdx force:source:deploy or use DevOps Center to push the changes to the target org. The deploy goes through dependency resolution, running tests for any Apex changes (75% coverage required for production), and reporting any conflicts. Read the deploy output carefully; metadata-type-specific errors usually point exactly at what is missing or misconfigured. Successful deploys move you to the next environment in the pipeline; failures send you back to fix the issue.
- Wildcard package.xml entries do not work for all metadata types. Profile and PermissionSet need explicit member lists in many cases.
- Source format and metadata format are not interchangeable inside a single project. Pick one and stick with it. SFDX projects use source format by default.
- Dependency order matters across deploys. A profile referencing a removed object fails to deploy. Remove the dependency first, then redeploy the profile.
- CustomLabel removals require manual editing in the target org or destructiveChanges.xml; the standard deploy treats CustomLabel as append-only.
- Some metadata types do not deploy through change sets at all. Check the metadata coverage report before assuming a type is change-set-deployable.
Trust & references
Cross-checked against the following references.
- Metadata Types ListSalesforce Developer Docs
- Metadata Coverage ReportSalesforce Developer Docs
Straight from the source - Salesforce's reference material on Metadata Type.
- Metadata API Developer GuideSalesforce Developer Docs
- Salesforce DX Developer GuideSalesforce Developer Docs
- DevOps CenterSalesforce Help
Hands-on resources to go deeper on Metadata Type.
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 Type?
Q2. Where are metadata types used?
Q3. How many metadata types does Salesforce support?
Discussion
Loading discussion…