Platform Custom Metadata Type Generate

Salesforce Custom Metadata Type Generator and Validator

When to Use This Skill

Use this skill when you need to:

• Create a Custom Metadata Type (__mdt)
• Generate or validate CMDT fields, including MetadataRelationship fields
• Generate CMDT records as deployable .md-meta.xml files
• Troubleshoot CMDT deployment errors

1. Overview and Purpose

A Custom Metadata Type produces two separate artifact families, and most requests need both:

API name suffix: __mdt on the type; fields still end in __c.

The defining advantage over a custom setting: CMDT records are metadata and therefore deploy between orgs. When a user says configuration should "ship with the package" or "be the same in every org," CMDT is the right answer.

The root element is <CustomObject>, but almost none of a custom object's rules apply. sharingModel, nameField, and deploymentStatus are required or normal on a regular custom object and are hard errors here. Do not carry assumptions across from platform-custom-object-generate.

2. Syntactic Essentials — Type Definition (Tier 1)

Required and Allowed Elements

<pluralLabel> being required here but forbidden on a custom setting is the most commonly inverted rule between the two families. Neither failure mentions the other family's rule.

Forbidden Elements

Every element below produces Cannot specify: <element> for Custom Metadata Type — reusing a regular custom object's skeleton (with sharingModel, deploymentStatus, a nameField block, or enableSearch) is the usual cause:

sharingModel, nameField, deploymentStatus, enableActivities, enableReports, enableHistory, enableSearch

CORRECT — minimum valid __mdt type:

<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Partner Tier</label>
  <pluralLabel>Partner Tiers</pluralLabel>
  <description>Discount and threshold configuration per partner tier. Ships with the package; edited by the revenue ops team.</description>
  <visibility>Public</visibility>
</CustomObject>

3. Field Rules

This skill owns the CMDT-specific deltas only — the type allowlist, fieldManageability, and MetadataRelationship below. For generic field mechanics (<fullName> derivation, <label>, <description>, <inlineHelpText>, precision/scale, <length>, visibleLines), follow platform-custom-field-generate.

Supported Field Types

Checkbox, Date, DateTime, Email, Number, Percent, Phone, Picklist, Text, TextArea, LongTextArea, Url, plus MetadataRelationship.

Unsupported Field Types

Currency, AutoNumber, MasterDetail, Summary, Location, Time, EncryptedText, Html, MultiselectPicklist. Each fails with a precise, well-formed error:

Type {TypeName} of CustomMetadataField {Object}__mdt.{Field}__c is not supported for the Entity {Object}__mdt

(There is no trailing period.) Example: Type Currency of CustomMetadataField Partner_Tier__mdt.Discount__c is not supported for the Entity Partner_Tier__mdt

Currency is the common trap — it works on a custom setting but not here. Use Number with <precision>/<scale> and put the currency in the label or help text.

Formula fields are unsupported, but they break the pattern above. A <formula> element on an otherwise legal type gives only:

Invalid data type.

Lookup is silently coerced — CRITICAL

<type>Lookup</type> on a __mdt does not fail when its referenceTo resolves to a real sObject: the deploy is green and the platform silently rewrites the field to MetadataRelationship. A later retrieve shows a field the user never wrote:

<type>MetadataRelationship</type>   <!-- was deployed as Lookup -->

Always write MetadataRelationship explicitly. Emitting Lookup produces a green deploy and a source-vs-org mismatch that churns in git the first time anyone retrieves. (Reproduced on a live deploy: a resolvable Lookup returns as MetadataRelationship; a non-resolvable referenceTo is cleanly rejected.)

MetadataRelationship

Three targets, all valid. referenceTo selects which.

<?xml version="1.0" encoding="UTF-8"?>
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Target_Field__c</fullName>
  <label>Target Field</label>
  <type>MetadataRelationship</type>
  <referenceTo>FieldDefinition</referenceTo>
  <metadataRelationshipControllingField>Partner_Tier__mdt.Target_Object__c</metadataRelationshipControllingField>
  <relationshipLabel>Target Field</relationshipLabel>
  <relationshipName>Target_Field</relationshipName>
</CustomField>

The controlling field must be an EntityDefinition relationship on the same type, referenced as Type__mdt.Field__c. Omitting it gives Metadata relationships to Field Definition require a controlling field.

Self-references are impossible. Pointing a MetadataRelationship at its own parent type fails with Cannot add a self-lookup relationship child with cascade or restrict options to the object itself (verbatim from a live __mdt deploy) — use a second type.

<fieldManageability>

Optional. It defaults to DeveloperControlled — do not add it unless the user wants a different value. Valid values are DeveloperControlled, SubscriberControlled, and Locked.

It is valid only on __mdt fields. On a regular custom object field or a custom setting field:

Field manageability cannot be set on this entity.

4. CMDT Records (.md-meta.xml)

Filename convention

Write customMetadata/<TypeNameWithout__mdt>.<RecordDeveloperName>.md-meta.xml.

customMetadata/Partner_Tier.Bronze_AMER.md-meta.xml

The __mdt suffix in the filename also deploys and creates a real record, so it is tolerated — but Salesforce's retrieve normalizes to the no-suffix form, so always write it without __mdt to avoid git churn (detail in references/cmdt-records.md).

Required namespaces

All three are mandatory on the root element — xsi:type on values will not resolve without them.

<CustomMetadata xmlns="http://soap.sforce.com/2006/04/metadata"
                xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

xsi:type mapping — every value needs one

A value pointing at another __mdt type via MetadataRelationship was not verified — expect xsd:string with the target's DeveloperName, but confirm.

xsd:picklist must not be emitted — CRITICAL

Salesforce's own documentation tells you to use xsd:picklist for Picklist fields. It is wrong — it is not a valid XML Schema type. Instead of a clean validation error, the platform fails the entire deploy server-side with no component-level diagnostics, taking every other component down with it. Always emit xsd:string for a Picklist field's value; never xsd:picklist. See references/cmdt-records.md §2.

Record body rules

• <label> is required. Omitting it gives Required fields are missing: [MasterLabel] — note it reports the sObject field name MasterLabel, not label.
• <protected> is optional and defaults to false.
• Never put <fullName> inside a <values> block — it is a hard parse error.
• <value xsi:nil="true"/> works on optional fields. On a required field it is rejected exactly as if the field were absent. Omitting xsi:type on a non-nil value is always fatal, including for text fields.

CORRECT — a complete record:

<?xml version="1.0" encoding="UTF-8"?>
<CustomMetadata xmlns="http://soap.sforce.com/2006/04/metadata"
                xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <label>Bronze AMER</label>
  <protected>false</protected>
  <values>
    <field>Discount_Percent__c</field>
    <value xsi:type="xsd:double">5.0</value>
  </values>
  <values>
    <field>Region__c</field>
    <value xsi:type="xsd:string">AMER</value>
  </values>
  <values>
    <field>Effective_Date__c</field>
    <value xsi:type="xsd:date">2024-01-15</value>
  </values>
  <values>
    <field>Notes__c</field>
    <value xsi:nil="true"/>
  </values>
</CustomMetadata>

Record DeveloperName rules

The name is the second segment of the filename. It must begin with a letter, contain only alphanumerics and underscores, not end with an underscore, not contain two consecutive underscores, and be at most 40 characters. Violations give:

Custom Metadata Record Name: The <Type>__mdt API Name can only contain underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.

Over 40 characters gives Value too long for field: fullName maximum length is:40 (no space after the colon).

Deploy ordering

No ordering constraint — the type and every referenced field only need to resolve (already in the org, or present in the same deploy). Two failures tell you what is missing: Custom metadata type <Type>__mdt is not available in this organization. (the type is missing) and <Type>__mdt: could not find fields: <Field>__c (the type exists but the field does not).

→ Full record-value error catalog and the xsi:type coercion asymmetry: references/cmdt-records.md.

Generating records from user input

Record data arrives three ways; in each case emit one <Type>.<Record>.md-meta.xml per row, mapping columns to <field>/<value> pairs with the right xsi:type:

• Inline list/table — map columns straight to fields.
• CSV — header = field API names (or map labels to them), each line = one record; take the DeveloperName from a key column.
• Prose — infer the rows ("Bronze at 5%, Gold at 15%") and confirm the field mapping before generating.

Derive every DeveloperName deterministically from the key column or label — never free-hand one. For each row, run scripts/sanitize-developer-name.sh "<LABEL>" <ROW> before writing its record file (same input → same valid name; empty/all-symbol/non-Latin labels fall back to Record_<ROW>).

The transform is many-to-one — United States and United-States both yield United_States, and since each record is <Type>.<DeveloperName>.md-meta.xml, a collision silently overwrites a row. After deriving the whole batch, check duplicates before writing; on any collision stop and report the colliding source labels rather than overwrite (append a deterministic _2/_3 suffix only if the user asks to auto-resolve). Ordered algorithm, ASCII-only limitation, uniqueness check, and worked examples: references/cmdt-records.md §7.

Consuming records in Apex

Records are read through the generated typed class — no SOQL, no query rows consumed, safe in loops and triggers:

Map<String, Partner_Tier__mdt> all = Partner_Tier__mdt.getAll();
Partner_Tier__mdt bronze = Partner_Tier__mdt.getInstance('Bronze_AMER');  // by DeveloperName

Accessor truncation — CRITICAL for LongTextArea. getAll()/getInstance() return only the first 255 characters of any field; longer LongTextArea values are silently truncated for those callers and must be read via SOQL (SELECT ... FROM Partner_Tier__mdt). Say so whenever you put a LongTextArea on a CMDT.

5. Choosing the Right Component

Before generating, confirm a CMDT is what the user needs.

The distinction that matters most: CMDT records deploy, custom setting values do not. If the user needs admins to edit values per profile at runtime, that is a custom setting, not a CMDT.

Field-mapping and lookup tables are a canonical CMDT use case. When a user asks to "map fields from A to B," maintain a code-to-code lookup, or keep a crosswalk admins can edit, model it as a CMDT — one record per pair (e.g. Lead_Field__c/Target_Field__c, or MetadataRelationship fields to FieldDefinition) — never a hardcoded Apex Map, constant, or Flow decision. Phrasing like "for conversion" or "for our integration" does not make it code: if admins maintain the pairs without a deploy, it is CMDT reference data.