Platform Custom Setting Generate

Salesforce Custom Setting Generator and Validator

When to Use This Skill

Use this skill when you need to:

• Create a Hierarchy or List custom setting
• Generate custom setting metadata XML
• Add or validate fields on an existing custom setting
• Populate custom setting values (these are data, not metadata — see Section 6)
• Troubleshoot custom setting deployment errors

A trigger bypass / kill switch is a Custom Setting — not Apex and not a `__mdt`. When the user wants a switch admins can flip to turn behavior on or off — "disable my Account triggers during a data load", a feature toggle, a maintenance-mode flag — generate only a hierarchy custom setting with a Checkbox field (e.g. Disable_Triggers__c / Bypass__c). Do not author the Apex trigger, handler, or test that reads it, and do not model it as a Custom Metadata Type: the per-profile/per-user override a bypass flag needs is exactly what a hierarchy custom setting gives you and a __mdt does not. The Apex that checks the flag is the developer's to write — this skill generates the setting only.

1. Overview and Purpose

This document defines the mandatory constraints for generating Custom Setting metadata. A custom setting is a CustomObject with <customSettingsType> set — it is not a distinct metadata type.

File extension: .object-meta.xml File path: force-app/main/default/objects/<Name>__c/<Name>__c.object-meta.xml API name suffix: __c (identical to a regular custom object — the suffix does not distinguish them)

Values are data, not metadata. You can generate the setting's definition as XML, but you cannot deploy its values that way. There is no source-format equivalent of customMetadata/ for custom settings. Never generate a file that claims to carry setting values — see Section 6 for what to do instead.

2. Syntactic Essentials (Tier 1)

<customSettingsType> is mandatory — CRITICAL

This is the single highest-severity rule in this skill. Omitting <customSettingsType> does not produce a "you forgot customSettingsType" error. The component silently stops being a custom setting and is validated as a plain custom object.

The failure is dangerous because it is recoverable in the wrong direction: an agent that omits the element, then obediently fixes each error the platform reports, ends up with a green deploy and completely the wrong kind of component.

These two strings are mutually exclusive tells. The giveaway in the first is the phrase `for the CustomObject` and the absence of any mention of custom settings.

If a deploy reports `Must specify a non-empty plural label for the CustomObject` on something the user asked to be a custom setting, never satisfy that error by adding `<pluralLabel>`. Adding it (plus nameField, deploymentStatus, and sharingModel) makes the deploy succeed and creates a regular custom object that the user did not ask for.

Required and Allowed Elements

Forbidden Elements

Every element below produces Cannot specify: <element> for CustomSettings:

INCORRECT — carries a regular custom object's required elements:

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <customSettingsType>Hierarchy</customSettingsType>
  <label>Feature Flags</label>
  <pluralLabel>Feature Flags</pluralLabel>        <!-- WRONG: forbidden on custom settings -->
  <sharingModel>ReadWrite</sharingModel>          <!-- WRONG: forbidden -->
  <deploymentStatus>Deployed</deploymentStatus>   <!-- WRONG: forbidden -->
  <nameField>                                    <!-- WRONG: forbidden -->
    <label>Name</label>
    <type>Text</type>
  </nameField>
  <visibility>Public</visibility>
</CustomObject>

Errors: Cannot specify: pluralLabel for CustomSettings · Cannot specify: sharingModel for CustomSettings · Cannot specify: deploymentStatus for CustomSettings · Cannot specify: nameField for CustomSettings

CORRECT — minimum valid custom setting:

<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <customSettingsType>Hierarchy</customSettingsType>
  <label>Feature Flags</label>
  <description>Per-profile and per-user toggles for beta features in the ordering app. Edited by admins in Setup.</description>
  <visibility>Public</visibility>
</CustomObject>

Note there is no <fullName>. A root-level one is tolerated and ignored, but omit it — the API name comes from the directory and filename.

<customSettingsType>List</customSettingsType> deployed without needing the "Manage List Custom Settings Type" toggle in Setup. That toggle exists in some orgs, so if a List setting is rejected on a customSettingsType grounds in a different org, check Schema Settings before assuming the XML is wrong.

3. List vs Hierarchy Decision (Tier 2)

<customSettingsType> has exactly two values, and the choice changes how rows are addressed.

Default to `Hierarchy` when the user describes toggles, limits, or anything that "can be overridden." Choose List when they describe a lookup table with named rows.

If the user asks for a keyed reference table that should be deployable between orgs, a List custom setting is usually the wrong answer — its rows are data and will not travel with the deploy. Route to platform-custom-metadata-type-generate instead (Section 7).

4. Field Rules

Fields on a custom setting are ordinary CustomField components at objects/<Name>__c/fields/<Field>__c.field-meta.xml.

This skill owns the custom-setting-specific deltas only — the supported-type allowlist and the fieldManageability prohibition below. For everything generic (<fullName> derivation, <label>, <description>, <inlineHelpText>, precision/scale, <length>, externalId), follow platform-custom-field-generate.

Supported Field Types