FieldDefinition

Concept: Objects, Records, and Fields →

The parsed contents of a *_field.json5 file: one of five authorable field kinds, plus a sixth, synthesis-only kind.

Tagged by the fieldKind property: "scalar", "formula", "lookup", "rollup", "composite", or "relatedRecords" (never authored directly — see RelatedRecordsFieldDefinition).

Field Kinds

scalar — Scalar

"scalar" — a single user-provided value stored in one column. See ScalarFieldDefinition.

Property	Type	Required/Default	Constraints	Meaning
fieldKey	string	Required	min length 1; max length 63; pattern ^[a-z][a-zA-Z0-9]*$	The field’s API name.
label	string	Required		Human-readable display name.
fieldType	ScalarType	Required		The data type of the stored value.
required	boolean	Optional (default: false)		When true, the column is NOT NULL and the data API rejects create/update requests that omit or null this field.
unique	boolean	Optional (default: false)		When true, the column has a UNIQUE constraint.
indexed	boolean	Optional (default: false)		When true, a non-unique B-tree index is created on the column.

fieldKey

The field’s API name. Uses camelCase by convention (e.g. firstName, email). Converted to snake_case for the SQL column name.

required

When true, the column is NOT NULL and the data API rejects create/update requests that omit or null this field. When false, the field is nullable.

unique

When true, the column has a UNIQUE constraint. The data API returns a 409 UNIQUE_CONSTRAINT_VIOLATION error on duplicate values. Unique fields can also be used as the match key for PUT upsert operations.

indexed

When true, a non-unique B-tree index is created on the column. Unique fields are implicitly indexed by the unique constraint.

formula — Formula

"formula" — a read-only value computed from an expression. See FormulaFieldDefinition.

Property	Type	Required/Default	Constraints	Meaning
fieldKey	string	Required	min length 1; max length 63; pattern ^[a-z][a-zA-Z0-9]*$	The field’s API name.
label	string	Required		Human-readable display name.
returnType	ScalarType	Required		The data type of the computed result.
formula	string	Required		The formula expression, e.g. "firstName & ' ' & lastName".
indexed	boolean	Optional (default: false)		When true, the compiler creates an expression index on the generated column.

fieldKey

The field’s API name. Uses camelCase.

returnType

The data type of the computed result. Uses the same type names as scalar fields.

indexed

When true, the compiler creates an expression index on the generated column. Only applicable to same-row formulas — cross-object formulas cannot be indexed.

lookup — Lookup

"lookup" — a reference to a record in another object. See LookupFieldDefinition.

Property	Type	Required/Default	Constraints	Meaning
fieldKey	string	Required	min length 1; max length 63; pattern ^[a-z][a-zA-Z0-9]*$	The field’s API name.
label	string	Required		Human-readable display name.
to	string	Required		The target object(s) this lookup references.
toInverseKey	string	Required		The API name for the inverse (child) side of the relationship, as seen from the target object (e.g. "contacts").
toInverseLabel	string	Required		Human-readable label for the inverse side (e.g. "Contacts").
required	boolean	Optional (default: false)		When true, the reference is mandatory: the FK column is NOT NULL and the data API rejects creates/updates that omit or null this field.
onParentDelete	enum (OnParentDelete)	Optional		Controls what happens to this record when the referenced (parent) record is deleted.
unique	boolean	Optional (default: false)		When true, the FK column has a UNIQUE constraint, enforcing a one-to-one relationship: each target record can be referenced by at most one record through this lookup.
mutable	boolean	Optional (default: true)		Controls whether the reference can change after the record is created.

fieldKey

The field’s API name. Uses camelCase (e.g. account, parentCase). The SQL column name is the snake_case form with _id appended (e.g. account_id).

to

The target object(s) this lookup references. A single object name (e.g. "core.Account") creates a single-target lookup — the reference accepts a record of that object, or, when the object is a base type in an inheritance hierarchy, any of its derived types. An array of object names (e.g. ["core.Account", "core.Contact"]) creates a multi-target lookup — the reference accepts a record of any object in the set.

toInverseKey

The API name for the inverse (child) side of the relationship, as seen from the target object (e.g. "contacts"). This is descriptive metadata only; no separate field file is authored for the inverse side.

required

When true, the reference is mandatory: the FK column is NOT NULL and the data API rejects creates/updates that omit or null this field. When false, records can exist without a parent reference.

onParentDelete

Controls what happens to this record when the referenced (parent) record is deleted. Accepts "restrict" (blocks deletion of the parent while any child references it), "setNull" (clears this field on delete), or "cascade" (deletes this record when the parent is deleted). When omitted, the default is derived from required: "setNull" for an optional reference, "restrict" for a required one. Pairing required: true with onParentDelete: "setNull" is invalid — a NOT NULL column cannot be cleared — so the compiler auto-corrects it to "restrict" and emits a warning diagnostic.

mutable

Controls whether the reference can change after the record is created. When false, any update that changes this field is rejected and the reference is permanently set at creation time. Defaults to true.

rollup — Rollup

"rollup" — a trigger-maintained aggregate of child records. See RollupFieldDefinition.

Property	Type	Required/Default	Constraints	Meaning
fieldKey	string	Required	min length 1; max length 63; pattern ^[a-z][a-zA-Z0-9]*$	The field’s API name.
label	string	Required		Human-readable display name.
returnType	ScalarType	Required		The data type of the aggregate result, e.g. int for count, decimal for sum.
relationship	string	Required		The inverse relationship key on this object — must match the toInverseKey of a child lookup field that targets this object.
function	enum (RollupFunction)	Required		The aggregation function to apply across child records.
sourceField	string	Optional		The field key on the child object to aggregate.

fieldKey

The field’s API name. Uses camelCase.

relationship

The inverse relationship key on this object — must match the toInverseKey of a child lookup field that targets this object. For example, if a Contact’s account lookup has toInverseKey: "contacts", a rollup on Account uses relationship: "contacts".

sourceField

The field key on the child object to aggregate. Required for sum, min, max, and avg; ignored for count — setting it on a count rollup produces a compiler warning. The referenced field must exist on the child object.

composite — Composite

"composite" — a single logical value stored across multiple columns. See CompositeFieldDefinition.

Property	Type	Required/Default	Constraints	Meaning
fieldKey	string	Required	min length 1; max length 63; pattern ^[a-z][a-zA-Z0-9]*$	The field’s API name.
label	string	Required		Human-readable display name.
compositeType	CompositeType	Required		The composite type declaration, tagged by kind.
required	boolean	Optional (default: false)		When true, every sub-field column is NOT NULL and the data API rejects create/update requests that omit or null this field.
indexed	boolean	Optional (default: false)		When true, a B-tree index is created on the composite’s primary sub-field column (for Money, the _amount column).

fieldKey

The field’s API name. Uses camelCase. Physical columns are named from the snake_case form of this key plus a per-sub-field suffix (e.g. price → price_amount, price_currency).

compositeType selects the composite kind and its own configuration — see Composite Types below.

Scalar Types

Scalar type taxonomy for Henceforth field definitions.

Every scalar field declares its type via the kind property in the field’s .json5 file, for example {"kind": "bool"} or {"kind": "text", "maxLength": 255}. Parameterless kinds need no further properties; kinds with parameters list them alongside kind. Each variant below documents its kind value, its accepted parameters, and the PostgreSQL column type it compiles to.

bool

BOOLEAN — true/false value.

Property	Type	Required/Default	Constraints	Meaning

date

DATE — calendar date without time-of-day.

Property	Type	Required/Default	Constraints	Meaning

uuid

UUID — 128-bit universally unique identifier, for external identifiers.

Property	Type	Required/Default	Constraints	Meaning

binary

BYTEA — arbitrary binary data; transmitted as base64 over the API.

Property	Type	Required/Default	Constraints	Meaning

inet

INET — IPv4 or IPv6 host or network address; host bits may be non-zero.

Property	Type	Required/Default	Constraints	Meaning

cidr

CIDR — IPv4 or IPv6 network address; host bits must be zero (enforced at write boundary).

Property	Type	Required/Default	Constraints	Meaning

json

JSONB — binary JSON; supports GIN indexing and @> containment operators.

Optionally carries a JSON Schema (Draft 2020-12) that incoming values must conform to. The schema is stored in field metadata (.json5 file) and evaluated at compile time. If absent, any well-formed JSON is accepted.

Property	Type	Required/Default	Constraints	Meaning
schema	any	Optional		Optional JSON Schema that incoming values must conform to.

schema

Optional JSON Schema that incoming values must conform to. Must be valid JSON Schema Draft 2020-12; an invalid schema is rejected when the module is compiled.

timestamp

TIMESTAMPTZ — timezone-aware timestamp; always stored as UTC.

TIMESTAMP WITHOUT TIME ZONE is intentionally unavailable — it silently loses timezone context on every store/retrieve.

Property	Type	Required/Default	Constraints	Meaning

int

Signed integer. Maps to SMALLINT, INTEGER, or BIGINT based on size.

Defaults to BIGINT — always safe; choose a smaller size only when storage density or join-key compatibility requires it.

Property	Type	Required/Default	Constraints	Meaning
size	enum (IntSize)	Optional (default: "big")		Storage width.

size

Storage width. Defaults to Big (BIGINT).

float

Approximate floating-point. Maps to REAL or DOUBLE PRECISION based on size.

Not suitable for monetary values — use Decimal instead.

Property	Type	Required/Default	Constraints	Meaning
size	enum (FloatSize)	Optional (default: "double")		Storage width.

size

Storage width. Defaults to Double (DOUBLE PRECISION).

decimal

Exact arbitrary-precision numeric. Maps to NUMERIC, NUMERIC(p), or NUMERIC(p,s).

Without parameters emits bare NUMERIC (variable precision). Set precision for fixed-width; set scale alongside precision for fixed decimal places.

Property	Type	Required/Default	Constraints	Meaning
precision	integer (uint16)	Optional	minimum 0; maximum 65535	Total significant digits (1–1000).
scale	integer (uint8)	Optional	minimum 0; maximum 255	Digits after the decimal point (0–precision).

precision

Total significant digits (1–1000). If absent, bare NUMERIC.

scale

Digits after the decimal point (0–precision). If absent with precision, defaults to 0.

text

Variable-length text. Maps to TEXT (unbounded) or VARCHAR(n) when max_length is set.

Property	Type	Required/Default	Constraints	Meaning
maxLength	integer (uint32)	Optional	minimum 0	Maximum character length → VARCHAR(n).

maxLength

Maximum character length → VARCHAR(n). If absent, TEXT. Authored as maxLength.

timeInterval

Duration / time interval. Maps to INTERVAL or INTERVAL <fields>.

fields restricts which time components are stored and accepted. precision controls fractional-seconds digits (0–6); only meaningful when fields includes a SECOND component.

Property	Type	Required/Default	Constraints	Meaning
fields	enum (IntervalFields)	Optional		Restricts which time components are stored and accepted.
precision	integer (uint8)	Optional	minimum 0; maximum 255	Fractional-seconds precision (0–6).

fields

Restricts which time components are stored and accepted. If absent, all components (years through microseconds) are valid.

precision

Fractional-seconds precision (0–6). Meaningful only when fields includes a SECOND component; compile error otherwise.

enum

Controlled vocabulary field — stores one of a declared set of string values.

Maps to TEXT column + CHECK (col IN (...)) constraint. Values are validated at the write boundary; optional state machine transitions constrain which value changes are allowed on UPDATE, independently of the declared value set itself — the value set may be edited on a later apply (values added or removed), while transitions govern which value-to-value moves a record may make.

Property	Type	Required/Default	Constraints	Meaning
values	array of string	Required		Ordered list of valid values.
transitions	array of EnumTransition object	Optional		State machine transition rules.

values

Ordered list of valid values. Must be non-empty, with no duplicate entries — both are rejected when the module is compiled.

transitions

State machine transition rules. If present, UPDATE operations must follow the declared transitions. Every from and to value must appear in values; an unlisted value is rejected when the module is compiled.

email

RFC 5321-subset email address. Stored as TEXT; lowercased at the write boundary. A CHECK constraint enforces basic format on the PG column.

Property	Type	Required/Default	Constraints	Meaning

url

https?:// URL. Stored as TEXT with a CHECK constraint.

Property	Type	Required/Default	Constraints	Meaning

phone

E.164-compatible phone number. Stored as TEXT with a CHECK constraint.

Property	Type	Required/Default	Constraints	Meaning

slug

URL-safe slug: [a-z0-9-]+. Stored as TEXT; lowercased at write boundary. CHECK constraint enforces the character set.

Property	Type	Required/Default	Constraints	Meaning

markdown

Markdown-formatted text. Stored as TEXT with no format constraint; content is free-form.

Property	Type	Required/Default	Constraints	Meaning

html

HTML markup. Stored as TEXT. When sanitize is true, disallowed tags and attributes are stripped before storing.

Property	Type	Required/Default	Constraints	Meaning
sanitize	boolean	Optional (default: false)		When true, disallowed tags and attributes are stripped before storing.

percent

Numeric ratio or percentage. Stored as NUMERIC; scale determines the accepted range: ZeroToOne (default) or ZeroToHundred.

Property	Type	Required/Default	Constraints	Meaning
scale	enum (PercentScale)	Optional (default: "zeroToOne")		Accepted value range.

scale

Accepted value range. Defaults to ZeroToOne.

barcode

Barcode data in a specific format. Stored as TEXT with a format-specific CHECK constraint.

Property	Type	Required/Default	Constraints	Meaning
format	enum (BarcodeFormat)	Required		Barcode format; determines the CHECK pattern.

array

Ordered list of scalar values. Maps to element_type[] in PostgreSQL.

The element type must not itself be Array (no nesting), and some scalar kinds are not valid array elements — see element_type.

Constraints:

• max_items: write-boundary enforcement only; no PG-level constraint.
• unique_elements: duplicate values are rejected at the write boundary.

GIN-indexed by the compiler for containment (@>) query support.

Property	Type	Required/Default	Constraints	Meaning
element_type	ScalarType	Required		The type of each element.
max_items	integer (uint32)	Optional	minimum 0	Maximum number of elements.
unique_elements	boolean	Optional (default: false)		When true, duplicate elements are rejected at the write boundary.

element_type

The type of each element. Must not be Array (no nesting), and must not be json, timeInterval, inet, cidr, markdown, html, binary, or barcode — none of these are valid array element kinds. An invalid element type is rejected when the module is compiled.

max_items

Maximum number of elements. Write-boundary enforced, not a DB constraint. When set, must be greater than zero.

Composite Types

The kind of composite field, selecting its sub-values and its authoring shape.

Tagged by the kind property in JSON5. Three kinds are supported today:

kind	Sub-values
"money"	amount, currency
"dateRange"	startDate, endDate
"timestampRange"	startAt, endAt

compositeType: { kind: "money" }

A monetary amount with an optional fixed or free-choice currency.

Free mode (currency absent): every write must supply a currency code explicitly. Fixed mode (currency set): the currency is fixed by the field’s metadata; the declared currency is the default when a write omits currency, and a write that supplies a different currency code is rejected (422 INVALID_MONEY_CURRENCY). Both modes store the currency on the record — currency is never held in metadata alone.

amountFormat controls the external representation of amount (decimal string vs. minor-unit integer). The default is "decimal".

Property	Type	Required/Default	Constraints	Meaning
compositeType.currency	string	Optional		Fixed ISO 4217 currency code (e.g. "USD"), three uppercase ASCII characters.
compositeType.defaultCurrency	string	Optional		Studio pre-fill hint for free-currency mode: a suggested default currency code (three uppercase ASCII letters, ISO 4217, e.g. "USD") shown in the authoring UI.
compositeType.amountFormat	enum (AmountFormat)	Optional (default: "decimal")		Controls how the amount sub-value is represented on the wire.

compositeType.currency

Fixed ISO 4217 currency code (e.g. "USD"), three uppercase ASCII characters. When set, this field’s currency is fixed: every write must either omit currency (the fixed value applies) or supply the matching code. When absent, the field is free-currency: every write must supply a currency code.

compositeType.defaultCurrency

Studio pre-fill hint for free-currency mode: a suggested default currency code (three uppercase ASCII letters, ISO 4217, e.g. "USD") shown in the authoring UI. Has no effect in fixed mode and is not stored on the record.

compositeType.amountFormat

Controls how the amount sub-value is represented on the wire. "decimal" (default): amounts are decimal strings, e.g. "123.45". "minor": amounts are minor-unit integers, e.g. 12345.

compositeType: { kind: "dateRange" }

A date interval: a start date and an end date. Declared with compositeType: { kind: "dateRange" } — no further configuration. Wire shape: { "startDate": "2024-01-01", "endDate": "2024-06-30" }. The two dates are independently optional at the column level, but either both are set or both are absent; when both are set, startDate must not be later than endDate.

Property	Type	Required/Default	Constraints	Meaning

compositeType: { kind: "timestampRange" }

A timestamp interval: a start instant and an end instant. Declared with compositeType: { kind: "timestampRange" } — no further configuration. Wire shape: { "startAt": "2024-01-01T09:00:00Z", "endAt": "2024-01-01T17:00:00Z" }. The two timestamps are independently optional at the column level, but either both are set or both are absent; when both are set, startAt must not be later than endAt.

Property	Type	Required/Default	Constraints	Meaning

AmountFormat

Controls how a Money field’s amount sub-value is represented to and accepted from API callers.

The stored value is always minor units internally; amountFormat governs only the external (wire) representation. Set via compositeType.amountFormat on a money composite field.

Value	Write input	Read output	Example (USD)
"decimal"	decimal string, e.g. "123.45"	decimal string	100 minor units → "1.00"
"minor"	integer, e.g. 12345	integer	100 minor units → 100

The default is "decimal" — it matches how humans write monetary amounts (e.g. "19.99"). "minor" is for callers that already work in minor units and want to skip the decimal round-trip (e.g. accounting systems, payment processors). When amountFormat is absent from a metadata file, "decimal" applies.

Value	Status	Description
decimal		"decimal" — amounts are decimal strings, e.g. "123.45".
minor		"minor" — amounts are integers in the smallest indivisible currency unit, e.g. 12345 for $123.45.

BarcodeFormat

Barcode encoding format for a Barcode field.

Value	Status	Description
ean13		EAN-13: 13-digit numeric barcode (retail products).
ean8		EAN-8: 8-digit numeric barcode (smaller retail products).
upcA		UPC-A: 12-digit numeric barcode (North American retail).
isbn13		ISBN-13: 13-digit book identifier (EAN-13 subset).
isbn10		ISBN-10: 10-character book identifier (9 digits + check digit [0-9Xx]).
code128		Code 128: variable-length alphanumeric barcode (printable ASCII, [ -~]).
qr		QR code: arbitrary data payload.

EnumTransition

A state machine transition rule for an enum field.

Declares that a field value is allowed to change from from to any value in to. An empty to vec means the state is terminal (no transitions out).

Property	Type	Required/Default	Constraints	Meaning
from	string	Required		The source state this rule applies to.
to	array of string	Required		Allowed destination states.

to

Allowed destination states. Empty means terminal.

FloatSize

Floating-point storage width.

Selects between the two IEEE 754 approximate-float PG types. The default is Double (64-bit DOUBLE PRECISION). Use Single only when storage density outweighs the reduced precision.

Variant	PG type	Precision
Single	REAL	~6–7 significant digits
Double	DOUBLE PRECISION	~15–16 significant digits

Value	Status	Description
single		32-bit IEEE 754 → REAL.
double		64-bit IEEE 754 → DOUBLE PRECISION.

IntSize

Integer storage width.

Selects between the three signed-integer PG types. The default is Big (64-bit BIGINT), which is always safe; downsize only when storage density matters.

Variant	PG type	Range
Small	SMALLINT	−32 768 … 32 767
Regular	INTEGER	~±2.1 B
Big	BIGINT	~±9.2 × 10¹⁸

Value	Status	Description
small		16-bit signed integer → SMALLINT.
regular		32-bit signed integer → INTEGER.
big		64-bit signed integer → BIGINT.

IntervalFields

Restricts which time components a TimeInterval field stores and accepts.

Maps directly to the PostgreSQL INTERVAL <fields> qualifiers. When absent (the default), all components (years through microseconds) are accepted.

Determines whether the field’s precision parameter (fractional-seconds digits) is meaningful: only qualifiers that include a SECOND component (Second, DayToSecond, HourToSecond, MinuteToSecond) accept one.

Value	Status	Description
year		YEAR
month		MONTH
day		DAY
hour		HOUR
minute		MINUTE
second		SECOND
yearToMonth		YEAR TO MONTH — billing periods, tenures.
dayToHour		DAY TO HOUR
dayToMinute		DAY TO MINUTE
dayToSecond		DAY TO SECOND — SLA windows, durations.
hourToMinute		HOUR TO MINUTE
hourToSecond		HOUR TO SECOND
minuteToSecond		MINUTE TO SECOND

OnParentDelete

Controls what happens to child records when the referenced (parent) record is deleted.

Authored as one of three values in *_relationship.json5 metadata: "restrict", "setNull", "cascade". When not specified, the default is derived from the field’s required property: setNull when the reference is optional, restrict when it is required (a required reference cannot be cleared to null on parent delete). Declaring required: true together with onParentDelete: "setNull" is an invalid combination — the platform auto-corrects it to restrict and reports a warning diagnostic.

Value	Status	Description
restrict		Prevents deletion of the parent record while any child record still references it — the delete fails with a database error.
setNull		Clears the reference on all child records when the parent record is deleted; the children remain, with an empty reference.
cascade		Deletes all child records when the parent record is deleted.

PercentScale

Accepted value range for a Percent field.

Value	Status	Description
zeroToOne		Values must be in the range [0.0, 1.0] (ratio).
zeroToHundred		Values must be in the range [0.0, 100.0] (percentage points).

RollupFunction

The aggregation function a rollup field applies across its child records.

Set via the function property of a rollup field, using the lowercase wire values shown per variant below.

Value	Status	Description
count		"count" — the number of child records.
sum		"sum" — the sum of sourceField across child records.
min		"min" — the minimum value of sourceField across child records.
max		"max" — the maximum value of sourceField across child records.
avg		"avg" — the arithmetic mean of sourceField across child records.

Read-only (server-set)

These are computed or managed by the server. They appear in API responses but are rejected or ignored in request bodies — they do not appear in the property table above.

Property	Meaning
relatedRecords	The read-only inverse side of a managed lookup relationship — see RelatedRecordsFieldDefinition.

Example

{
  "fieldKey": "example",
  "fieldKind": "scalar",
  "fieldType": {
    "kind": "bool"
  },
  "label": "example"
}