CustomMetadata | Metadata API Developer Guide

This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location

CustomMetadata components have the suffix .md and are stored in the customMetadata folder. Unlike custom metadata types, custom metadata records don’t have a double-underscore suffix. Custom metadata record names are prepended with their custom metadata type name, excluding the __mdt suffix but including the namespace of any types in an installed managed package.

Version

CustomMetadata components are available in API version 31.0 and later.

Special Access Rules

To create custom metadata records, you must have the “Customize Application” permission.

Fields

Field Name	Field Type	Description
description	string	A description of the custom metadata record. This field can contain a maximum of 1,000 characters.
label	string	A label that represents the object throughout the Salesforce Setup user interface. Custom metadata records are currently visible only through the packaging user interface.
protected	boolean	Boolean. Indicates whether the record is protected (true) or not (false). 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 with a package upgrade or by using the Metadata Apex classes (if the Apex code is in the same namespace as either the records or their type). 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.
values	CustomMetadataValue[]	Represents one or more values for custom fields on the custom metadata record.

CustomMetadataValue

Represents a value for a custom field on the custom metadata record.

Field Name	Field Type	Description
field	string	Required. The non-object-qualified name of a custom field in the custom metadata type. This value corresponds to the name of a field on the custom metadata record’s custom metadata type. Include the namespace (if the type is from a managed package) and the __c suffix. The name of the custom metadata type isn’t required. For example, `picklist1234__AlphaSort__c`.
value	Any type	The value on a custom metadata record. Where fields are EntityDefinition and FieldDefinition, the qualified API names of the entity and the field it points to. This value can be null.

Declarative Metadata Sample Definitions

The following is an example of a CustomMetadata component. In this example, the sample app TravelApp deploys a Planets picklist, specifies its sort order, and adds picklist items to it.

Assuming Picklists R Us’s namespace is picklist1234, to define the Planets picklist, TravelApp deploys a file in the customMetadata folder, named picklist1234__ReusablePicklist.Planets.md, with these contents. The xsi:type attribute specifies the type for the value of the AlphaSort__c checkbox field.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomMetadata xmlns="http://soap.sforce.com/2006/04/metadata" 
3                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
4                   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
5    <description>All the planets in the solar system. Does not 
6                 include asteroids.</description>
7    <label>Planets</label>
8    <values>
9        <field>picklist1234__AlphaSort__c</field>
10        <value xsi:type="xsd:boolean">false</value>
11    </values>
12</CustomMetadata>

Picklists R Us creates its Reusable Picklist Option custom metadata type by deploying a file in the objects folder, named ReusablePicklist__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>Picklist__c</fullName>
5        <externalId>false</externalId>
6        <label>Picklist</label>
7        <length>40</length>
8        <required>true</required>
9        <type>Text</type>
10        <unique>false</unique>
11    </fields>
12    <fields>
13        <fullName>SortOrder__c</fullName>
14        <externalId>false</externalId>
15        <label>Non-Alphabetical Sort Order</label>
16        <precision>3</precision>
17        <scale>0</scale>
18        <required>false</required>
19        <type>Number</type>
20        <unique>false</unique>
21    </fields>
22    <label>Reusable Picklist Option</label>
23    <pluralLabel>Reusable Picklist Options</pluralLabel>
24</CustomObject>

To define the Mars picklist item, TravelApp deploys a file, named picklist1234__ReusablePicklistOption.Mars.md, with these contents. This component file specifies types that apply to the ReusablePicklistOption__mdt custom fields.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomMetadata xmlns="http://soap.sforce.com/2006/04/metadata" 
3  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
4  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
5    <label>Mars</label>
6    <values>
7        <field>picklist1234__Picklist__c</field>
8        <value xsi:type="xsd:string">Planets</value>
9    </values>
10    <values>
11        <field>picklist1234__SortOrder__c</field>
12        <value xsi:type="xsd:int">4</value>
13    </values>
14</CustomMetadata>

To define the Motel6 picklist item, TravelApp deploys a file, named picklist1234__ReusablePicklistOption.Motel6.md, with these contents.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomMetadata xmlns="http://soap.sforce.com/2006/04/metadata" 
3  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
4  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
5    <label>Motel 6</label>
6    <values>
7        <field>picklist1234__Picklist__c</field>
8        <value xsi:type="xsd:string">Hotels</value>
9    </values>
10</CustomMetadata>

Because the SortOrder__c field isn’t required, this file doesn’t require a value for SortOrder__c. Alternatively, the file could have explicitly specified a value with xsi:nil to ensure that SortOrder__c was cleared of any previous value.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomMetadata xmlns="http://soap.sforce.com/2006/04/metadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
3    <label>Motel 6</label>
4    <values>
5        <field>picklist1234__Picklist__c</field>
6        <value xsi:type="xsd:string">Hotels</value>
7    </values>
8    <values>
9        <field>picklist1234__SortOrder__c</field>
10        <value xsi:nil="true" />
11    </values>
12</CustomMetadata>

This excerpt from a package.xml file illustrates the inclusion of custom metadata types and their namespaces in custom metadata records’ names. Assume that Picklists R Us’s namespace is picklist1234.

1<?xml version="1.0" encoding="UTF-8"?>
2<package xmlns="http://soap.sforce.com/2006/04/metadata">
3…
4   <types>
5      <members>picklist1234__ReusablePicklist.Hotels</members>
6      <members>picklist1234__ReusablePicklist.Planets</members>
7      <members>picklist1234__ReusablePicklistOption.Bellagio</members>
8      <members>picklist1234__ReusablePicklistOption.Motel6</members>
9      <members>picklist1234__ReusablePicklistOption.Mercury</members>
10      <members>picklist1234__ReusablePicklistOption.Venus</members>
11      <members>picklist1234__ReusablePicklistOption.Earth</members>
12      <members>picklist1234__PicklistUsage.BookedHotel</members>
13      <members>
14         picklist1234__PicklistUsage.DestinationPlanetPL
15      </members>
16      <members>picklist1234__PicklistUsage.PlanetVisitedPl</members>
17      <name>CustomMetadata</name>
18   </types>
19… 
20</package>

TravelApp, Inc.’s package.xml file uses a wildcard to install custom metadata, as is shown in this excerpt from their package.xml file. Unless you want to deploy or retrieve specific records, using a wildcard is easier than listing all of your custom metadata records in your package.xml file.

1<types>
2   <members>*</members>
3   <name>CustomMetadata</name>
4</types>

If the custom metadata is from a managed package, the name after the dot in the package.xml file—between the two dots in the file name—is qualified by the managed package’s namespace. For example, assuming TravelApp uses the namespace travelApp1234, the first member element in the TravelApp package.xml file appears to Galactic Tours as:

1<members>picklist1234__ReusablePicklist.travelApp1234__Hotels</members>

Here’s another example. In this case, we have an instance of custom metadata record, whose EntityDefinition field points to a custom object named SalesAgreement__c. The FieldDefinition field points to the custom field CustomerReference__c on SalesAgreement__c. You can deploy new custom metadata records and retrieve existing ones with EntityDefinition and FieldDefinition fields using qualified API names of custom and standard entities and their fields.

1<?xml version="1.0" encoding="UTF-8"?><values>
2<field>EntityDefintionField__c</field>
3<value xsi:type="xsd:string">v1__SalesAgreement__c</value>
4</values>
5<values>
6<field>FieldDefinitionField__c</field>
7<value xsi:type="xsd:string">v1__CustomerReference__c</value>
8</values>

Usage

When specifying the value field in the CustomMetadataValue subtype, specify an appropriately typed object that’s based on your field type definition. In declarative metadata definitions for CustomMetadataValue, use the xsi:type attribute of the value element. For example, to specify a boolean value: <value xsi:type="xsd:boolean">true</value>. Valid xsi:type attributes are:

Custom metadata value	Custom field definition
`xsi:type="xsd:boolean"`	Checkbox
`xsi:type="xsd:date"`	Date
`xsi:type="xsd:dateTime"`	Date/Time
`xsi:type="xsd:picklist"`	Picklist
`xsi:type="xsd:string"`	Text
`xsi:type="xsd:string"`	Phone
`xsi:type="xsd:string"`	TextArea
`xsi:type="xsd:string"`	URL
`xsi:type="xsd:string"`	Email
`xsi:type="xsd:int"`	Number/Percent, with scale equal to 0
`xsi:type="xsd:double"`	Number/Percent, with scale not equal to 0

You can also omit the xsi:type attribute. For example, <value>true</value>.

Although this attribute must be specified for any CustomMetadataValue, you can use an element with the xsi:nil attribute set to true to explicitly set the field’s value to null. For example, <value xsi:nil="true"/>.

Using null field values differs from leaving out the CustomMetadataValue for a particular field entirely. If you leave out the CustomMetadataValue, the value of the field doesn’t change. The field’s value is null for newly deployed custom metadata records and left at its previous value for updated custom metadata records.

When you retrieve CustomMetadataValue objects, the value field of the returned object holds a value of the correct type, specified by xsi:type in the case of declarative metadata definitions.

Custom number fields are stored as double values. When you retrieve a value from a Number type field with a scale 0, you will see a decimal number. For example, if the value in UI is 1234567, a query through the API returns 1234567.0.

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.