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

Checkbox, Currency, Date, DateTime, Email, Number, Percent, Phone, Text, TextArea, Url

required, unique, externalId, and defaultValue are accepted on custom setting fields. Whether a given one applies to a given type is a generic field rule — defer to platform-custom-field-generate.

Unsupported Field Types

Picklist, MultiselectPicklist, LongTextArea, Html, Lookup, MasterDetail, AutoNumber, Location, Time, EncryptedText, and Formula (a <formula> element on any type).

Every one of these fails with the same bare, uninformative string:

Invalid data type.

This error names neither field nor type. On a multi-field deploy, read componentFailures[].fullName from the --json output to find the culprit — do not guess.

Roll-up summary fields are structurally impossible here — a Summary needs a master-detail child, and MasterDetail is itself rejected on a custom setting. Don't generate one; the error text varies, so don't match on a specific string.

Picklist is the common trap. Users frequently ask for a picklist on a custom setting. It is not supported. Use Text and enforce the allowed values in Apex, or route the request to platform-custom-metadata-type-generate — CMDT does support Picklist.

Near-inversion vs CMDT: Currency works here but not on CMDT; Picklist/LongTextArea work on CMDT but not here. Never carry field-type assumptions across the two families.

<fieldManageability> is forbidden

That element belongs to CMDT fields only. On a custom setting field it fails with:

Field manageability cannot be set on this entity.

5. Visibility, Secrets, and the No-Silent-Downgrade Rule

Protected is org-type dependent

<visibility>Protected</visibility> deploys only in a developer, sandbox, or scratch org. Anywhere else:

You can't set the visibility for a Custom Setting to Protected unless you are in a developer, sandbox, or scratch org.

The no-silent-downgrade rule — CRITICAL

If `Protected` fails because of the org type, never "fix" it by switching to `Public`. A silent downgrade turns a deliberate confidentiality choice into a world-readable component with no signal. Report it plainly: the org does not permit Protected, so the options are a dev/sandbox/scratch org or accepting Public — let the user decide. This applies to any visibility narrowing, not just this error.

Secrets do not belong in a custom setting

Custom settings are not a secret store. Values are readable by anyone who can query the object, and Protected does not change that for code in the same namespace.

When a user asks to store an API key, password, token, client secret, or certificate in a custom setting:

1. Warn prominently and first — before generating anything — that a custom setting is the wrong place

for a credential and the value will be readable.

1. Recommend the right component — a Named Credential with an External Credential for callout

auth. Say plainly that this skill does not generate those.

1. If the user still insists, comply — generate the setting but keep the warning in the response. Do not

silently refuse, and do not silently obey.

Never route a secret to Protected visibility as a compromise: if Protected is unavailable (above), the no-silent-downgrade rule applies with full force, because the downgrade would publish the secret.

6. Setting Values Are Data, Not Metadata

A custom setting's rows cannot be deployed as XML. There is no customMetadata/-style folder for them. Only the object definition and its fields are metadata.

When a user asks to create a setting with values — "add a feature flag setting with Beta enabled for admins" — do all of the following:

1. Generate the object and field XML as normal.
2. State the limitation in one line: setting values are data, not metadata, so they are not deployed.
3. Give ready-to-run commands inline in the chat response, fully substituted with the real object and

field API names and the actual values — not a placeholder template, and not written to a file.

All three shapes below are verified working.

Hierarchy — org-wide default row

Omit `SetupOwnerId`. It defaults to the Organization Id, which is exactly the org-default row. No Id lookup is needed.

sf data create record --sobject Feature_Flags__c \
  --values "Enable_Beta__c=true Max_Retries__c=3" \
  --target-org <alias>

Hierarchy — profile or user override

This one does need an Id, so it is two steps. A user-level override uses the same shape with a User Id in place of the Profile Id (extrapolated from the profile case, not separately verified).

sf data query --query "SELECT Id FROM Profile WHERE Name='System Administrator'" --target-org <alias>

sf data create record --sobject Feature_Flags__c \
  --values "SetupOwnerId=00eXXXXXXXXXXXXXXX Enable_Beta__c=false" \
  --target-org <alias>

An override row coexists with the org-default row; it does not replace it.

List — one row per key

Name is the row key and is required.

sf data create record --sobject Country_Codes__c \
  --values "Name='US' Iso_Code__c='USA' Dial_Prefix__c='+1'" \
  --target-org <alias>

Quoting

Wrap the whole --values argument in double quotes; single-quote any value with a space or shell-special character (Environment_Label__c='org default'). Plain numbers, booleans, and Ids need no inner quotes.

Consuming a setting in Apex

Values are read through the generated typed class — cached, so reads cost no SOQL and are safe inside loops and triggers. For a Hierarchy setting:

Feature_Flags__c cfg = Feature_Flags__c.getInstance();        // running user: user → profile → org default
Feature_Flags__c org = Feature_Flags__c.getOrgDefaults();     // org-default row only, no hierarchy
Feature_Flags__c forProfile = Feature_Flags__c.getInstance(profileId);  // a User Id works too
Boolean beta = cfg.Enable_Beta__c;

getInstance() and getOrgDefaults() never return null (API ≥ 22) — a missing record comes back as an empty row, so test org.Id != null when you need to know whether a real record actually exists. For a List setting, use getValues('Key') for one row or getAll() for the Map<String, Feature_Flags__c> of every row.

The in-transaction DML rule

Populating or changing values is runtime DML (Apex insert/update/upsert, or the sf commands above) — there is no metadata path. That is the operational face of "values are data," and it has two consequences worth stating to the user:

• Writes count against DML governor limits; reads do not. In a trigger over 200 records, never upsert

the setting once per record — hoist the write out of the loop and do it once.

• Cross-transaction propagation lags. After a write, other transactions may briefly read the previous

value while the org cache propagates; within the same transaction the new value is visible immediately.

7. Choosing the Right Component

Before generating, confirm a custom setting is actually what the user needs. If it is not, say so and name the right skill rather than building the wrong thing.

The distinction that matters most: CMDT records deploy, custom setting values do not. If the user says "and it should ship with these values" or "the same in every org," that is a CMDT request.

8. Common Deployment Errors

The Cannot specify: suffix is for CustomSettings (one word) versus CMDT's for Custom Metadata Type, and the visibility error uses for a Custom Setting (spaced, singular). Do not assume a shared template when matching these strings.

9. Verification Checklist

Before generating custom setting XML, verify:

Component Identity Checks CRITICAL

• [ ] Is <customSettingsType> present and set to Hierarchy or List?
• [ ] Is the choice between Hierarchy and List justified by the request (overridable vs keyed table)?
• [ ] If a deploy reported Must specify a non-empty plural label for the CustomObject, was it fixed by adding <customSettingsType> rather than by adding <pluralLabel>?
• [ ] After a successful deploy of a new setting, was it confirmed to actually be a custom setting? Inspecting the XML cannot catch this failure, because the wrong-component outcome deploys green. Run sf sobject describe --sobject <Name>__c --target-org <alias> and verify customSetting is true.

Syntactic Checks

• [ ] Are <label> and <visibility> present?
• [ ] Is <description> present and specific about what the setting controls?
• [ ] Is <pluralLabel> ABSENT?
• [ ] Are <nameField>, <sharingModel>, and <deploymentStatus> ABSENT?
• [ ] Are <enableActivities>, <enableReports>, <enableHistory>, and <enableSearch> ABSENT?
• [ ] Are <validationRules>, <recordTypes>, and <compactLayouts> ABSENT?
• [ ] Does the filename match the intended API name, ending in __c?

Field Checks

• [ ] Is every field type in the supported list (Section 4)?
• [ ] Is Picklist absent? (unsupported — use Text, or route to CMDT)
• [ ] Is every <formula> element absent? (formulas are unsupported)
• [ ] Is <fieldManageability> ABSENT on every field?
• [ ] Do generic field attributes follow platform-custom-field-generate?

Values Checks

• [ ] If the user asked for values, was the data-not-metadata limitation stated explicitly?
• [ ] Were sf commands given inline in the response, fully substituted with real API names and real values — not written to a file, not left as a template?
• [ ] For a Hierarchy org default, is SetupOwnerId omitted rather than guessed?
• [ ] For a List row, is Name supplied?

Consumption Checks

• [ ] If the user asked how to read the setting, was an Apex snippet given using the generated accessors (getInstance / getOrgDefaults for Hierarchy, getValues / getAll for List)?
• [ ] Was the in-transaction DML rule stated — writes are DML that count against limits (bulkify, hoist out of loops), reads are free, and cross-transaction cache propagation lags?

Security Checks CRITICAL

• [ ] If the request involves a secret, key, token, or password, was the warning given before generating, with a Named Credential recommended?
• [ ] Was Protected left intact rather than silently downgraded to Public on an org-type failure?

Component-Choice Checks

• [ ] If the values must deploy between orgs, was platform-custom-metadata-type-generate recommended instead?
• [ ] If the request is really business records, was platform-custom-object-generate recommended instead?