Salesforce Custom Field Generator and Validator

Overview

Generates and validates Salesforce CustomField metadata XML, with special handling for the highest-failure-rate types — Roll-Up Summary and Master-Detail. The agent must verify the constraints below before outputting XML to prevent Metadata API deployment errors.

---

1. Universal Mandatory Attributes

Every generated field must include these tags:

Attribute	Requirement	Notes
`<fullName>`	Required	Field name only: derive from `<label>` — capitalize each word, replace spaces with `_`, append `__c`. Must start with a letter. E.g., label `Total Contract Value` → `Total_Contract_Value__c`. ⚠️ This rule is for the FIELD name. Picklist VALUE `<fullName>` is different — keep it exactly as the user spelled it, spaces and all, no `__c` (e.g. `Closed Won`, NOT `Closed_Won`). See `references/advanced-picklists.md` (ref §3).
`<label>`	Required	The UI name (Title Case)
`<description>`	Always include	Explain the business reason why this field exists.
`<inlineHelpText>`	Always include	Actionable end-user guidance that adds value beyond the label (e.g., "Enter the value in USD including tax", not "The amount").

<description> and <inlineHelpText> are mandatory outputs even though the Metadata API does not enforce them — omitting them produces low-quality metadata.

File path (SFDX source format): save each field as force-app/main/default/objects/<Object>/fields/<FieldName>__c.field-meta.xml, where <Object> is the object's API name (Account, Opportunity, or a custom Inventory_Item__c). A correct XML at the wrong path is never seen by the Metadata API.

External ID Configuration

Trigger: If the user mentions "integration," "importing data," "external system ID," or "unique key from [System Name]," set <externalId>true</externalId>.

Applicable Types: Text, Number, Email

---

2. Precision, Scale, and Length Rules

To ensure deployment success, follow these mathematical constraints:

Precision vs. Scale Rules

precision is the total digits; scale is the decimal digits
Rule: precision ≤ 18 AND scale ≤ precision
Calculation: Digits to the left of decimal = precision - scale

The "Fixed 255" Rule

TextArea: always include <length>255</length> exactly — this literal value is required by the Metadata API and omitting it fails deployment, even though the UI exposes no length control. Unlike every other type where length is a value you calculate, TextArea's is a fixed constant.

Visible Lines

Mandatory for Long/Rich text and Multi-select picklists to control UI height.

---

3. Field Data Types

3.1 Simple Attribute Types

Type	`<type>` Value	Required Attributes
Auto Number	`AutoNumber`	`displayFormat` (must include `{0}`), `startingNumber`
Checkbox	`Checkbox`	Default `defaultValue` to `false`
Date	`Date`	No precision/length required
Date/Time	`DateTime`	No precision/length required
Email	`Email`	Built-in format validation
Lookup Relationship	`Lookup`	`referenceTo`, `relationshipName`, `deleteConstraint`
Master-Detail Relationship	`MasterDetail`	`referenceTo`, `relationshipName`, `relationshipOrder`
Number	`Number`	`precision`, `scale`
Currency	`Currency`	Default precision: 18, scale: 2
Percent	`Percent`	Default precision: 5, scale: 2
Phone	`Phone`	Standardizes phone number formatting
Picklist	`Picklist`	`valueSet` containing EITHER `valueSetDefinition` (inline) OR `valueSetName` (reference); `restricted` (see "Picklist `restricted` default" below; advanced cases in §3.4)
Text	`Text`	`length` (Max 255)
Text Area	`TextArea`	`<length>255</length>`
Text (Long)	`LongTextArea`	`length`, `visibleLines` (default 3)
Text (Rich)	`Html`	`length`, `visibleLines` (default 25)
Time	`Time`	Stores time only (no date)
URL	`Url`	Validates for protocol and format

3.2 Computed & Multi-Value Types

Type	`<type>` Value	Required Attributes
Formula	Result type (e.g., `Number`)	`formula`, `formulaTreatBlanksAs`
Roll-Up Summary	`Summary`	See Section 5 for complete requirements
Multi-Select Picklist	`MultiselectPicklist`	`valueSet`, `visibleLines` (default 4)

3.3 Specialized Types

Type	`<type>` Value	Required Attributes
Geolocation	`Location`	`scale`, `displayLocationInDecimal`

Picklist `restricted` default

Always set <restricted>true</restricted> inside <valueSet> unless the user explicitly says the picklist should accept custom values not in the admin-defined list (e.g. "unrestricted"/"open"). Restricted sets are capped at 1,000 total values (active + inactive). Minimal inline shape:

<valueSet>
  <restricted>true</restricted>
  <valueSetDefinition>
    <sorted>false</sorted>
    <value><fullName>Option_A</fullName><default>false</default><label>Option A</label></value>
  </valueSetDefinition>
</valueSet>

3.4 Advanced Picklists

The inline <valueSetDefinition> above is the simple case. Full rules and worked ✅/❌ examples for everything below are in references/advanced-picklists.md — load it for any non-trivial picklist. Section numbers in parentheses below (e.g. "ref §1") point to that reference file, not to this skill. The hard rules:

Value-set reference (ref §1). A <valueSet> holds EITHER <valueSetName> (reference) OR

<valueSetDefinition> (inline) — never both. Reference by the bare developer name — Standard set Industry, GlobalValueSet Priority_Levels with NO __gvs and no __c (the __gvs suffix is org-storage display only; the Metadata API uses the bare name). A value-set-backed field is <restricted>true</restricted>. Creating the value set is the platform-value-set-generate skill's job; this one only references it.

Value-name fidelity (ref §3). A picklist value's <fullName>/<label> keep the user's exact

text including spaces (Closed Won, never Closed_Won). The space→_ + __c rule is for the FIELD name only.

Dependent picklists (ref §2). Use the modern API 38.0+ form: <controllingField> +

one <valueSettings> (<controllingFieldValue>+<valueName>) per pair; never the legacy <picklist>/<picklistValues>/<controllingFieldValues> tags. Both controlling and dependent fields MUST be <restricted>true</restricted>, even if the request doesn't say so.

Enhanced value attributes (ref §3). <value> entries also accept <color> (hex, leading

#), <isActive> (false retires a value), and a value-level <description>.

Scoping a picklist to a record type (ref §5). Per-record-type value visibility lives on the

RecordType (<picklistValues>), not the field. The RecordType file carries its own <fullName> (bare developer name). First decide if the object needs a BusinessProcess: only Opportunity / Lead / Case / Solution require one — they won't deploy without a <businessProcess> (Required field is missing: businessProcess), even when only a custom picklist is filtered. There you emit two coupled files: the businessProcesses/<Name>.businessProcess-meta.xml file AND a matching <businessProcess><Name></businessProcess> inside the <RecordType> (after <active>, before <picklistValues>; the <fullName> in the BP file is bare, never object-qualified). *Custom objects (__c) and all other standard objects (Account, Contact, …) need NO BusinessProcess — emit the RecordType alone; do not invent one. Scope limit:** picklist-value visibility per record type only — NOT general record-type authoring (compact layouts, page layouts, branding).

---

4. Master-Detail Relationship Rules CRITICAL

Master-Detail fields have strict attribute restrictions that differ from Lookup fields. Violating these rules causes deployment failures.

Forbidden Attributes on Master-Detail Fields

NEVER include these attributes on Master-Detail fields:

Forbidden Attribute	Why	What Happens
`<required>`	Master-Detail is ALWAYS required by design	Deployment error
`<deleteConstraint>`	Master-Detail ALWAYS cascades deletes	Deployment error
`<lookupFilter>`	Only supported on Lookup fields	Deployment error

Master-Detail vs Lookup Comparison

Attribute	Master-Detail	Lookup
`<required>`	❌ FORBIDDEN	✅ Optional
`<deleteConstraint>`	❌ FORBIDDEN (always CASCADE)	✅ Required (`SetNull`, `Restrict`, `Cascade`)
`<lookupFilter>`	❌ FORBIDDEN	✅ Optional
`<relationshipOrder>`	✅ Required (0 or 1)	❌ Not applicable
`<reparentableMasterDetail>`	✅ Optional	❌ Not applicable
`<writeRequiresMasterRead>`	✅ Optional	❌ Not applicable

INCORRECT — Master-Detail with forbidden attributes:

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Account__c</fullName>
  <type>MasterDetail</type>
  <referenceTo>Account</referenceTo>
  <relationshipName>Contacts</relationshipName>
  <relationshipOrder>0</relationshipOrder>
  <required>true</required>                     <!-- WRONG: remove -->
  <deleteConstraint>Cascade</deleteConstraint>  <!-- WRONG: remove -->
  <lookupFilter>...</lookupFilter>              <!-- WRONG: remove entire block -->
</CustomField>

Errors: Master-Detail Relationship Fields Cannot be Optional or Required · Can not specify 'deleteConstraint' for a CustomField of type MasterDetail · Lookup filters are only supported on Lookup Relationship Fields

CORRECT — Master-Detail field:

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Account__c</fullName>
  <label>Account</label>
  <description>Links this record to its parent Account</description>
  <type>MasterDetail</type>
  <referenceTo>Account</referenceTo>
  <relationshipLabel>Child Records</relationshipLabel>
  <relationshipName>ChildRecords</relationshipName>
  <relationshipOrder>0</relationshipOrder>
  <reparentableMasterDetail>false</reparentableMasterDetail>
  <writeRequiresMasterRead>false</writeRequiresMasterRead>
  <!-- NO required, deleteConstraint, or lookupFilter -->
</CustomField>

CORRECT — Lookup field (with optional attributes):

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Related_Account__c</fullName>
  <label>Related Account</label>
  <description>Optional link to a related Account</description>
  <type>Lookup</type>
  <referenceTo>Account</referenceTo>
  <relationshipLabel>Related Records</relationshipLabel>
  <relationshipName>RelatedRecords</relationshipName>
  <required>false</required>
  <deleteConstraint>SetNull</deleteConstraint>
  <lookupFilter>
    <active>true</active>
    <filterItems>
      <field>Account.Type</field>
      <operation>equals</operation>
      <value>Customer</value>
    </filterItems>
    <isOptional>false</isOptional>
  </lookupFilter>
</CustomField>

Additional Master-Detail Rules

Relationship Order: First Master-Detail on object = 0, second = 1
Relationship Name: Must be a plural PascalCase string (e.g., Travel_Bookings)
Junction Objects: Use two Master-Detail fields for standard many-to-many (enables Roll-ups)
Limit: Maximum 2 Master-Detail relationships per object. Use Lookup for additional relationships.

---

5. Roll-Up Summary Field Rules CRITICAL

Roll-up Summary fields have the highest deployment failure rate. Follow these rules exactly.

Required Elements for Roll-Up Summary

Element	Requirement	Format
`<type>`	Required	Always `Summary`
`<summaryOperation>`	Required	`count`, `sum`, `min`, or `max`
`<summaryForeignKey>`	Required	`ChildObject__c.MasterDetailField__c`
`<summarizedField>`	Conditional	Required for `sum`, `min`, `max`. NOT for `count`

Forbidden Elements on Roll-Up Summary

NEVER include these attributes on Roll-Up Summary fields:

Forbidden Attribute	Why
`<precision>`	Summary inherits from summarized field
`<scale>`	Summary inherits from summarized field
`<required>`	Not applicable to Summary fields
`<length>`	Not applicable to Summary fields

Format Rules for summaryForeignKey and summarizedField

CRITICAL: Both summaryForeignKey and summarizedField MUST use the fully qualified format:

ChildObjectAPIName__c.FieldAPIName__c

Decision Logic:

summaryForeignKey = ChildObject__c.MasterDetailFieldOnChild__c
summarizedField = ChildObject__c.FieldToSummarize__c

INCORRECT — Roll-Up Summary with common errors:

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Total_Amount__c</fullName>
  <label>Total Amount</label>
  <type>Summary</type>
  <precision>18</precision>           <!-- WRONG: Remove - inherited from source -->
  <scale>2</scale>                    <!-- WRONG: Remove - inherited from source -->
  <summaryOperation>sum</summaryOperation>
  <summaryForeignKey>Order__c</summaryForeignKey>        <!-- WRONG: Missing field name -->
  <summarizedField>Amount__c</summarizedField>           <!-- WRONG: Missing object name -->
</CustomField>

Errors:

Can not specify 'precision' for a CustomField of type Summary
Must specify the name in the CustomObject.CustomField format (e.g. Account.MyNewCustomField)

CORRECT — Roll-Up Summary (SUM operation):

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Total_Amount__c</fullName>
  <label>Total Amount</label>
  <description>Sum of all line item amounts</description>
  <inlineHelpText>Automatically calculated from child line items</inlineHelpText>
  <type>Summary</type>
  <summaryOperation>sum</summaryOperation>
  <summarizedField>Order_Line_Item__c.Amount__c</summarizedField>
  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
  <!-- NO precision, scale, required, or length -->
</CustomField>

COUNT: identical structure to SUM but omit <summarizedField> entirely (and keep <summaryForeignKey>). MIN / MAX: identical to SUM — just <summaryOperation>min</summaryOperation> or max, with <summarizedField> pointing at the field to find the minimum/maximum of. The Quick Reference table below covers all four.

Roll-Up Summary Quick Reference

Operation	summarizedField Required?	Use Case
`count`	NO	Count number of child records
`sum`	YES	Add up numeric values
`min`	YES	Find smallest value
`max`	YES	Find largest value

Roll-Up Summary Prerequisites

Roll-Up Summary fields can ONLY be created on the parent object in a Master-Detail relationship
The child object MUST have a Master-Detail field pointing to this parent
The summarized field must exist on the child object

---

6. Formula Field Rules

Formula Result Types

A Formula is not a type itself. The <formula> tag is added to a field whose <type> is set to the result data type:

Checkbox, Currency, Date, DateTime, Number, Percent, Text

Formula XML Generation Rules

The contents of the <formula> tag MUST be wrapped in a <![CDATA[ ... ]]> section. This prevents the XML parser from interpreting formula operators (like &, <, >) as XML markup.
If the formula text itself contains the literal sequence ]]>, escape it by breaking the CDATA block: e.g., <![CDATA[Text_Field__c & "]]]]><![CDATA[>"]]>
NEVER use an attribute or tag named returnType. This does not exist in the Metadata API. The <type> tag defines the return data type of the formula result.

formulaTreatBlanksAs Rule