Component Settings Schema

A component's behaviour is fully described by its Settings document. This page is the reference for the raw JSON shape of that document — useful when building integrations, writing toolkit scripts, or constructing components programmatically.

---

Settings

The top-level container for all component configuration.

Field	Type	Required	Description
version	string	No	Semver string of this settings snapshot
appearance	Appearance	No	Custom UI entrypoints
list	List	No	List view configuration
fields	SettingsField[]	Yes	All fields defined for this component
model	Model	No	Workflow events and unique index rules
presets	Preset[]	No	Saved list-view filter configurations
templates	object[]	No	Raw record templates
templates_dist	TemplatesDist	No	Compiled template distribution
config	object	No	Arbitrary key/value component config
functions	Function[]	No	Named JavaScript expression functions
extensions	Extension[]	No	Installed extensions
policies	Policy[]	No	Access control policies
idl	ComponentIDL	No	Type contracts per schema — see IDL

{
  "version": "1.0.0",
  "fields": [],
  "model": { "events": [], "unique_indexes_combinations": [] },
  "functions": [],
  "extensions": [],
  "policies": []
}

---

Appearance

Controls which custom UI component is rendered for each view.

Field	Type	Description
list_entrypoint	string	Custom component name for the list view
create_entrypoint	string	Custom component name for the create form
edit_entrypoint	string	Custom component name for the edit form

---

List

Configures the default list view.

Field	Type	Description
quick_actions	boolean	Show inline action buttons in each row
fields	ListField[]	Ordered list of columns to display

ListField

Field	Type	Description
key	string	Field key
label	object	Localised label
sortable	boolean	Allow column sorting
filterable	boolean	Allow column filtering
sort_direction	string	Default sort — "asc" or "desc"
formatter	string	Display formatter identifier
variant	string	Visual variant hint

---

Model

Holds workflow definitions and unique index constraints.

Field	Type	Description
events	Node[]	Workflow nodes — see Workflow Schema
unique_indexes_combinations	UniqueIndexCombination[]	Multi-field unique constraints

UniqueIndexCombination

Field	Type	Required	Description
schema	string	No	Schema this index applies to — defaults to "default"
fields	string[]	Yes	Field keys that must be unique together

{
  "unique_indexes_combinations": [
    { "fields": ["email"] },
    { "schema": "premium", "fields": ["email", "tier"] }
  ]
}

---

SettingsField

Describes a single field on a component record.

Field	Type	Required	Description
key	string	Yes	Unique identifier used as the data key
name	string	No	Internal system name
label	object	No	Localised display label
description	object	No	Localised help text
type	string	Yes	Sub-type within the module — see Field Modules
module	string	Yes	Input widget category — see Field Modules
group	string	No	UI group/section name
sort_order	number	No	Display order within the form
visible	boolean	No	Whether the field is shown in the UI
protected	boolean	No	Whether the field is write-protected
schema	string	No	Schema this field belongs to — defaults to "default"
context	Context[]	No	Static key/value pairs injected into expression context
constraints	FieldConstraints	No	Validation and UI constraint rules
relation	Relation	No	Foreign component reference settings
permissions	string[]	No	Additional permission identifiers
provided_template	boolean	No	Whether this field renders via a provided template
provided_template_component	string	No	Component name providing the template
component_template	string	No	Template name within the component
template	string	No	Raw template string

Relation

Field	Type	Description
foreign	string	Name of the foreign component
foreign_uuid	string \| null	UUID of the foreign component
key	string[]	Field keys from the foreign component to include
type	string	Relation type — "one" or "many"

---

Field Modules

The module determines the input widget; type selects the variant within that module.

module	type values	Description
input	text, text_i18n, number, date, image, email, password, file	Single-value text inputs
image	carousel	Image carousel
text	default, editor	Text area / rich-text editor
select	text, number, image, relation, external	Dropdown / multi-select
radio	text, number	Radio button group
checkbox	text, number, bool	Checkbox(es)
table	default, custom	Inline table of sub-records
picker	date, daterange, datetime, time	Date/time pickers
fieldset	default	Group of fields rendered together
data	json	Raw JSON editor

---

FieldConstraints

Validation and UI behaviour rules for a field.

Field	Type	Description
required	boolean	Field must have a value
unique	boolean	Value must be unique across all records
placeholder	string	Input placeholder text
default	string	Default value expression
length.min	number \| null	Minimum string/array length
length.max	number \| null	Maximum string/array length
not_allowed_words	string	Comma-separated blocked words
regex	string	Validation regular expression
display_condition	string	JS expression — field is shown only when truthy
custom_data	object	Arbitrary module-specific data

constraints.date

For picker module fields.

Field	Type	Description
pattern	string	Display format pattern
disable_past_dates	boolean	Prevent selecting past dates
disable_future_dates	boolean	Prevent selecting future dates
disabled_dates.dates	string[]	Specific disabled dates
disabled_dates.days	number[]	Disabled weekday numbers (0 = Sunday)
highlighted_dates	object	Same structure as disabled_dates

constraints.selectables

For select and radio module fields.

Field	Type	Description
items	any[]	Explicit list of allowed values
multiple	boolean	Allow selecting multiple values
range.from	number	Generate items from this number
range.to	number	Generate items up to this number
custom	boolean	Allow values not in items

constraints.table

For table module fields.

Field	Type	Description
search	boolean	Show search box above the table
per_page	number	Default rows per page
save_on_create	boolean	Persist rows immediately on record create
fields	SettingsField[]	Column definitions — same shape as top-level fields

constraints.relation

For select relation type fields.

Field	Type	Description
label	string	Field key from the foreign component used as display label
searchOn	string[]	Field keys to search when filtering the relation dropdown

---

Function

Named JavaScript expression callable from workflows and other expressions.

Field	Type	Required	Description
name	string	Yes	Function identifier
expr	string	Yes	JavaScript expression body

{
  "functions": [
    { "name": "fullName", "expr": "data.first_name + ' ' + data.last_name" }
  ]
}

---

Preset

A saved list-view filter configuration.

Field	Type	Description
name	string	Display name of the preset
roles	string[]	Roles that can see this preset
context.filters	Filters	Filter values applied when preset is active
context.default	boolean	Auto-apply this preset on load
context.locked	boolean	Prevent users from clearing this preset
context.expr	string	Dynamic filter expression

Filters

Field	Type	Description
filter	string	Free-text search string
filterOn	string[]	Fields to search within
dateField	string	Field used for date range filtering
dateFrom	string	Start of date range
dateTo	string	End of date range
$adv	object	Advanced filter map — keyed by field key

---

Extension

An installed extension adds fields, functions, and workflows to a component without modifying the base settings.

Field	Type	Description
name	string	Extension identifier
is_active	boolean	Whether the extension is enabled
version	string	Installed version string
installed_by	string	UUID of the component that installed this extension
installed_at	string	ISO 8601 install timestamp
fields	SettingsField[]	Additional fields contributed by this extension
functions	Function[]	Additional functions
workflows	Node[]	Additional workflow nodes — see Workflow Schema
config	object	Extension-specific configuration
idl	ComponentIDL	Extension-scoped type contracts — see IDL

Extension functions are called using dot notation: extensionName.functionName.

---

Policy

Access control rule applied to the component.

Field	Type	Required	Description
name	string	Yes	Policy identifier
type	string	Yes	Policy category — currently only "field_access"
description	string	No	Human-readable explanation
enabled	boolean	Yes	Whether the policy is active
priority	number	No	Higher priority wins on conflict (default: 0)
config	object	Yes	Type-specific configuration — see Policies

---

Complete Example

{
  "version": "1.0.0",
  "appearance": {
    "list_entrypoint": "",
    "create_entrypoint": "",
    "edit_entrypoint": ""
  },
  "fields": [
    {
      "key": "name",
      "label": { "locales": { "en_US": "Name" } },
      "module": "input",
      "type": "text",
      "visible": true,
      "constraints": { "required": true }
    },
    {
      "key": "status",
      "label": { "locales": { "en_US": "Status" } },
      "module": "select",
      "type": "text",
      "visible": true,
      "constraints": {
        "selectables": { "items": ["active", "inactive"] }
      }
    },
    {
      "key": "assigned_to",
      "label": { "locales": { "en_US": "Assigned To" } },
      "module": "select",
      "type": "relation",
      "visible": true,
      "relation": {
        "foreign": "users",
        "key": ["name", "email"],
        "type": "one"
      },
      "constraints": {
        "relation": { "label": "name", "searchOn": ["name", "email"] }
      }
    }
  ],
  "model": {
    "events": [
      {
        "id": 1,
        "name": "Create",
        "type": "event",
        "action": "event",
        "data": {},
        "connections": [],
        "parallel": false,
        "paused": false
      }
    ],
    "unique_indexes_combinations": [
      { "fields": ["name"] }
    ]
  },
  "functions": [
    { "name": "displayName", "expr": "data.name.toUpperCase()" }
  ],
  "policies": [],
  "extensions": []
}