Custom Metadata Type
A Custom Metadata Type in Salesforce is a framework for creating custom, deployable, and packageable application metadata.
Definition
A Custom Metadata Type in Salesforce is a framework for creating custom, deployable, and packageable application metadata. Unlike Custom Settings (which store data), Custom Metadata Type records are treated as metadata and can be deployed between environments using Change Sets, packages, and the Metadata API. They are ideal for storing application configuration, mapping tables, and business rules that need to move with the application.
In plain English
“Custom Metadata Types let you store configuration data that travels with your code when you deploy. Unlike Custom Settings which hold regular data, Custom Metadata records are treated like metadata, so they go through Change Sets and packages just like Apex classes or page layouts.”
Worked example
Lacewing Software stores their pricing-tier configuration in a Custom Metadata Type called PricingTier__mdt - five records (Free, Starter, Pro, Business, Enterprise) each with fields for monthly cost, included seats, feature flags. Apex code reads the records via PricingTier__mdt.getAll(); deploy time, the entire pricing-tier dataset travels in the change set or unmanaged package along with the Apex code that uses it. If they used Custom Settings instead, the configuration data would have to be exported/imported separately from code deploys. Custom Metadata Types are the right choice when configuration data and the code that uses it should ship together.
Why Custom Metadata Type matters
A Custom Metadata Type is a framework for creating custom, deployable, packageable application metadata in Salesforce. You define a Custom Metadata Type in Setup much like you'd define a custom object, giving it fields and records. The key difference from Custom Settings is that Custom Metadata Type records are themselves treated as metadata. They can be retrieved via the Metadata API, included in Change Sets, shipped inside managed or unlocked packages, and promoted through CI/CD pipelines right alongside code.
This makes Custom Metadata Types the right choice for configuration data that needs to move with the application: mapping tables, business rule thresholds, integration endpoint URLs, feature flags, and lookup data. They're also queryable from Apex, Formula fields, Validation Rules, and Flows, so your code and automation can read the values without hardcoding. The main limits to know are that you generally update Custom Metadata records through deployments rather than runtime writes, and there are governor limits around how many you can query in a transaction. For anything that should be managed as code-adjacent configuration rather than runtime data, Custom Metadata Types are the modern answer.
How to create Custom Metadata Type
Custom Metadata Types are deployable metadata records — "environment-specific config," "mapping tables," "business rules" that move between sandboxes and production via Change Sets / DX. Modern replacement for Custom Settings: data IS metadata, so it deploys with the rest of your code. Admin-friendly to author; developer-friendly to read at runtime.
- Open Setup → Custom Metadata Types
Setup gear → Quick Find: Custom Metadata Types → Custom Metadata Types.
- Click New Custom Metadata Type
Top-right.
- Set Label, Plural Label, Object Name
Label is the display name. Plural Label is for the records collection. Object Name auto-derives with __mdt suffix.
- Set Visibility (Public / Protected)
Public: subscribers can read records. Protected: only the package owner. For internal types, Public is fine.
- Save → add Custom Fields to the type
Each Custom Metadata Type needs fields to store config values. Same field types as Custom Objects, plus Picklist, Checkbox, Number, Text.
- Add records via the Manage button
On the type's detail page → Manage → New. Each record is a deployable metadata row.
- Read at runtime via SOQL or @AuraEnabled metadata access
Apex: SOQL queries on the __mdt object. LWC: @wire to wire-adapter for metadata. Reads are cached and don't count against query governor limits.
Required.
Required. __mdt suffix.
Required.
- Custom Metadata Types replaced Custom Settings for new development. Modern best practice: use Custom Metadata for deployable config; use Custom Settings only for org-only config that shouldn't deploy.
- Records are metadata — every change to a record is a metadata change. Bulk record updates via UI are fine; via API in production is restricted (need Modify Metadata permission).
- SOQL queries on __mdt are FREE (don't count against governor limits) and CACHED. This is a key perf advantage — accessing config via Custom Metadata is fast.
How organizations use Custom Metadata Type
Stores integration endpoint URLs and credentials references in a Custom Metadata Type. When they deploy to a new environment, the endpoint metadata deploys with the code, so there's no manual Setup step after deployment.
Built a business rules engine backed by Custom Metadata Type records. Each rule (threshold, condition, action) is a metadata record, so changes to rules go through their normal Git and CI/CD process with full audit trail.
Uses Custom Metadata Types for feature flags. Flipping a feature on or off happens through a metadata deployment rather than a database update, keeping production changes traceable and reversible.
Trust & references
Straight from the source - Salesforce's reference material on Custom Metadata Type.
- Custom Metadata Types in ApexSalesforce Developers
Test your knowledge
Q1. What makes Custom Metadata Types different from Custom Settings?
Q2. Which is a good use case for Custom Metadata Types?
Q3. Can Custom Metadata Types be queried from Formula fields and Validation Rules?
Discussion
Loading discussion…