Metadata Component
A metadata component in Salesforce is a single configurable element of an org's setup, represented as an instance of a metadata type such as ApexClass, CustomObject, Flow, or PermissionSet.
Definition
A metadata component in Salesforce is a single configurable element of an org's setup, represented as an instance of a metadata type such as ApexClass, CustomObject, Flow, or PermissionSet. Components are not built on sObjects the way records are. Each one extends the Metadata base class and is identified by a fullName, so the platform treats an Apex class, a custom field, and a validation rule as the same kind of thing: a unit of configuration that tooling can read and write.
Every change an admin or developer makes touches one or more metadata components. The Metadata API is the programmatic interface for retrieving and deploying them, and the Salesforce CLI, DevOps Center, change sets, and packaging all sit on top of it. Knowing which components a change requires is the basis of any reliable deployment.
How metadata components are structured, moved, and tracked
A component is an instance of a metadata type
Salesforce models configuration as metadata types, and a component is one instance of a type. ApexClass, CustomObject, Flow, Profile, ValidationRule, and several hundred others all extend a shared Metadata base class. That base class gives each component a fullName, the value that uniquely names it within its type. This design is deliberately different from the SOAP API, where you work with records that map to sObjects. Here you work with the definition of the object itself, not the rows inside it. The practical effect is that two very different things, say an Apex trigger and a page layout, share one programming model. Tooling can list them, fetch their XML, and write them back using the same calls. When you read the Metadata API guide, the long list of types is really a list of the shapes a component can take. Understanding that a component is just a typed, named blob of configuration helps explain why deployments behave the way they do, and why a single feature in the UI can map to several components under the surface.
File-based deploy and retrieve
The most common way to move components is the file-based path. The deploy() and retrieve() calls work on a .zip archive that contains a project manifest named package.xml plus the component XML, arranged in folders by type. retrieve() pulls components out of an org into that archive, and deploy() uses the files to create, update, or delete components in a target org. A single operation can include up to 10,000 files, and the compressed archive can be up to 39 MB through the SOAP-based path. The manifest is the contract for the operation. It lists each type and the named members of that type, so the API knows exactly what to act on. Wildcards pull every component of a type, while explicit names target specific ones. A companion file, destructiveChanges.xml, names components to delete. Because the whole archive deploys as one transaction, a custom object and its dependent fields, validation rules, and triggers should travel together. Splitting them across separate deployments is a common cause of failures, since a component that references a missing dependency cannot be saved.
CRUD-based calls for one component at a time
Alongside the file-based path, the Metadata API offers CRUD-style calls that act on components more like ordinary API objects. createMetadata(), updateMetadata(), readMetadata(), upsertMetadata(), renameMetadata(), and deleteMetadata() let code work with components synchronously, passing the component definitions directly rather than zipping files. These calls suit tools that generate or edit configuration on the fly, such as a setup wizard that provisions a custom field. The trade-off is scale. CRUD-based calls handle a small batch per request, up to 10 components at a time, so they are not how you migrate a whole org. They also do not cover every metadata type, since the file-based path supports a broader set. Most teams reach for CRUD-based calls when an application needs to manipulate a handful of components programmatically, and reach for deploy() and retrieve() when moving real change sets between environments. Knowing both styles exist saves you from forcing one approach onto a problem better suited to the other.
Source format versus metadata format
Salesforce supports two file layouts for the same components. The original metadata format produces large XML files, where one CustomObject file holds every field, list view, and validation rule for that object. The source format used in Salesforce DX projects decomposes those big files into smaller ones, so a single custom field becomes its own file inside the object's folder. Decomposition makes the source far friendlier to git, because each change shows up as an edit to a small, focused file instead of a noisy diff on a giant one. By default a DX project decomposes custom objects and their translations, and you can opt to decompose other types such as permission sets and custom labels. The CLI bridges the two layouts. Running project convert mdapi turns retrieved metadata-format files into source format, and project convert source turns source-format files back into something deploy() can consume. The platform itself only ever consumes metadata format, so source format is best thought of as the developer-facing representation that gets converted on the way in and out.
Manifests, dependencies, and what travels together
A manifest is more than a file list. It encodes the boundary of a deployment, and getting that boundary right is most of the work. Components have references to each other, and a deploy fails if a referenced component is missing from both the package and the target org. A flow that updates a custom field needs that field present, and a permission set that grants access to an object needs the object too. Teams that build manifests by hand quickly hit this, which is why generating manifests from a git diff is the scalable pattern. The diff tells you which files changed, and tooling translates those files into the matching package.xml entries plus any dependencies. Order can matter as well, since some types must exist before others that point at them. The reward for treating the manifest seriously is predictable deployments. When the package contains a self-consistent set of components, the operation either applies cleanly or reports a precise error, instead of failing partway and leaving an environment in a half-migrated state.
Coverage limits and the Metadata Coverage Report
Not every feature is reachable through the Metadata API. Some configuration is UI-only with no API support, some is retrievable but not deployable, and some is fully supported. The Metadata Coverage Report is the source of truth for this, documenting support per type across several channels, including the Metadata API, source tracking, unlocked packages, second-generation managed packages, and classic managed packages. You pick an API version and read off what each type supports, which is the fastest way to avoid building a migration plan around a component that cannot move. One change worth tracking: the current report tied to API v66 in the Spring 26 release is the last version of that report. Salesforce plans to keep it available through Summer 26 while transitioning to a replacement, and the old report is set to retire in Winter 27. Whichever report is live, checking coverage before a complex migration saves hours of trial-and-error, because it tells you up front which parts of a feature you can automate and which you may have to configure by hand.
Change sets, packages, and CI/CD all sit on components
The same components flow through every deployment tool, just wrapped in different workflows. Change sets are the declarative option, where an admin picks components in the UI, bundles them, and deploys from sandbox to production. Underneath, a change set is a managed wrapper around the Metadata API, moving the same XML with a picker and an approval step layered on top. Managed and unlocked packages bundle components for installation in other orgs, with a namespace applied so the installed components do not collide with what is already there. DevOps Center and custom CI/CD pipelines automate the retrieve, version, and deploy cycle, usually pulling components into source format, committing them to git, and deploying from there. Seen this way, the component is the constant and the tool is the variable. Whether you click through a change set, install a package, or run a pipeline, you are moving instances of metadata types from one org to another. That is why a solid grasp of components transfers across whatever deployment method a team happens to use.
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Metadata Component.
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 does a single Metadata Component represent in an org's configuration?
Q2. Which interface lets tooling retrieve and deploy Metadata Components programmatically?
Q3. Which of these is a valid Metadata Component type exposed by the Metadata API?
Discussion
Loading discussion…