SchemaSettings Metadata in SFDX

Architectural Overview#

SchemaSettings represents the organizational settings metadata controlling schema definition behaviors, Schema Builder administration, and custom permission delegation. In enterprise implementations, maintaining strict guardrails around how administrators interact with Object Manager and Schema Builder is crucial for preventing accidental data model sprawl and uncontrolled relationship creation.

Through SchemaSettings, Technical Architects codify data modeling governance into source control. This ensures that features like enhanced custom permission delegation and schema visualization tools behave consistently across developer environments, automated scratch orgs, sandboxes, and production.

Directory and File Conventions#

SchemaSettings is stored as a singleton configuration file inside the settings directory.

Key Metadata Fields#

The settings file exposes parameters controlling schema visualization and administrative permissions.

Declarative XML and Package Manifest Examples#

The following example enables Schema Builder and delegated custom permission management:

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

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Retrieve and deploy SchemaSettings using standard Salesforce CLI commands:

# Retrieve Schema settings
sf project retrieve start --metadata "Settings:Schema"

# Deploy Schema settings to target org
sf project deploy start --source-dir force-app/main/default/settings/Schema.settings-meta.xml

# Validate deployment in scratch org
sf project deploy validate --metadata "Settings:Schema"

Architect Best Practices and Gotchas#

• Schema Builder Governance in Production: In mature enterprise environments, creating custom objects and fields directly within production via Schema Builder bypasses version control and CI/CD validation. Use SchemaSettings and permission sets to restrict Schema Builder write operations to sandbox environments.
• Scratch Org Definitions: Add schemaSettings configurations directly into project-scratch-def.json under settings so that newly created automated test orgs reflect exact production schema policies.
• Custom Permission Delegation: Activating enableManageCustomPermissions enables security teams to delegate application-specific custom permissions without granting broad Manage Users system privileges.

Frequently asked questions

What does SchemaSettings manage in Salesforce?

It manages org-wide settings for Schema Builder, custom permissions management, and picklist restriction policies across standard and custom objects.

Where is SchemaSettings located in SFDX projects?

It is located in the settings folder under the file name Schema.settings-meta.xml.

What is the effect of enableManageCustomPermissions?

It allows administrators to delegate the management and assignment of custom permissions to designated administrative profiles and users.

Can SchemaSettings be deployed to scratch orgs during automated testing?

Yes, defining SchemaSettings in scratch org configuration files or source directories guarantees consistent data modeling rules in CI/CD pipelines.