entities.fields

Refused at apply

field.validation — Field ‘validation’ is not evaluated yet, so a value the expression forbids is accepted — the field is not constrained at all. Fix: Remove ‘validation’. Enforce the rule in a before-hook once #22 lands, or express it with a facet the API does validate — ‘maxLength’, ‘precision’/‘scale’, enum ‘values’ or a ‘format’.

field.default — Field ‘default’ is honoured as a literal, but not as a ‘$cel’ expression: a CEL default is evaluated against the caller’s context at insert time, which is the ‘computed’ machinery rather than a column default — so the value would be dropped and the field left null. Fix: Declare a literal default, which this build emits as a column DEFAULT, or remove ‘default’ and send the value explicitly on create (#113).

Guide: Entities and fields

The entities block spans these pages: entities · entities · fields · entities · computed & rollups · entities · rules · entities · hooks · entities · indexes.

Keys

entities.<name>.fields

Entity fields. The id field (uuid, PK) is always added by the framework and cannot be declared, nor can the columns the entity’s traits add (tenant_id, the audit columns, deleted_at). Key = field name (snake_case). The names order, limit, offset, after, select, or, and and not are reserved and are rejected when the descriptor is applied: the generated Data API’s query string gives each of them a meaning (?limit=10, ?or=(...), ?not.color=eq.red), so a request could not tell a filter on such a field from the parameter itself. The pattern above cannot express that exclusion, which is why it is stated here rather than validated by the schema — rename the field.

• Type: map of object
• Required: yes
• Names match ^[a-z][a-z0-9_]{0,62}$.

entities.<name>.fields.<name>.type

The field’s storage and validation type. decimal needs precision and scale; enum needs values; ref needs entity.

• Type: string
• Required: yes
• Values: "string", "text", "integer", "decimal", "boolean", "date", "datetime", "uuid", "json", "enum", "ref"

entities.<name>.fields.<name>.description

Human-readable description of the field (surfaced to agents and in the admin UI).

• Type: string
• Required: no

entities.<name>.fields.<name>.renamedFrom

Previous name of this field: declares a rename so apply preserves data instead of drop+add.

• Type: string
• Required: no
• Pattern: ^[a-z][a-z0-9_-]{0,62}$

entities.<name>.fields.<name>.required

Whether the field must be present (NOT NULL).

• Type: boolean
• Required: no
• Default: false

entities.<name>.fields.<name>.unique

Whether values must be unique across the entity.

• Type: boolean
• Required: no
• Default: false

entities.<name>.fields.<name>.nullable

Explicitly allow NULL; the default is derived from required.

• Type: boolean
• Required: no

entities.<name>.fields.<name>.default

Default value: a JSON literal, or a tagged expression {“$cel”: ”…”} (e.g. {“$cel”: “now()”}, {“$cel”: “gen_random_uuid()”}, {“$cel”: “@user.id”}). The $cel default context includes @user/@tenant and is evaluated at insert time.

• Type: any
• Required: no
• Not allowed together with computed.
• Not allowed together with rollup.

entities.<name>.fields.<name>.default.$cel

A CEL expression whose result becomes the value, in place of a JSON literal (e.g. now(), @user.id).

• Type: string
• Required: yes

entities.<name>.fields.<name>.maxLength

type=string only. Counted in Unicode code points — the unit JSON Schema’s own maxLength keyword and PostgreSQL’s varchar(n) both use — not UTF-16 code units, so a character outside the Basic Multilingual Plane counts once. Both shipped drivers honour that bound; a dialect whose column counts UTF-16 units owes its own answer.

• Type: integer
• Required: no
• Allowed only when type is "string".

entities.<name>.fields.<name>.precision

type=decimal only (required).

• Type: integer
• Required: no
• Required when type is "decimal".
• Allowed only when type is "decimal".

entities.<name>.fields.<name>.scale

type=decimal only (required).

• Type: integer
• Required: no
• Required when type is "decimal".
• Allowed only when type is "decimal".

entities.<name>.fields.<name>.values

type=enum only.

• Type: array of string
• Required: no
• Required when type is "enum".
• Allowed only when type is "enum".

entities.<name>.fields.<name>.entity

type=ref only — target entity (FK to its id). May target the reserved users entity, or a dynamic/runtime entity (late-bound).

• Type: string
• Required: no
• Pattern: ^[a-z][a-z0-9_-]{0,62}$
• Required when type is "ref".
• Allowed only when type is "ref".

entities.<name>.fields.<name>.onDelete

type=ref only. Registry-level semantics: enforced as a DB FK for physical targets, app-enforced for dynamic targets.

• Type: string
• Required: no
• Values: "restrict", "cascade", "setNull"
• Default: "restrict"
• Allowed only when type is "ref".

entities.<name>.fields.<name>.format

type=string only — validation format: a built-in (email, uri, phone) or the name of a format declared in the top-level formats. An unknown name is caught fail-fast at apply (like a ref to a missing entity), not by this schema.

• Type: string
• Required: no
• Allowed only when type is "string".

entities.<name>.fields.<name>.validation

Optional CEL value validation (context: value, new).

• Type: string
• Required: no

entities.<name>.fields.<name>.index

Create an index (for dynamic entities = generated column + index over the JSON path).

• Type: boolean
• Required: no
• Default: false

entities.<name>.fields.<name>.hidden

Field is never returned in API responses. true = always hidden; a CEL expression over @user makes visibility conditional (per-role masking, e.g. ”!(‘compliance’ in @user.roles)”).

• Type: boolean or string
• Required: no

entities.<name>.fields.<name>.readOnly

Field cannot be modified via the API. true = always read-only; a CEL expression over @user makes it conditional.

• Type: boolean or string
• Required: no