PicklistSettings Metadata Type in SFDX

Architectural Overview#

The PicklistSettings metadata type manages platform governance settings for custom picklists and global value sets across Salesforce. In mature enterprise orgs that have operated for years, picklist fields on Account, Contact, Opportunity, and custom objects often accumulate thousands of deprecated, inactive values.

Salesforce enforces a strict platform ceiling: a single picklist field cannot contain more than 4,000 total values (active plus inactive). When unrestricted integrations insert arbitrary picklist entries into unrestricted fields, the limit is quickly reached, causing unexpected runtime save failures. PicklistSettings provides automated lifecycle management—enabling automatic pruning of unreferenced inactive picklist values and standardizing value set resolution.

Directory and File Conventions#

In SFDX source format, PicklistSettings is stored in the settings/ directory and referenced as Settings:Picklist.

Key Metadata Fields#

The XML schema of PicklistSettings exposes parameters controlling picklist retention and namespaces:

Declarative XML and Package Manifest Examples#

Below is a declarative configuration for automated picklist governance:

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

Scratch Org Definition Configuration#

When standardizing scratch org definitions for continuous integration:

{
  "orgName": "Enterprise Data Governance Org",
  "edition": "Enterprise",
  "settings": {
    "picklistSettings": {
      "enableAutoCleanUpInactivePicklists": true,
      "enablePicklistsDoNotRequireNamespace": true
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage PicklistSettings using the Salesforce CLI:

# Retrieve PicklistSettings from the active target org
sf project retrieve start --metadata Settings:Picklist

# Deploy PicklistSettings to target environment
sf project deploy start --metadata Settings:Picklist

# Validate picklist settings deployment
sf project deploy validate --metadata Settings:Picklist

Architect Best Practices and Gotchas#

• Restricted vs. Unrestricted Fields: For new custom fields, always set <restricted>true</restricted> in CustomField definitions. This prevents automated API integrations from creating rogue inactive values in the first place.
• Reporting Historical Data Drift: Before enabling enableAutoCleanUpInactivePicklists, verify whether historical analytics or Data Cloud queries rely on inactive picklist values. If historical records hold inactive values, those values are preserved; only values with zero record references are purged.
• Global Value Set Modularization: Migrate custom picklists containing shared business domains (e.g., Country codes, Industry classifications) to Global Value Sets to enforce consistency across multiple objects.

Frequently asked questions

What does PicklistSettings manage in Salesforce?

It governs org-wide picklist configuration switches, such as automatic inactive picklist value deletion and namespace enforcement on value sets.

Where is PicklistSettings stored in an SFDX directory?

It is stored under force-app/main/default/settings/ as Picklist.settings-meta.xml and retrieved using the Settings:Picklist metadata identifier.

How does enableAutoCleanUpInactivePicklists help architects?

It automatically purges unused inactive picklist values, preventing custom fields from hitting the platform limit of 4,000 total values.

Can PicklistSettings be declared in scratch org definition files?

Yes. Adding picklistSettings to project-scratch-def.json ensures test and CI orgs enforce the same picklist lifecycle rules as production.