Custom Metadata Types (CustomObject) | Metadata API Developer Guide

For more information, see the Custom Metadata Types Implementation Guide.

File Suffix and Directory Location

A custom metadata type is defined as a custom object and is stored in the objects folder. Custom metadata types have a suffix of __mdt (instead of __c for custom objects). Custom metadata type field names have a suffix of __c, like other custom fields. Custom metadata type field names must be dot-qualified with the name of the custom metadata type to which they belong.

Names of custom metadata types must be unique within their namespace. All custom metadata types belong to the CustomMetadata namespace and can optionally belong to a second namespace. In your organization, you can use custom metadata types with your namespace and also other organizations’ namespaces.

Version

Custom metadata type components are available in API version 31.0 and later.

Special Access Rules

To create custom metadata types, you must have the “Author Apex” permission. Apex code can create, read, and update (but not delete) custom metadata records, as long as the metadata is subscriber-controlled and visible from within the code's namespace. You can edit records in memory but not upsert or delete them. Apex code can deploy custom metadata records, but not via a DML operation. Moreover, DML operations aren’t allowed on custom metadata in the Partner or Enterprise APIs. Customers who install a managed custom metadata type can’t add new custom fields to it. With unpackaged metadata, both developer-controlled and subscriber-controlled access behave the same: like subscriber-controlled access. Refer to Trust, but Verify: Apex Metadata API and Security to learn more.

Audit fields (CreatedDate, CreatedBy, LastModifiedDate, LastModifiedBy, SystemModStamp) remain uneditable.

Note

Fields

Custom metadata types can contain the following CustomObject fields.

To make the fields on your custom metadata types unique and indexable, mark your fields as Unique and ExternalId.

Field Name	Field Type	Description
description	string	A description of the custom metadata type. This field can contain a maximum of 1,000 characters.
fields	CustomField[]	Represents one or more custom fields in the custom metadata type.
gender	Gender	Indicates the gender of the noun that represents the object. This field is used for languages where words need different treatment depending on their gender.
label	string	A label that represents the object throughout the Salesforce Setup user interface. Custom metadata types are visible only through the recently used objects list on the Lightning Platform Home Page and in the packaging user interface.
pluralLabel	string	The plural version of the label value.
startsWith	StartsWith (enumeration of type string)	Indicates whether the noun starts with a vowel, a consonant, or a special character. This field is used for languages where words need different treatment depending on their first character.
visibility	SetupObjectVisibility (enumeration of type string)	This field returns the visibility of a custom metadata type. The following values are valid: `Public`—If the custom setting or custom metadata type is packaged, it’s accessible to all subscribing organizations. `Protected`—If the custom object, custom setting, or custom metadata type is in a managed package, it’s accessible only to the developer org. Subscribing orgs can’t access it. `PackageProtected`—If the custom metadata type is `PackageProtected`, it’s only accessible by the custom Apex code in the package. Use this value to secure secrets such as API access keys and security tokens. Available in API version 47.0 and later. The default value is `Public`.

Declarative Metadata Sample Definition

In this example, Picklists R Us creates its Reusable Picklist custom metadata type by deploying a file in the objects folder, named ReusablePicklistOption__mdt.object, with these contents.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
3   <fields>
4      <fullName>AlphaSort__c</fullName>
5      <defaultValue>false</defaultValue>
6      <externalId>false</externalId>
7      <label>Sorted Alphabetically</label>
8      <type>Checkbox</type>
9   </fields>
10   <label>Reusable Picklist</label>
11   <pluralLabel>Reusable Picklist</pluralLabel>
12   <visibility>Public</visibility>
13</CustomObject>

This excerpt from a package.xml file shows the use of dot notation and the __mdt suffix. If you’re using a namespace, for example picklist1234, the full name of ReusablePicklistOption__mdt would be picklist1234__ReusablePicklistOption__mdt.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3...
4   <types>
5      <members>PicklistTest__c.PicklistTestField__c</members>
6      <members>ReusablePicklistOption__mdt.Picklist__c</members>
7      <members>ReusablePicklistOption__mdt.SortOrder__c</members>
8      <members>PicklistUsage__mdt.Field__c</members>
9      <members>PicklistUsage__mdt.Picklist__c</members>
10      <members>PicklistUsage__mdt.SObjectType__c</members>
11      <members>ReusablePicklist__mdt.AlphaSort__c</members>
12      <name>CustomField</name>
13   </types>
14...
15   <types>
16      <members>PicklistTest__c</members>
17      <members>ReusablePicklistOption__mdt</members>
18      <members>PicklistUsage__mdt</members>
19      <members>ReusablePicklist__mdt</members>
20      <name>CustomObject</name>
21   </types>
22...
23   <version>63.0</version>
24</Package>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.