Salesforce metadata is the configuration of your org: the objects, fields, page layouts, flows, Apex code, permission sets and settings that decide how Salesforce looks and behaves. Data is the records stored inside that structure. Salesforce also gives you three ways to store your own configuration values: custom metadata types, custom settings and custom labels. This guide explains each and when to use which.
This guide was first published in 2020 as "What Is Salesforce Metadata?" and now also covers our older posts on custom settings and custom labels. It has been rewritten for 2026.
What is metadata in Salesforce?
Metadata in Salesforce is everything that defines your org rather than the records in it. Metadata is "data about data": it describes the shape of your records and the rules around them. Salesforce's Metadata API Developer Guide gives the clearest example. Address fields such as Address Type, City and Postal Code are schema metadata; the values in them, such as "Mailing address", "Chicago, IL" and "60106", are data.
Common kinds of metadata include:
- Schema: custom objects, fields, record types, relationships.
- User interface: page layouts, Lightning pages, Lightning web components, Visualforce pages.
- Logic and automation: flows, validation rules, Apex classes and triggers.
- Access: profiles, permission sets, sharing rules.
- Configuration you define: custom metadata types, custom settings and custom labels, covered below.
Metadata vs data: why the difference matters
Metadata moves through deployments and source control; data moves through data tools. The split decides which tool moves what. The Metadata API deploys, retrieves, creates, updates and deletes customization such as custom object definitions and page layouts, and, as the developer guide says, it does not work directly with business data; records such as accounts and leads go through the SOAP or REST API.
| Metadata | Data | |
|---|---|---|
| What it is | Structure, logic and settings | Records: accounts, cases, orders |
| Example | The Postal Code field, a validation rule | The value 60106 on one contact |
| Copied into Developer sandboxes | Yes | No |
| Moved between orgs with | Metadata API, Salesforce CLI, change sets, DevOps tools | Data Loader, REST or SOAP API, Bulk API |
| Belongs in version control | Yes | No (except reference data you treat as config) |
In practice this is why a release process works on metadata: you build in a sandbox, store the metadata in source control and deploy it forward, as our Salesforce DevOps guide describes. Records are loaded with tools such as Data Loader.
How to retrieve and view Salesforce metadata
Retrieve metadata with the Salesforce CLI, using a package.xml manifest that lists the components you want.
- Build a manifest.
sf project generate manifestcreates a package.xml from your project or from an org; or write one by hand listing types such asApexClass,CustomObjectandFlow. - Retrieve. The CLI reference gives
sf project retrieve start --manifest manifest/package.xml --target-org MyOrg. You can scope by--manifest,--metadataor--source-dir, but only one at a time. - Commit it to source control, so every change is reviewed and can be rolled back.
For quick one-off looks, Setup shows most metadata in Object Manager, and tools such as Workbench or the Salesforce Inspector Reloaded extension can retrieve or inspect it from the browser.
What are custom metadata types?
Custom metadata types store your own configuration as metadata, so the values deploy with your code. A custom metadata type is an object that defines the structure for your own application configuration, and, in Trailhead's words, its records are also metadata, not data. Its API name ends in __mdt. Because the records are metadata, they travel with the type: when you package or deploy a custom metadata type, its records go too, through change sets or the Metadata API.
Typical uses, from the same Trailhead module:
- Mappings, such as which region each country or state belongs to.
- Business rules, such as which payment endpoint handles which kind of transaction, read by Apex.
- Reference values, such as tax or duty rates that several apps share.
Custom metadata types can be referenced from Apex, flows, formula fields and validation rules, and they support relationship fields to other custom metadata types. They do not support hierarchy values that differ by user, profile or org.
What are custom settings in Salesforce?
Custom settings store configuration as data, with optional per-user or per-profile values. Custom settings are an older way to store configuration in a custom object-like structure, with an API name ending in __c. There are two kinds:
- List custom settings hold a reusable set of values, such as a list of country codes.
- Hierarchy custom settings hold a value that can be set at org level and overridden for a profile or a single user, so the most specific value wins.
The catch is deployment: when you deploy a custom setting, only its definition moves and the records are left behind, as Trailhead's comparison points out, so every sandbox and production org needs its values loaded separately. Salesforce Help's custom settings page now says Salesforce strongly suggests using custom metadata types instead.
Custom settings vs custom metadata types: which should you use?
Use custom metadata types by default; use hierarchy custom settings only when a value must differ by user or profile.
| Custom metadata types | Custom settings | |
|---|---|---|
| Suffix | __mdt | __c |
| Records are | Metadata | Data |
| Records deploy and package with the definition | Yes | No, definition only |
| Values by user or profile | No | Yes (hierarchy type) |
| Relationship fields | Yes, to other custom metadata types | No |
| Changing records from Apex | Through the Apex Metadata API | Normal insert, update and delete |
| Salesforce's recommendation for new work | Preferred | Use when you need hierarchy values |
Our rule of thumb: use a custom metadata type for anything that should be identical in every environment and promoted through your release pipeline. Use a hierarchy custom setting only when a value really must differ per user or profile, such as a switch that turns an integration off for one integration user. Values that change often at runtime, such as counters, belong in records, not in either.
How to convert list custom settings to custom metadata types
List custom settings convert easily; hierarchy custom settings usually should stay as they are. Trailhead's conversion unit calls converting list custom settings easy, and does not recommend converting hierarchy custom settings. The steps:
- Create a custom metadata type for each list custom setting, keeping the same field names so your code needs fewer changes.
- Load the existing values as custom metadata records. The Salesforce CLI can create records and load them from a CSV file.
- In Apex classes and triggers, change object references from
__cto__mdt; field names keep their__csuffix. - Replace custom setting accessor methods with SOQL queries on the new type, and refactor any code that inserts or updates setting records to use the Apex Metadata API.
- Test in a sandbox, deploy, then delete the old custom setting and its supporting code.
What are custom labels in Salesforce?
Custom labels are reusable, translatable text strings. Custom labels are text values, such as error messages, help text and button captions, stored once and referenced wherever they are needed. According to the Apex Label class reference, a custom label can hold up to 1,000 characters, and Salesforce Help's Custom Labels page allows up to 5,000 labels per org as of November 2026. Labels can be used from Apex classes, Visualforce pages, Lightning pages and Lightning components. To show a label in other languages, turn on Translation Workbench and add translations; Salesforce then shows each user the version for their language.
Use custom labels for anything a user reads and that might need translating or rewording later. Don't use them as a general configuration store: a custom metadata type is easier to manage when you have many related values.
Common metadata mistakes to avoid
Most metadata problems come from hardcoding, drift between environments and secrets in the wrong place.
- Hardcoding IDs, URLs and thresholds in Apex. Put them in a custom metadata type so they can change without a code deployment.
- Forgetting custom setting records in a release. They don't deploy with the definition; plan a data step or move to custom metadata types.
- Changing metadata directly in production. It makes environments drift; change it in a sandbox and deploy.
- Hardcoded user-facing text. Strings inside code can't be translated; use custom labels.
- Storing secrets in plain configuration. Credentials belong in named credentials (or encrypted custom fields), not in custom metadata, settings or labels any admin can read; Salesforce's Apex reference advises against storing secrets in custom metadata records.
Getting help
Well-organised metadata is what makes an org easy to change. Techila is a Salesforce Summit Partner; our Salesforce development services team designs configuration models, moves custom settings to custom metadata types and sets up release pipelines. See also our guide to Salesforce Workbench for retrieving metadata, or talk to us about your org.
Frequently asked questions
What is metadata in Salesforce?
Metadata is the configuration that defines your org: objects, fields, page layouts, flows, Apex code, permission sets and settings. Data is the records stored in that structure, such as accounts and leads. A field called City is metadata; the value Chicago in it is data.
What is the difference between custom settings and custom metadata types?
Both store configuration, but custom metadata type records are metadata, so they deploy and package with the type, while custom setting records stay behind and must be loaded separately. Custom settings can be hierarchical (org, profile, user); custom metadata types cannot. Salesforce recommends custom metadata types for new work.
Are custom settings deprecated?
No, custom settings still work, but Salesforce Help says it strongly suggests using custom metadata types instead. Hierarchy custom settings remain useful when a value must differ by user or profile, which custom metadata types do not support.
What are custom labels used for in Salesforce?
Custom labels hold text values, such as messages and button text, that Apex, Visualforce, Lightning pages and Lightning components can reference. They can be translated with Translation Workbench, which makes them the standard way to build multilingual user interfaces. Each label can hold up to 1,000 characters.
How do I move metadata between Salesforce orgs?
Use the Metadata API, usually through the Salesforce CLI, a DevOps tool or change sets. The API deploys and retrieves configuration but does not move business records; use Data Loader, the REST API or the SOAP API for those.