Org Shape And Scratch Definition

Org Shape and Scratch Definition

This skill activates when a practitioner needs to author, troubleshoot, or refine the scratch org definition file (project-scratch-def.json). It covers the full schema depth of the definition file including edition selection, feature declarations, settings blocks, Org Shape sourcing, and release channel pinning. It does not cover scratch org lifecycle commands, CI pipeline orchestration, or sandbox strategy.

Before Starting

Gather this context before working on anything in this domain:

• What Dev Hub edition is in use? Org Shape requires Enterprise Edition or higher on the Dev Hub.
• Which features does the target org need that go beyond the default Developer edition scratch org (e.g., Communities, MultiCurrency, ServiceCloud, PersonAccounts)?
• Is the team migrating from the deprecated orgPreferences block, or starting fresh with settings?

Core Concepts

Understanding the scratch org definition file requires clarity on four areas: schema structure, the features array, the settings hierarchy, and Org Shape.

Definition File Schema

The project-scratch-def.json file is the declarative blueprint for a scratch org. It lives at the root of an SFDX project (or a path specified by --definition-file). The top-level keys include orgName, edition, features, settings, language, country, hasSampleData, release, and sourceOrg. The edition field accepts values like Developer, Enterprise, Group, and Professional. If omitted, Developer is the default. The edition determines the baseline feature ceiling -- for example, you cannot use Record Types in a Group edition scratch org.

Features Array

The features array enables specific platform capabilities that are not part of the base edition. Examples include Communities, ServiceCloud, LightningServiceConsole, API, AuthorApex, MultiCurrency, PersonAccounts, StateAndCountryPicklist, and AnalyticsCRMAnalyticsPlusPlatform. Feature names are case-sensitive strings. An invalid or misspelled feature name causes org creation to fail with an INVALID_INPUT error. Some features depend on edition -- for instance, PersonAccounts requires Enterprise edition or higher.

Settings Hierarchy

Since Winter '20, the settings object replaced the deprecated orgPreferences block. Settings are organized by Metadata API type. For example, Translation Workbench is enabled via languageSettings.enableTranslationWorkbench: true, and chatter is controlled by chatterSettings.enableChatter: true. The structure mirrors the Salesforce Metadata API settings types, so any setting available in <SettingsType> metadata can be expressed here using camelCase property paths. Attempting to use the old orgPreferences key will produce a deprecation warning and may be silently ignored in newer CLI versions.

Org Shape

Org Shape lets you create scratch orgs that replicate the shape (features, settings, limits) of an existing source org. You enable it by setting "sourceOrg": "<orgId>" in the definition file and omitting edition, features, and settings that conflict. The source org must be connected to the Dev Hub. However, Org Shape does not capture every feature -- notably, MultiCurrency, PersonAccounts, and certain ISV features are excluded and must still be declared explicitly in the features array alongside the sourceOrg reference. Org Shape is only available when the Dev Hub is Enterprise Edition or above.

Common Patterns

Pattern: Hybrid Org Shape with Explicit Feature Overrides

When to use: Your team wants scratch orgs that closely mirror production but production uses features Org Shape does not capture (MultiCurrency, PersonAccounts).

How it works:

1. Set sourceOrg to the 15- or 18-character Org ID of the source org.
2. Add the uncaptured features to the features array explicitly.
3. Add any settings that Org Shape does not carry over to the settings block.
4. Omit edition -- Org Shape infers it from the source.

{
  "sourceOrg": "00D000000000001",
  "features": ["MultiCurrency", "PersonAccounts"],
  "settings": {
    "languageSettings": {
      "enableTranslationWorkbench": true
    }
  }
}

Why not the alternative: Using Org Shape alone silently omits these features, leading to deployment failures or missing functionality during development that only surfaces during UAT.

Pattern: Edition-Pinned Minimal Definition for Package Development

When to use: You are building an unlocked or managed package and need a lightweight, fast-provisioning scratch org with only the features the package requires.

How it works:

1. Set edition explicitly (usually Developer).
2. Declare only the features your package metadata requires.
3. Pin release to "Previous" if you need stability against preview-release breakage.

{
  "orgName": "Package Dev Scratch",
  "edition": "Developer",
  "features": ["LightningComponentBundle", "API"],
  "settings": {
    "lightningExperienceSettings": {
      "enableS1DesktopEnabled": true
    }
  },
  "release": "Previous"
}

Why not the alternative: Including unnecessary features slows provisioning and introduces surface area for flaky CI failures.

Decision Guidance

Recommended Workflow

Step-by-step instructions for authoring or debugging a scratch org definition file:

1. Identify target capabilities -- List every Salesforce feature, setting, and edition requirement the development work needs. Cross-reference with the source production org if available.
2. Choose sourcing strategy -- Decide between Org Shape (sourceOrg) and manual feature/settings declaration. Use Org Shape when the source org is Enterprise+ and the Dev Hub supports it; otherwise, declare manually.
3. Draft the definition file -- Write project-scratch-def.json with the chosen edition (or sourceOrg), features array, and settings blocks. Use the Metadata API settings type names for the settings hierarchy.
4. Validate feature names -- Confirm each feature string against the official Salesforce feature list. Misspelled or unsupported feature names cause creation failure with no partial-match hint.
5. Test org creation -- Run sf org create scratch --definition-file config/project-scratch-def.json --target-dev-hub <hub> and inspect the output for warnings or errors. Fix any INVALID_INPUT messages.
6. Verify feature availability -- After creation, open the scratch org and confirm the expected features are enabled (e.g., check Setup > Company Information for MultiCurrency, check Communities setup page).
7. Commit and document -- Store the validated definition file in the project repo under config/. Document any Org Shape gaps that required explicit overrides.

Review Checklist

Run through these before marking work in this area complete:

• Definition file has valid JSON syntax and all required top-level keys
• Edition is appropriate for the features declared (no Group edition with Record Types)
• No use of deprecated orgPreferences -- all preferences expressed via settings
• Org Shape source org is connected to the Dev Hub (if using sourceOrg)
• Features excluded from Org Shape (MultiCurrency, PersonAccounts) are declared explicitly
• Feature names are spelled exactly as documented (case-sensitive)
• release is set intentionally (Previous, Current, or omitted for default)
• Scratch org creation succeeds and target features are verified in the running org

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Org Shape silently omits features -- MultiCurrency, PersonAccounts, and certain ISV-specific features are not captured by Org Shape. The scratch org creates successfully but is missing capabilities, which only surfaces when deploying metadata that depends on them.
2. orgPreferences deprecation is silent -- Since Winter '20, orgPreferences is deprecated. Some CLI versions silently ignore it rather than erroring, so your definition file appears to work but the preferences are not applied.
3. Feature names are case-sensitive -- Declaring "multicurrency" instead of "MultiCurrency" produces an INVALID_INPUT error. There is no fuzzy matching or helpful suggestion in the error message.

Output Artifacts

Related Skills

• scratch-org-management -- Use for scratch org lifecycle operations (creation, deletion, allocation management, CI automation)
• unlocked-package-development -- Use when the definition file is part of a package development workflow
• environment-strategy -- Use for broader environment planning across sandboxes, scratch orgs, and production

Official Sources Used

• Scratch Org Definition File -- https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_def_file.htm
• Scratch Org Definition Configuration Values -- https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_def_file_config_values.htm
• Salesforce DX Developer Guide -- https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_intro.htm