Skip to content

package.xml explained: structure, wildcards and common mistakes

How a Salesforce package.xml manifest is structured, which metadata types accept a wildcard, and the mistakes that cause retrieves to come back empty.

6 minute readUpdated By Kappa Vinay

A package.xml file, often called a manifest, is a list. It tells the Metadata API which components to retrieve from an org or which components a deployment contains. It does not hold any metadata itself.

The structure

XML
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>AccountService</members>
        <members>AccountServiceTest</members>
        <name>ApexClass</name>
    </types>
    <types>
        <members>*</members>
        <name>LightningComponentBundle</name>
    </types>
    <version>62.0</version>
</Package>
  • Each <types> block names one metadata type in <name> and lists components in <members>.
  • <version> is the Metadata API version used for the operation. It should not be higher than the version your org is on.
  • The namespace on <Package> is required exactly as shown.

Wildcards

An asterisk in <members> means “every component of this type”. It works for many types, including ApexClass, ApexTrigger, Flow, LightningComponentBundle and PermissionSet, but not for all of them.

  • Child types such as CustomField, ValidationRule, RecordType and ListView need each member named as Object.Component.
  • Folder-based types such as Report, Dashboard, Document and EmailTemplate need Folder/Component names.
  • For CustomObject, the wildcard returns custom objects only. Standard objects such as Account must be named explicitly.
  • StandardValueSet members, such as Industry, must always be named.

Mistakes that waste an afternoon

  • Using the label instead of the API name. Invoice will not match Invoice__c.
  • Forgetting the object for child types. Region__c is not a valid CustomField member; Account.Region__c is.
  • Layout names. They combine the object and the layout label: Account-Account Layout.
  • Retrieving a profile on its own. A profile in a retrieve only contains permissions for the other components in the same manifest, so the result looks almost empty.
  • Setting a version higher than the target org supports, which fails immediately.

Using the manifest with the Salesforce CLI

Example
# Retrieve what the manifest lists
sf project retrieve start --manifest package.xml

# Deploy what the manifest lists
sf project deploy start --manifest package.xml

To delete components as part of a deployment, list them in a second file named destructiveChanges.xml with the same structure, alongside a package.xml.

Salesforce adds and changes metadata types in every release. The Metadata Coverage Report on the Salesforce developer site is the authoritative list.