ChoiceList Metadata Type for Dynamic Forms

Architectural Overview#

Across Salesforce Industry Clouds (such as Health Cloud, Financial Services Cloud, and Public Sector Solutions) and dynamic questionnaire engines, intake forms and assessments require hundreds of standardized single-select or multi-select answer sets (for example, Yes / No / Unable to Assess or Low / Moderate / High / Critical). Creating database-level CustomField picklists for every questionnaire prompt quickly exhausts object field governor limits.

The ChoiceList metadata type decouples form answer options from physical database columns. It defines a reusable collection of choice values (choiceListValue) that dynamic assessments, Discovery Framework questions, and guided Flow screens can reference declaratively.

Directory Location and File Suffix#

In Salesforce DX source format, ChoiceList components are stored in the choiceLists directory.

Key Metadata Fields#

The following table describes the fields available on ChoiceList and its nested ChoiceListValue items in API version 68.0 (Winter ’27):

Declarative Metadata Example#

The following ChoiceList defines a standardized Clinical Risk Severity scale (Low, Moderate, High, Critical) for patient intake assessments.

<?xml version="1.0" encoding="UTF-8"?>
<ChoiceList xmlns="http://soap.sforce.com/2006/04/metadata">
    <choiceListValue>
        <displayOrder>1</displayOrder>
        <isDefaultValue>true</isDefaultValue>
        <label>Low Risk</label>
        <valueName>LOW</valueName>
    </choiceListValue>
    <choiceListValue>
        <displayOrder>2</displayOrder>
        <isDefaultValue>false</isDefaultValue>
        <label>Moderate Risk</label>
        <valueName>MODERATE</valueName>
    </choiceListValue>
    <choiceListValue>
        <displayOrder>3</displayOrder>
        <isDefaultValue>false</isDefaultValue>
        <label>High Risk</label>
        <valueName>HIGH</valueName>
    </choiceListValue>
    <choiceListValue>
        <displayOrder>4</displayOrder>
        <isDefaultValue>false</isDefaultValue>
        <label>Critical Risk</label>
        <valueName>CRITICAL</valueName>
    </choiceListValue>
    <description>Standardized four-tier risk severity choices for patient and member intake assessments.</description>
    <name>Clinical Risk Severity Scale</name>
</ChoiceList>

Package Manifest (package.xml)#

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

SFDX CLI Retrieval and Deployment#

Manage ChoiceList metadata across environments with the Salesforce CLI (sf):

# Retrieve all ChoiceList components from the org
sf project retrieve start --metadata ChoiceList

# Deploy a specific ChoiceList component
sf project deploy start --metadata ChoiceList:Clinical_Risk_Severity_Scale

Architect Best Practices and Gotchas#

• Avoid Duplicate ChoiceList Definitions: Before creating a new ChoiceList for an assessment, audit existing force-app/main/default/choiceLists/ files to reuse common scales (such as Yes/No/NA or Likert 1–5 scales).
• Preserve Historical valueName Entries: Never rename an active valueName that has already been captured in production assessment responses; add a new choiceListValue instead so historical reporting remains consistent.

Frequently asked questions

How does ChoiceList differ from a GlobalValueSet in Salesforce?

GlobalValueSet backs standard and custom object picklist fields in the core database schema, whereas ChoiceList defines selectable option lists specifically for dynamic questionnaires, assessments, and guided form components.

Where are ChoiceList metadata files stored in an SFDX project?

ChoiceList files are stored in the force-app/main/default/choiceLists/ directory with the .choiceList-meta.xml file extension.

Can multiple assessment questions share the same ChoiceList?

Yes, defining a single ChoiceList allows multiple assessment questions or dynamic form elements to reference the same standardized list of values without duplicating option entries.

How do I retrieve all ChoiceList records from an org using Salesforce CLI?

Run sf project retrieve start --metadata ChoiceList to pull all choice lists into your local SFDX project.