Document Metadata Type and SFDX Reference

Overview#

The Document metadata type represents a binary or text file stored in the legacy Salesforce Classic Documents tab. Although Salesforce Files (ContentVersion / ContentDocument) and ContentAsset have superseded Document in Lightning Experience, Document remains architecturally relevant in enterprise orgs for three reasons:

1. Classic Letterhead and HTML EmailTemplate headers and footers reference Document records by folder and developer name.
2. Unauthenticated external image links using /servlet/servlet.ImageServer?id=<DocId>&oid=<OrgId> rely on Document with <public>true</public>.
3. Legacy managed packages and custom Visualforce PDF generators frequently query the Document object via SOQL to load dynamic branding logos or XML configuration files.

Directory and File Suffix Reference#

Document is a folder-based metadata type (inFolder: true). Every document must reside inside a named DocumentFolder subdirectory under force-app/main/default/documents/.

Key Metadata Fields#

Querying Document Records via SOQL#

Unlike purely declarative XML settings, Document maps directly to the standard Document SObject and can be queried via SOQL in Apex or the Salesforce CLI:

SELECT Id, DeveloperName, Name, Folder.DeveloperName, ContentType,
       BodyLength, IsPublic, IsInternalUseOnly, Url, LastModifiedDate
FROM Document
WHERE Folder.DeveloperName = 'Corporate_Branding'
ORDER BY DeveloperName ASC

Declarative XML and Package.xml Examples#

1. Parent Folder Metadata (Corporate_Branding.documentFolder-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<DocumentFolder xmlns="http://soap.sforce.com/2006/04/metadata">
    <accessType>Public</accessType>
    <name>Corporate Branding Assets</name>
    <publicFolderAccess>ReadOnly</publicFolderAccess>
</DocumentFolder>

2. Document Metadata (Invoice_Header_Logo.png-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Official 600x120 PNG header logo used in Classic billing email templates.</description>
    <internalUseOnly>false</internalUseOnly>
    <keywords>logo, header, billing, letterhead</keywords>
    <name>Invoice Header Logo</name>
    <public>true</public>
</Document>

3. Package Manifest (package.xml)#

Because Document does not support the * wildcard, you must include both the DocumentFolder name and the slash-delimited FolderName/DocumentName member in <types>:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Corporate_Branding</members>
        <members>Corporate_Branding/Invoice_Header_Logo.png</members>
        <name>Document</name>
    </types>
    <version>68.0</version>
</Package>

# List all documents in a specific folder using the Salesforce CLI
sf org list metadata --metadata-type Document --folder Corporate_Branding

# Retrieve the folder and the document together
sf project retrieve start --metadata "Document:Corporate_Branding,Document:Corporate_Branding/Invoice_Header_Logo.png"

Architect Best Practices and Gotchas#

• File Extension Preservation in SFDX: In modern SFDX source format, if a Document has its file extension included in its DeveloperName or filename (Invoice_Header_Logo.png), both the binary file and the -meta.xml file include .png. Ensure your package.xml member matches the exact DeveloperName stored in Salesforce.
• Migrate App Logos to ContentAsset: Lightning Apps (CustomApplication) require ContentAsset rather than Document for app branding logos. When modernizing a Classic app to Lightning, convert its Document logo into a ContentAsset.
• Hardcoded ImageServer URLs Across Sandboxes: External HTML templates that hardcode /servlet/servlet.ImageServer?id=015...&oid=00D... break after sandbox refreshes or deployments to new orgs because both 015 (Document ID) and 00D (Organization ID) change when created via Metadata API deployment. Use dynamic merge fields or convert to ContentAsset / CDN delivery.

Frequently asked questions

Why does wildcard retrieval fail for the Document metadata type in package.xml?

Document is a folder-based metadata type. Metadata API does not support the asterisk wildcard for folder-based types; you must list the parent DocumentFolder name and every folder-qualified Document member path explicitly in package.xml.

When should architects use Document instead of ContentAsset or StaticResource?

Use ContentAsset for Lightning Experience app logos and Lightning email templates, and StaticResource for LWC or Visualforce assets. Use Document only when maintaining Classic EmailTemplate letterheads or legacy integrations requiring /servlet/servlet.ImageServer URLs.

How do I make a Document publicly accessible without authentication?

Set the public boolean field to true in the .document-meta.xml file. When public is true, Salesforce allows external email clients and guest users to render the image via the /servlet/servlet.ImageServer endpoint using the org ID and document ID.

What is the maximum file size for a Document deployed via Metadata API?

A single Document record supports up to 5 MB for standard file uploads and up to 20 KB when configured as a custom application logo, subject to the overall 39 MB compressed Metadata API zip payload limit.