Let's say I have a Custom Metadata created on my Org: MyCustomMetadata.

Downloading its record within Org Browser:

  • Command used: sfdx force:source:retrieve -m CustomMetadata:MyCustomMetadata.MyCustomMetadataRecord
  • File retrieved: MyCustomMetadata.MyCustomMetadataRecord.md-meta.xml

Via mdapi:

  • Command used: sfdx force:mdapi:retrieve -u MyOrgAlias -r "./" -k package.xml
  • File retrieved: MyCustomMetadata.MyCustomMetadataRecord.md

package.xml contents:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">

There's a difference in file extension, a -meta.xml suffix is added when using Org Browser / force:source:retrieve.

What's the reason for that and are there any consequences of using these two commands interchangeably?

1 Answer 1


With the introduction of SFDX, we also got a new representation for the metadata/code known as "Source form".

This is different from the traditional representation, which is called "Metadata API form"

Source form is meant to be more flexible for project structure in versioning systems (git, subversion, etc...) and is also important for driving the pushing and pulling of code to/from scratch orgs.

Metadata API form is what's primarily used for working with the metadata api (things like sfdx force:mdapi:deploy)

There's also a difference in how the metadata/code is structured. As a quick example, take custom SObject fields...

  • Metadata API form keeps field metadata inside of the object's metadata definition
  • Source form breaks field metadata out into separate metadata files stored in a subdirectory of the object (which itself is a metadata file in a subdirectory of the "objects" folder, by default)

If nothing else, the file extensions are different so that there's some way to easily, programmatically distinguish between the two formats.

Mixing source and metadata api forms is not a good idea. Try to stick to running one set of commands if you can. If you can't, then that's why we have the ability to convert between them (sfdx force:mdapi:convert and sfdx force:source:convert)

  • I would add that the extensions now correctly identify the type of content (the "file type") whereas they did not in Metadata API. For example, here you see that the custom metadata type instance is an XML file. Another example, previously a JavaScript static resource had (in the Metadata API) the extension .resource, but now (in Source format) has the extension .js.
    – Phil W
    Mar 18, 2020 at 16:53

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .