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 as well as 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. Only managed package developers can add new fields to the custom metadata types in their managed packages. Customers who install a managed custom metadata type can’t add new custom fields to it.

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.
Protected	boolean	When a custom metadata type is released in a managed package, access is limited in specific ways. Code that’s in the same managed package as custom metadata records can read the records. Code that’s in the same managed package as custom metadata types can read the records that belong to that type. Code that’s in a managed package that doesn’t contain either the type or the protected record can’t read the protected records. Code that the subscriber creates and code that’s in an unmanaged package can’t read the protected records. The developer can modify protected records only with a package upgrade. The subscriber can’t read or modify protected records. The developer name of a protected record can’t be changed after release. The subscriber can’t create records of a protected type. Records that are hidden by these access rules are also unavailable to REST, SOAP, SOQL, and Setup.
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 Force.com 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)	When this field is present, this component is not a custom object, but a custom setting or custom metadata type. This field returns the visibility of the custom setting or 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 setting or custom metadata type is in a managed package, it’s only accessible to the developer organization; subscribing organizations can’t access it. 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>40.0</version>
24</Package>