Why does VS Code's Org Browser retrieves metadata with different file extensions than Metadata API and what are possible consequences of that?

Question

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">
    <types>
        <members>MyCustomMetadata.MyCustomMetadataRecord</members>
        <name>CustomMetadata</name>
    </types>
    <version>45.0</version>
</Package>

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?

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)