Schema reference

Every node in a schema is one of four kinds. This page documents each one and all of its properties.

Each property is tagged with its concern:

• _data — shapes the control structure, the value, or its validation.

• _ui — shapes only the rendered presentation.

Tip

A property tagged _data changes what form.getRawValue() returns or whether the form is valid. A property tagged _ui never changes the value — only how it looks.

leaf — a single field

A scalar field. Builds a FormControl.

{ kind: 'leaf', type: 'string', name: 'firstName', label: 'First name', required: true }

Property	Type	Concern	Description
kind	'leaf'	data	Node discriminant. Required.
name	string	data	Field identity. Must equal this node’s key in the parent children map. Required.
type	'string' | 'number' | 'boolean' | 'enum'	data	The value type (see table below). Required.
required	true	data	Adds Validators.required. Omit for optional fields.
default	matches type	data	Initial value when no value is supplied to buildFormFromSchema.
label	string	ui	Field label. Falls back to name when omitted.
enum	(string | number)[]	data	Required when type: 'enum'. The allowed values; also enforced by a validator.
enumLabel	string[]	ui	Display labels for the enum options, positionally aligned with enum.

type maps to a control value type:

type	Control value	Rendered as
'string'	FormControl<string>	text input
'number'	FormControl<number>	number input
'boolean'	FormControl<boolean>	checkbox
'enum'	FormControl<string | number>	select

enumLabel alignment

enumLabel is a parallel array — enumLabel[i] labels enum[i]. Keep the two arrays the same length and order. If you reorder enum, reorder enumLabel to match.

leafList — a list of scalars

A repeatable scalar field. Builds a FormArray<FormControl>.

{ kind: 'leafList', type: 'string', name: 'tags', label: 'Tags' }

Property	Type	Concern	Description
kind	'leafList'	data	Node discriminant. Required.
name	string	data	Identity; must equal the children key. Required.
type	'string' | 'number' | 'boolean' | 'enum'	data	Element value type. Required.
default	array of the element type	data	Initial items when no value is supplied.
minItems	number	data	Minimum item count.
maxItems	number	data	Maximum item count.
label	string	ui	List label. Falls back to name.

nodeGroup — a nested object

A group of fields. Builds a nested FormGroup. The root of every schema is a nodeGroup.

{
  kind: 'nodeGroup',
  name: 'address',
  label: 'Address',
  children: {
    street: { kind: 'leaf', type: 'string', name: 'street' },
    city:   { kind: 'leaf', type: 'string', name: 'city' },
  },
}

Property	Type	Concern	Description
kind	'nodeGroup'	data	Node discriminant. Required.
name	string	data	Identity; must equal the children key (except at the root). Required.
children	Record<string, NodeType>	data	The child nodes, keyed by field name. Required.
label	string	ui	Group heading (card or panel title). Falls back to name.
root	boolean	ui	Renders the group as the top-level accordion layout instead of a card. Set on the schema root.
presence	boolean	data	Makes the group optional: rendered with an on/off toggle and absent from the form value until enabled. Its control is removed when off and rebuilt when on.
appearance	Appearance	ui	Layout options (see below).

Appearance

Property	Type	Concern	Description
flatten	boolean	ui	Render the group’s fields inline, without a surrounding card.
noBorder	boolean	ui	Render the group card without its border.

nodeGroupList — a list of objects

A repeatable group. Builds a FormArray<FormGroup>. Each item is an instance of the type group.

{
  kind: 'nodeGroupList',
  name: 'contacts',
  label: 'Contacts',
  minItems: 1,
  type: {
    kind: 'nodeGroup',
    name: 'contact',
    children: {
      email:   { kind: 'leaf', type: 'string', name: 'email' },
      primary: { kind: 'leaf', type: 'boolean', name: 'primary' },
    },
  },
}

Property	Type	Concern	Description
kind	'nodeGroupList'	data	Node discriminant. Required.
name	string	data	Identity; must equal the children key. Required.
type	NodeGroup	data	The group schema each item conforms to. Required.
minItems	number	data	Minimum item count; the last item cannot be removed below this.
maxItems	number	data	Maximum item count.
label	string	ui	List label. Falls back to name.

choice — a discriminated selection

The user picks one case; only that case’s fields are present. Rendered as a case selector plus the selected case’s fields.

{
  kind: 'choice',
  name: 'transport',
  cases: {
    tcp: {
      port: { kind: 'leaf', type: 'number', name: 'port' },
      tls:  { kind: 'leaf', type: 'boolean', name: 'tls' },
    },
    udp: {
      port: { kind: 'leaf', type: 'number', name: 'port' },
    },
  },
}

Property	Type	Concern	Description
kind	'choice'	data	Node discriminant. Required.
name	string	data	Identity; must equal the children key. Required.
cases	Record<string, Record<string, NodeType>>	data	Each case name → that case’s fields. Required.
default	string	data	Case selected when none is chosen.
mandatory	boolean	data	Whether a case must be selected.
label	string	ui	Selector label. Falls back to name.

In the form value a choice is { __case: <caseName>, ...that case's fields }.

Current limitations

The library is at an early version (0.1.x). A few properties are declared on the model but not yet fully wired:

• minItems / maxItems currently gate the remove control on nodeGroupList, but are not yet enforced as FormArray validators, and are not yet applied to leafList. Treat them as UI hints for now, and validate cardinality yourself if it must be enforced.

• description and subType exist on the types but are not rendered. Avoid relying on them.

These are tracked for a future release; the source repository is the place to follow progress.