SharingSettings Metadata Type in SFDX

Architectural Overview#

SharingSettings is the global metadata type that governs the organization-wide data access infrastructure in Salesforce. While individual object defaults (such as sharingModel and externalSharingModel) are defined on CustomObject, SharingSettings controls platform-wide policies: deferred sharing calculation, manager group sharing, standard report visibility, secure guest user record access, and asset sharing.

In large-scale enterprise deployments, managing SharingSettings via metadata is critical for data governance and operational stability. For instance, Deferred Sharing Calculation allows large data volume (LDV) migration teams to suspend automatic recalculations of sharing rules while importing millions of accounts or reshaping global role hierarchies. Once data loading completes, sharing recalculation is resumed in a controlled, non-blocking window.

Directory and File Conventions#

In SFDX source format, SharingSettings is stored in the settings directory under the filename Sharing.settings-meta.xml.

Key Metadata Fields#

The SharingSettings metadata structure provides top-level security controls:

Declarative XML and Package Manifest Examples#

Below is an enterprise Sharing.settings-meta.xml file configured for strict corporate governance:

<?xml version="1.0" encoding="UTF-8"?>
<SharingSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <deferSharingCalculation>false</deferSharingCalculation>
    <enableAssetSharing>true</enableAssetSharing>
    <enableExternalSharingModelRule>true</enableExternalSharingModelRule>
    <enableManagerGroups>true</enableManagerGroups>
    <enableSecureGuestAccess>true</enableSecureGuestAccess>
    <enableStandardReportVisibility>true</enableStandardReportVisibility>
</SharingSettings>

Manifest Definition (package.xml)#

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

Retrieval and Deployment#

Use the Salesforce CLI to retrieve and deploy SharingSettings:

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

# Deploy Sharing settings
sf project deploy start --metadata "Settings:Sharing"

Senior Architect Deployment Best Practices and Gotchas#

1. Deferred Sharing Calculation Workflow: Never deploy deferSharingCalculation: true into production without a scheduled plan to recalculate. While calculations are deferred, sharing rule changes and role reassignments will not reflect in record visibility until recalculated via the Setup UI.
2. External Sharing Model Enabling: Enabling enableExternalSharingModelRule allows distinct external sharing models. Once enabled and customized, reverting an object’s external sharing model from Private back to Public requires recalculating external shares.
3. Manager Groups Adoption: Enabling enableManagerGroups provides two automatic groups for every user: Manager and Manager Subordinates. This significantly reduces the proliferation of custom public groups created solely for hierarchical approvals.
4. Scratch Org Definitions: Include sharingSettings in config/project-scratch-def.json when automated test suites validate community guest user access or manager group record sharing.

Frequently asked questions

What global sharing behaviors are governed by SharingSettings?

It controls deferred sharing calculations, manager group sharing, standard report visibility, and external sharing model enforcement.

Where is SharingSettings stored in SFDX format?

In force-app/main/default/settings/Sharing.settings-meta.xml and retrieved using the Settings:Sharing metadata component.

What is deferred sharing calculation and when should architects use it?

It suspends sharing rule calculations during massive data migrations or role reorganizations, resuming recalculation during maintenance windows.

How does secure guest user access impact public sites and communities?

Enforcing secure guest access forces external org-wide defaults to Private for guest users and restricts sharing to guest sharing rules.