Skip to content

Designing doctypes

A doctype is one record type inside a domain, such as crm.Company or hr.Employee. You declare it once, and Facet validates every write against it. The definition holds the fields, the actions users can run, the owned children, and the rules that name and search each document.

You add a doctype to a draft domain, or you rework an existing one. Work in a draft domain while you design; publish when the model holds (see Domains, drafts and domain editors).

  • Edit rights. You need the right to edit doctypes in the target domain. The editor role holds it for the domains the account edits.
  • A domain to live in. The domain must exist before Facet accepts a doctype in it.
  • A free action name. Reserved action names (validate, create, update) are not available; they name lifecycle hooks.

Give each field a name and a type, then add the constraints the data needs. Field names use lower_snake_case or camelCase. See Field types (guide) for the common types, and Field types (reference) for the full table.

Part Purpose
label The name the interface shows, for example Company. Falls back to the doctype name.
icon A Lucide icon name in kebab-case, for example building-2.
display_name A Jinja2 template that names each document, for example {{ name }}.
search A Jinja2 template for the search text. A doctype without one stays out of cross-doctype search.

A doctype is exactly one of two things:

Kind Declaration Meaning
Aggregate root aggregate_root: true The record users create and delete. It is the unit of locking and of access control.
Owned child aggregate_root: false plus member_of A part of a parent document. See Parent/child composition.

4. Add actions, children, and an identifier

Section titled “4. Add actions, children, and an identifier”

Add actions when users need typed operations beyond edits (see Named actions). Add children for owned parts. Add an identifier block when documents need readable numbers (see Identifiers and unique constraints).

Submit the definition while your draft domain is open. Facet validates the schema, compiles the script, and returns the issues. On a live domain, every later change to the data shape needs a version bump (see Evolving a schema).

Every write then follows the same path: Facet validates the document, appends one log row, updates one projection, and publishes one event.

App or user App or user

The definition below declares a crm.Company root with four fields. Send it to the doctype endpoint of your instance.

{
"domain": "crm",
"doctype": "Company",
"label": "Company",
"icon": "building-2",
"aggregate_root": true,
"schema_version": 1,
"display_name": "{{ name }}",
"search": "{{ name }} {{ industry }}",
"fields": {
"name": { "type": "string", "required": true, "filters": ["equality", "text_search"] },
"industry": { "type": "string", "filters": ["equality"] },
"status": {
"type": "enum",
"default": "lead",
"filters": ["equality"],
"values": [
{ "key": "lead", "label": "Lead" },
{ "key": "active", "label": "Active" }
]
},
"website": { "type": "url" }
}
}
Terminal window
curl -k -X POST "https://facet.localhost:3443/Api/core/DocType" \
-H "Authorization: Bearer $FACET_API_KEY" \
-H "Content-Type: application/json" \
-d @company.json

-k skips the certificate check of the local development address. A second submit of the same definition answers 409; updates go through the doctype editor instead.

The create answers 422 Domain 'crm' does not exist

Section titled “The create answers 422 Domain 'crm' does not exist”

Create the domain first. A doctype needs a live or draft domain to live in.

A definition accepts only known keys, and every field entry checks its own keys. The message names the key and its location. Most often a constraint is misspelled, for example reqired instead of required.

The icon value must match a Lucide icon name in kebab-case. Facet falls back to a plain mark when the name is unknown.