NameSettings Metadata Type in SFDX

Architectural Overview#

NameSettings is an org-level metadata type that controls the constituent subfields of compound name fields across Salesforce. By default, core entities represent a person’s name via Salutation, FirstName, and LastName. Deploying NameSettings expands the standard name schema to support MiddleName, Suffix, and InformalName across Contact, Lead, User, PersonAccount, and related person-centric tables.

From an enterprise data architecture perspective, enabling these fields aligns Salesforce data models with international naming conventions, KYC compliance mandates, and downstream identity federation systems.

Directory and File Conventions#

NameSettings files reside in the settings/ directory and are identified by the Name member name.

Key Metadata Fields#

The configuration fields exposed by NameSettings are:

Declarative XML and Package Manifest Examples#

A standard production Name.settings-meta.xml manifest enabling full compound name capabilities:

<?xml version="1.0" encoding="UTF-8"?>
<NameSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableInformalName>true</enableInformalName>
    <enableMiddleName>true</enableMiddleName>
    <enableNameSuffix>true</enableNameSuffix>
</NameSettings>

Scratch Org Configuration (config/project-scratch-def.json)#

To replicate compound name fields in scratch orgs, add nameSettings to the definitions:

{
  "orgName": "Global Identity Scratch Org",
  "edition": "Enterprise",
  "settings": {
    "nameSettings": {
      "enableMiddleName": true,
      "enableNameSuffix": true,
      "enableInformalName": true
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Retrieve and deploy NameSettings using the Salesforce CLI:

# Retrieve Name settings from the org
sf project retrieve start --metadata Settings:Name

# Deploy Name settings to the target org
sf project deploy start --metadata Settings:Name

Architect Best Practices and Gotchas#

• Dependency Ordering in CI/CD: Any page layouts, FlexiPages, validation rules, or Apex classes referencing MiddleName or Suffix will fail deployment if NameSettings is not deployed first. Include Name.settings-meta.xml in base infrastructure deployments.
• Data Integration Payloads: Upstream CRM or ERP integrations that map single string names to FirstName and LastName may split or truncate names unpredictably once MiddleName is active. Audit inbound REST/SOAP schemas before enabling.
• Reporting and Formulas: Formulas referencing Name automatically concatenate active name elements (Salutation, FirstName, MiddleName, LastName, Suffix). Verify that customer communication templates do not inadvertently duplicate suffixes or middle names.

Frequently asked questions

What standard entities are affected when enableMiddleName is activated?

Activating middle names updates Lead, Contact, User, and Person Account entities, making MiddleName accessible via API, layouts, and search.

Can informal names be searched through Global Search?

Yes. Enabling informal names allows nicknames to be indexed and queried through Global Search and SOSL queries.

How is NameSettings referenced in an SFDX package.xml manifest?

It is retrieved under the Settings metadata type using Name as the member name.