Doctype definition schema
Generated from
src/doctypebymake gen-docs-doctype-schema. Do not edit this file by hand.
Use this page to check the keys a doctype definition accepts.
A doctype definition is the JSON document that registers a document type. The parser under src/doctype/ accepts exactly the keys below and rejects every other key with 422. Definitions may also be authored in YAML; the loader converts it to the same JSON grammar.
Top-level keys
Section titled “Top-level keys”| Key | Type | Required | Purpose |
|---|---|---|---|
doctype |
string | yes | CamelCase type name, e.g. WorkOrder. |
domain |
string | yes | Owning domain. Lowercase with dashes; a draft domain may carry the _ prefix. |
schema_version |
integer | no | Breaking-change version, minimum 1. Drives lazy migration on read. Defaults to 1. |
aggregate_root |
boolean | no | True for an aggregate root. Defaults to false. |
member_of |
string | no | CamelCase parent doctype when this type is an owned child. |
description |
string | no | What the doctype represents. |
label |
string | no | Display label the interface shows. Falls back to the doctype name. |
icon |
string | no | Lucide icon identifier. Falls back to the default diamond mark. |
color |
string | no | CSS hex accent color, e.g. #1565C0. |
plural_label |
string | no | Human plural label for consent previews and client snippets. |
sensitive |
boolean | no | Highlights grants on this doctype in the permissions editor and consent preview. |
nav_visible |
boolean | no | Shows an owned child in the sidebar as a top-level entry. |
fields |
object | no | Field definitions keyed by field name. |
actions |
object | no | Named actions keyed by action name. Each maps to a Lua export function. |
children |
object | no | Composition children keyed by relationship name. Stored as separate projection rows. |
sidecar |
boolean | no | True for a system-managed attachment doctype in the core domain. |
sidecars |
object | no | Sidecar attachments on a host doctype, keyed by route segment. |
surface |
string | no | Custom-surface id on a sidecar doctype. The frontend resolves it through its surface registry. |
search |
string | no | Jinja2 template rendered into the trigram-search corpus at mutation time. |
display_name |
string | no | Jinja2 template rendered into the projection display label at mutation time. |
migrations |
object | no | Source schema version mapped to a Lua migration function name. |
script |
string | no | Lua script source with the lifecycle hooks, actions, and migrations. |
scopes |
object | no | Named predicates over the doctype’s own fields. Permissions reference them as $name. |
identifier |
object | no | Sequential identifier configuration. When absent, document ids are ULIDs. |
JSON Schema
Section titled “JSON Schema”The schema expresses the key sets, the required keys, the patterns, and the enums the code enforces. The rules the schema cannot express follow below.
{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "Facet doctype definition", "type": "object", "additionalProperties": false, "required": [ "doctype", "domain" ], "properties": { "doctype": { "type": "string", "pattern": "^[A-Z][a-zA-Z0-9]*$" }, "domain": { "type": "string", "pattern": "^[a-z_][a-z0-9_\\-]*$" }, "schema_version": { "type": "integer", "minimum": 1 }, "aggregate_root": { "type": "boolean" }, "member_of": { "type": "string", "pattern": "^[A-Z][a-zA-Z0-9]*$" }, "description": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string" }, "color": { "type": "string" }, "plural_label": { "type": "string" }, "sensitive": { "type": "boolean" }, "nav_visible": { "type": "boolean" }, "fields": { "type": "object", "additionalProperties": { "$ref": "#/$defs/field" } }, "actions": { "type": "object", "propertyNames": { "not": { "enum": [ "create", "delete", "history", "migrate", "rollback", "snapshot", "update", "validate" ] } }, "additionalProperties": { "$ref": "#/$defs/action" } }, "children": { "type": "object", "additionalProperties": { "$ref": "#/$defs/childrenEntry" } }, "sidecar": { "type": "boolean" }, "sidecars": { "type": "object", "additionalProperties": { "$ref": "#/$defs/sidecarRef" } }, "surface": { "type": "string" }, "search": { "type": "string" }, "display_name": { "type": "string" }, "migrations": { "type": "object", "additionalProperties": { "type": "string" } }, "script": { "type": "string" }, "scopes": { "type": "object", "additionalProperties": { "$ref": "#/$defs/scope" } }, "identifier": { "$ref": "#/$defs/identifier" } }, "$defs": { "field": { "type": "object", "additionalProperties": false, "properties": { "type": { "enum": [ "any", "array", "boolean", "color", "data", "date", "dateperiod", "datetime", "dictionary", "duration", "enum", "file", "integer", "longtext", "money", "object", "period", "phone", "reference", "secret", "string", "url" ] }, "values": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "$ref": "#/$defs/enumValue" }, { "type": "string", "minLength": 1 } ] } }, { "$ref": "#/$defs/field" } ] }, "items": { "$ref": "#/$defs/field" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/$defs/field" } }, "doctype": { "type": "string" }, "required": { "type": "boolean" }, "unique": { "type": "boolean" }, "default": {}, "min": { "type": "integer" }, "max": { "type": "integer" }, "collection": { "type": "boolean" }, "compute": { "type": "string" }, "compute_when": { "type": "array", "items": { "type": "string" } }, "replicate": { "$ref": "#/$defs/replicate" }, "on_source_delete": { "enum": [ "keep", "unset" ] }, "accept": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" }, "description": { "type": "string" }, "write_only": { "type": "boolean" }, "read_only": { "type": "boolean" }, "owned": { "type": "boolean" }, "filter": { "type": "object" }, "dangling": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "pattern": { "type": "string" }, "pattern_flags": { "type": "string" }, "mode": { "type": "string" }, "ttl_seconds": { "type": "integer" }, "filters": { "type": "array", "items": { "enum": [ "comparison", "currency", "equality", "interval", "membership", "text_search" ] } }, "currency": { "type": "string" }, "precision": { "type": "integer" }, "operators": { "type": "array", "items": { "type": "string" } } } }, "enumValue": { "type": "object", "additionalProperties": false, "required": [ "key" ], "properties": { "key": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "color": { "type": "string" } } }, "action": { "type": "object", "additionalProperties": false, "properties": { "args": { "type": "object", "additionalProperties": { "$ref": "#/$defs/actionArg" } }, "event_name": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "description": { "type": "string" }, "states": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } } } }, "actionArg": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "enum": [ "any", "array", "boolean", "color", "data", "date", "dateperiod", "datetime", "dictionary", "duration", "enum", "file", "integer", "longtext", "money", "object", "period", "phone", "reference", "secret", "string", "url" ] }, "required": { "type": "boolean" }, "default": {}, "values": { "type": "array", "items": { "type": "string" } }, "min": { "type": "integer" }, "max": { "type": "integer" }, "doctype": { "type": "string" }, "collection": { "type": "boolean" } } }, "childrenEntry": { "type": "object", "additionalProperties": false, "required": [ "doctype" ], "properties": { "doctype": { "type": "string", "pattern": "^[A-Z][a-zA-Z0-9]*$" }, "collection": { "type": "boolean" }, "description": { "type": "string" } } }, "sidecarRef": { "type": "object", "additionalProperties": false, "required": [ "doctype" ], "properties": { "doctype": { "type": "string", "pattern": "\\." }, "column": { "type": "string" }, "order": { "type": "integer" }, "label": { "type": "string" } } }, "scope": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string" }, "where": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } } }, "replicate": { "type": "object", "additionalProperties": false, "required": [ "field", "via" ], "properties": { "via": { "type": "string", "minLength": 1 }, "field": { "type": "string", "minLength": 1 } } }, "identifier": { "type": "object", "additionalProperties": false, "required": [ "template" ], "properties": { "template": { "type": "string", "minLength": 1 }, "genonly": { "type": "boolean" } } } }}Rules the schema cannot express
Section titled “Rules the schema cannot express”| Rule | What the validator enforces | Code |
|---|---|---|
| Reserved action names | An action cannot use one of the reserved names: create, delete, history, migrate, rollback, snapshot, update, validate. | doctype_definition.cr, validation.cr |
| Action and child name collision | An action name cannot equal a child relationship name, in either direction. | validation.cr (validate_actions) |
| Actions and migrations need a script | Declared actions or migrations without a script are rejected. | validation.cr (validate_script) |
| Aggregation pair | aggregate_root: true contradicts member_of. A doctype is a root or a member, not both. | validation.cr (validate_aggregation) |
| compute keys only on data | compute and compute_when are rejected on every field type except data (secret fields get their own message). | validation.cr (validate_compute_field_type) |
| compute_when triggers | Each trigger must name a field of the doctype or a child relationship. | validation.cr (validate_compute_when) |
| Replicated field consistency | on_source_delete applies only to a field that carries replicate; its value must be keep or unset; a replica cannot be computed, required, or unique; the via field must exist and must be a reference field. | validation.cr (validate_replicate_schema) |
| Secret placement | A secret leaf is allowed at top level and inside object properties only, never inside arrays or dictionaries. A secret root must not appear in the search or display_name templates. Secret cannot be an action argument type. | validation.cr (validate_secret_fields) |
| Template roots | Every search and display_name root variable must be a declared field or a reserved variable: content always, display_name in search templates only. A display_name template must not reference the display_name column. | validation.cr (validate_template) |
| Reserved field names | A field cannot use one of the reserved names: created_at, deleted_at, display_name, id, links, parent_id, search, state, updated_at, version. | validation.cr (RESERVED_FIELD_NAMES) |
| Field name shape | A field name is lower_case_with_underscores or camelCase. | validation.cr (validate_field_names) |
| read_only and write_only | The two flags are mutually exclusive on one field. | validation.cr (validate_field_names) |
| Filter capability matrix | A declared filter capability must be valid for the field type: equality, comparison, text_search, interval, membership, and currency each cover their own type set. | validation.cr (validate_field_filters), filter_capability.cr |
| Sidecar shape | A sidecar doctype lives in the core domain and carries a target reference field that is required, read_only, and has no default. surface is only meaningful with sidecar: true and must be a lowercase identifier. | validation.cr (validate_sidecar, validate_sidecar_surface) |
| Sidecar segments | A sidecars segment is a lowercase identifier, does not collide with a children key, and names a non-empty column. | validation.cr (validate_sidecars_keys) |
| Children targets | A children doctype is a bare CamelCase name in the same domain. A domain prefix is rejected. | validation.cr (validate_children) |
| Draft versus live domains | The _-prefixed domain form is valid only in draft domains. A live domain cannot start with a digit or carry _. |
validation.cr (validate_domain_name, validate_domain_name_draft) |
| Migration gaps | On update, every version below schema_version needs a migrations entry whose function name is non-empty; version keys are integers below schema_version. | validation.cr (validate_migrations) |
| identifier template | identifier.template must compile through the sequence generator: valid variables, at least one # group, group width within limits. | validation.cr (validate_identifier) |
| Empty text is absent | An optional text key parses an empty string as absent. No consumer handles “” beside nil. | doctype_definition.cr (optional_string) |
| Closed key sets | Every object level rejects unknown keys with 422. The sets are the KNOWN_KEYS constants this page is generated from. | doctype_definition.cr, field_definition.cr, action_definition.cr, children_definition.cr, sidecar_ref.cr, named_scope.cr, replicate_config.cr |
| Derived operators member | operators on a field is accepted on read and re-derived from filters. It is never stored. | field_definition.cr |
Related
Section titled “Related”- Designing doctypes — how to model a domain with these keys.
- Evolving a schema — schema versions and migrations.
- Parent and child composition — the children and member_of pair.