CRUDUI PHP API

FieldSpec

in package

• Application

CRUDUI canonical FieldSpec model. SINGLE SOURCE OF TRUTH (SPEC §3).

Table of Contents

Constants

BEHAVIOR_SUB_KEYS  : array<int, string> = ['onchange', 'onclick', 'onload']

Sub-keys inside the `behavior` slot. Opaque client JS, passed through WITHOUT the expression engine (§4). `behavior: false` voids synthesized inheritance. An action label sits adjacent at behavior.{action}.label.

CLOSED_BUCKET_KEYS  : array<string, array<int, string>> = ['design' => self::DESIGN_SUB_KEYS, 'behavior'...

Closed buckets and the only keys each map form accepts; any other key is an unknown-key violation. Mirrors the JSON schema: design, behavior, multiple, lang and validate close their map form, and every design node (DESIGN_NODE_KEYS) closes to class/style. `options` and the `items` dynamic source stay open (see OPTIONS_IS_OPEN) and are checked only for forbidden and comment keys.

COMPOSITION_DIRECTIVES  : array<int, string> = ['$ref', '$patch']

Composition directives, in resolution order: $ref (base inheritance) is expanded first; an unresolved $ref cannot be loaded. $patch then mutates.

CONDITION_MAP_DEFAULT_KEY  : mixed = 'true'

The condition-map default key: the literal `true` expression (always truthy). R4 forbids convention sigils such as `_`. A condition map is an ordered map {expr: value, …}; keys are evaluated in declaration order and the first truthy expression's value wins; otherwise the `true` key's value (if present), else null. A single `?:` expression is the one-entry shorthand with identical semantics. Each key is an expressions.md §2 expression; the condition map is a thin wrapper over the same engine, not a separate parser. Evaluated value type — boolean | string | number | null — is decided by the call site.

DEPENDENCY_BUCKETS  : array<string, array{location: string, keys: list}> = ['type' => ['location' => 'options', 'keys' =>...

Dependency-bucket targets and where each one's dependent keys live. Keys here are CANONICAL CRUDUI names only — no alternative spellings, no magic tokens.

DESIGN_NODE_KEYS  : array<int, string> = ['class', 'style']

DESIGN_NODE_MAP  : array<int, string> = ['show', 'class', 'style', 'attributes', 'label...

Design appearance entries and the DOM node each targets (R8): show is the display condition (not a node); class/style hit the primary node; the named nodes carry .class/.style. Same surface as SPEC §design_node_map.

DESIGN_NODES  : array<int, string> = ['label', 'wrapper', 'group', 'prepend']

The design nodes (label/wrapper/group/prepend) and the closed key set of each node's map form.

DESIGN_SUB_KEYS  : array<int, string> = ['show', 'class', 'style', 'attributes', 'layou...

Sub-keys inside the `design` slot. show = display condition (NOT a node); class/style = the primary (input) node; attributes = the declared attributes of the control; layout = the layout a group gives its fields (not a node); label|wrapper|group|prepend carry .class/.style for that named node, and the wrapper also .attributes. Which node a class/style targets is revealed by the key (R8).

FORBIDDEN_META_KEYS  : array<int, string> = ['display_switch', 'display_target', 'if', 'whe...

Condition-only and retired meta keys that MUST NOT appear ANYWHERE in a CRUDUI field — at root, and also one level below any slot or bucket body. Open buckets stay open via propertyNames:{not:{enum:FORBIDDEN}}, so extension is allowed but every one of these is globally blocked. `x{key}` comment keys are not listed here; they are handled separately by the x-strip premise (see isCommentKey()).

OPTIONS_IS_OPEN  : mixed = true

The `options` slot is open (a type may introduce its own settings). The schema keeps it open with propertyNames:{not:{enum:FORBIDDEN}} rather than additionalProperties:true, so a type extends freely yet a forbidden meta key is still blocked one level below `options`.

OPTIONS_SUB_KEYS  : array<int, string> = ['keyword_min_length', 'max_tags', 'checkbox_la...

Sub-keys inside the `options` slot — the type-dependent slot (the type defines and validates them; the core stays uninvolved). Container chrome and type-dependent scripts/callbacks live here too. Removing the type also removes these options. A new widget does not change the core.

ROLE_CONTENT  : mixed = 'content'

Content: human-facing text. A plain string, a per-language LangMap {ko,en} (G3 content translation), or null/omitted for empty content — null is identical to absent and has no render/validate effect (SPEC §2 G3).

ROLE_FORM  : mixed = 'form'

Form declaration: buttons, action and dataLimits, honored on the form root only.

ROLE_IDENTITY  : mixed = 'identity'

Identity: field type. Defines and owns the `options` slot.

ROLE_MESSAGES  : mixed = 'messages'

Messages: error message overrides keyed by registered rule name.

ROLE_SLOT  : mixed = 'role_slot'

Role slot: validate/design/behavior/options (§3 role distribution).

ROLE_STRUCTURE  : mixed = 'structure'

Structure: $ref/$patch composition, child maps, dependency buckets.

ROLE_STRUCTURE_IDENTITY  : mixed = 'structure_identity'

Structure/identity: serialization name (explicit, semantic; R4).

SLOT_SUB_KEYS  : array<string, array<int, string>> = ['validate' => self::VALIDATE_SUB_KEYS, 'design...

Slot name => its recognized sub-keys.

SLOT_VALUE_FORMS  : array<int, string> = ['false', 'map', 'true']

The polymorphic slot value forms. A slot value MUST be one of these.

SLOTS  : array<int, string> = ['validate', 'design', 'behavior', 'options']

Role slot names (§3). Every slot is polymorphic: false | {} | true.

TOP_LEVEL  : array<string, string> = ['type' => self::ROLE_IDENTITY, 'name' => self:...

The closed set of top-level field keys, in declaration order, each with its role. A CRUDUI field accepts these keys and nothing else; the schema enforces this with additionalProperties:false plus the global propertyNames forbidden-key check.

VALIDATE_SUB_KEYS  : array<int, string> = ['required', 'email', 'minlength', 'maxlength',...

Sub-keys recognized inside the `validate` slot: the registered rule names, in the order of the validator's default messages. Each value may itself be an expression / condition map, so conditional validation needs no separate key (e.g. required: '.subscribe', email: true). Polymorphic slot (R: G1).

WRAPPER_NODE_KEYS  : array<int, string> = ['class', 'style', 'attributes']

The closed key set of the wrapper node: its appearance and the declared attributes of the node root.

Methods

isCommentKey()  : bool

Whether a key is an `x`-prefixed comment key. The meta-schema x-strips these before validating the canonical spec, so a canonical document must not carry one. Rejected by validation; recorded here for the reason.

isDependencyTarget()  : bool

Whether a key is a structural dependency-bucket target (type/multiple/lang/items).

isDynamicItemsSource()  : bool

Whether a decoded `items` value is a dynamic source descriptor: a non-empty string-keyed map whose keys are ALL dynamic-source keys (model/method/table/relations/api_server/items, the placeholder included).

isForbiddenMetaKey()  : bool

Whether a key is forbidden in a CRUDUI field at ANY depth.

isSlot()  : bool

Whether a key is a role slot (validate/design/behavior/options).

isTopLevelKey()  : bool

Whether a key is a recognized top-level field key.

isValidContent()  : bool

Whether a content value is a valid CRUDUI content shape (SPEC §2 G3): a plain string, a per-language LangMap (string-keyed array of string|null), or null (empty content — identical to absent, no render/validate effect). A LangMap slot may itself be null (empty label for that language).

isValidSlotValue()  : bool

Whether a slot value is a valid polymorphic form (false | array map | true).

isValueLabelItemsMap()  : bool

Whether an `items` value is a static value→label content map (SPEC §2 G3): a non-empty string-keyed array whose entry values are labels — a string, a LangMap array {ko,en}, or null (empty label). The option VALUE is the KEY (the membership target); the label is display-only and never a membership value, so a LangMap label and a null label have no membership effect.

itemsMembershipValues()  : array<int, mixed>

The membership values of an `items` source: for a static value→label map the KEYS (the option values — labels are display-only, SPEC §2 G3); for a static list the list itself; otherwise an empty list (a dynamic source has no static membership set). Mirrors the `in`-rule flatten across the four engines.

parse()  : array<string, mixed>

Parse a CRUDUI JSON document into an ordered associative array for the analysis API (validate/predicates). PHP associative arrays preserve insertion order, so condition-map and properties declaration order survives. Throws on malformed JSON.

parseTree()  : mixed

Parse a CRUDUI JSON document into an object tree (stdClass for objects, list for arrays). This keeps insertion order AND distinguishes the empty-map `{}` polymorphic form from an empty array `[]`. Throws on malformed JSON.

roleOf()  : string|null

Role of a top-level key, or null when the key is not top-level.

roundTrips()  : bool

Round-trip a canonical JSON document and report whether it is byte-stable.

serialize()  : string

Serialize a decoded CRUDUI field (associative-array form) back to canonical JSON, preserving key order. Empty associative arrays emit as `[]`; when the `{}` polymorphic form matters, use the *Tree round-trip path instead.

serializeTree()  : string

Serialize a CRUDUI object tree back to canonical JSON, preserving key order and the `{}` form. Round-trip invariant: serializeTree(parseTree(canonical)) === canonical for any already-canonical document.

slotValueForm()  : string|null

The polymorphic form name of a slot value, or null when invalid.

subKeysOf()  : array<int, string>|null

Recognized sub-keys for a slot, or null when the name is not a slot.

validate()  : array<int, string>

Deep-validate a decoded CRUDUI field. Returns the list of violations (empty = valid). Enforces: closed top-level key set, polymorphic slot value forms, dependency isolation (a bucket key only under its location), closed bucket key sets (CLOSED_BUCKET_KEYS: design, behavior, multiple, lang, validate and each design node's class/style), `messages` keys limited to the registered rule names, and the global forbidden-key check (root + one level below every slot and bucket; open options/items too). An `x`-prefixed comment key is a violation (x-strip is an upstream step).

guardInside()  : void

Append a violation for every forbidden, comment or (in a closed bucket) unknown key found one level below the given container. Open buckets ($allowed null) accept extension but never a forbidden or comment key.