Error with Custom Metadata deployment via metadata API

Question

In testing dev org (org A) CustomMetadata was made and added to the package. This package was retrieved via metadata API (VS Code + ForceCode plugin).

Now I am trying to deploy (migrate) all changes made in org A to another dev org B for future development. Custom Metadata has Metadata Relationship(Field Definition) and metadata API gives an Error Metadata relationships to Field Definition require a controlling field when I'm trying to deploy it to org B

Here is how this FieldDefinition looks as metadata:

<fields>
    <fullName>Field__c</fullName>
    <externalId>false</externalId>
    <fieldManageability>DeveloperControlled</fieldManageability>
    <label>Field</label>
    <referenceTo>FieldDefinition</referenceTo>
    <relationshipLabel>Some_Settings</relationshipLabel>
    <relationshipName>Some_Settings</relationshipName>
    <required>false</required>
    <type>MetadataRelationship</type>
    <unique>false</unique>
</fields>

Same metadata object has EntityDefinition relationship and there is no problem with that one. There is a couple Custom of Metadata objects with FieldDefinition and all of them are throwing the same Error when deployed via metadata API to org B.

Some workaround. 1. I removed FieldDefinition field from metadata .xml

2. Replicate it in org B manually

3. No more Errors

Question:

a. Is this a known issue or I made some mistake?

b. How about packaging metadata and it's records? So far it is not part of the managed package, that's why development done in isolated org. Can it brake managed package the same way as basic metadata transfer?

Answer 1

Looks like this is missing a metadataRelationshipControllingField element.

Any metadata relationship field to FieldDefinition needs that element; it specifies the relationship field to EntityDefinition that acts as its "controller".

For example, if you have a relationship field that points to EntityDefinition and has the name Entity__c, you would want to add the following to the definition of Field__c above:

<metadataRelationshipControllingField>Entity__c</metadataRelationshipControllingField>

This way, when an object is selected as a value of the Entity__c field, the Field__c field will be limited to fields on that object.

If you didn't see this when you retrieved the field using the metadata API, my guess is that you're using an old API version from before relationships to FieldDefinition existed; in those old versions you couldn't see this element.

This isn't a concern with actual packages because a package version is always uploaded using the latest version of the metadata API; any package that was uploaded with a relationship to FieldDefinition was uploaded in an API version that had this element.