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.
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	Required. The value for a field on the CustomMetadata object. This value can be null. For more information, see Usage.

Declarative Metadata Sample Definition

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>

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.