Schema files

Content types are YAML files under config/schema/, one type per file (a type may also be split across several files, and a site may add its own under config/sites/<key>/schema/). Every place that declares fields uses the same field grammar: types, shared field groups, blocks, and the CRM’s custom fields. Content modelling explains types and fields; this page lists every key.

key: walk
label: { en-GB: Walk }
plural: { en-GB: Walks }
icon: footprints
searchable: true
fields:
  - name: title
    type: text
    required: true
  - name: slug
    type: slug
    required: true
  - name: distance
    type: number
    index: true
  - name: route
    type: geo
  - use: contact
groups:
  - key: details
    label: { en-GB: Details }
    fields: [distance, route]

Every type, field, group and block carries a stable id. Leave it out when you write the file and run engine-dmo check --fix, which writes each missing id in place and keeps your comments; check without --fix reports a missing id as an error. engine-dmo dev type add, dev field add, dev field set, dev field rename and dev group add change these files safely and write ids; engine-dmo describe type <key> shows a type as the engine resolved it; engine-dmo describe fieldtypes lists every field type with its parameters.

The type file

Key	Type	Default	Meaning
`key`	string	Required	The type’s key. Lower case; used in routes, templates and the API
`id`	string	Written for you	The type’s stable id. Written by `engine-dmo check --fix`; never write or change it by hand
`extends`	string		Instead of `key`: a core type (`page`, `article`, `event`, `guide`, `collection`, and in `engine-dmo` `listing` and `area`) this file adds fields to
`label`	map of strings		The type’s name per locale
`plural`	map of strings		Its plural per locale
`icon`	string		The admin icon name
`localisable`	boolean	`true`	Documents of this type have per-locale versions
`singleton`	boolean	`false`	The type has one document per site, such as site settings
`searchable`	boolean	`false`	Published documents are indexed for site search
`template`	string	`<type>/entry.html`	The template an entry renders with
`uri`	string or map		A URI pattern the type carries itself, where it is not routed in `routes.yaml`
`sites`	list of strings	Every site	The sites the type is offered on
`ordering.field`	string		The field index pages order by
`ordering.direction`	string		`asc` or `desc`
`fields`	list	Required	The fields, in editor order (below)
`groups`	list	`[]`	Tabs or sections of the editor: `key`, `label`, the `fields` they hold and `collapsed`
`validation`	list	`[]`	Cross-field rules: `rule` (an expression), `message` per locale, `fields` the message shows against, `severity` (`error` or `warning`) and `on` (`save` or `publish`)
`member_editable`	object		Which fields members may edit in the portal, by tier, and whether their changes need review (`engine-dmo`)
`structured_data`	map		The schema.org type and property mapping for the type’s JSON-LD
`embed`	any		How the type is offered to embeddable widgets
`revisions`	any	`content.revisions`	The type’s revision retention, overriding the install’s key by key
`variants.default`	string		The default entry variant
`variants.options`	list		Entry variants: alternative editor and template layouts of the same type

A field

Key	Type	Default	Meaning
`name`	string	Required	The field’s handle, used in templates and the API. Unique in its type
`id`	string	Written for you	The field’s stable id, which keeps its values through a rename
`type`	string	Required	The field type: `address`, `asset`, `blocks`, `boolean`, `date`, `datetime`, `form`, `geo`, `geo_shape`, `link`, `money`, `number`, `opening_hours`, `phone`, `portable_text`, `recurrence`, `relation`, `repeater`, `select`, `seo`, `slug`, `text` or `video`
`use`	string		Instead of `name` and `type`: include a field group from `_shared.yaml`
`aliases`	list of strings	`[]`	Old handles still answered after a rename. `engine-dmo schema alias` lists and retires them
`label`	map of strings		The label per locale
`help`	map of strings		Help text per locale
`required`	boolean	`false`	A value is needed to publish
`required_in`	string or list	`source`	Where `required` applies: `source`, `all`, or a list of locale codes
`required_when`	string		An expression under which the field is required
`visible_when`	string		An expression under which the editor shows the field
`recommended`	boolean	`false`	The editor flags an empty value without blocking publishing
`index`	boolean	`false`	Projected for listing, filtering and sorting
`unique`	boolean	`false`	No two documents of the type share a value
`protected`	boolean	`false`	Any change to the field’s definition is a destructive schema change needing approval
`default`	any		The value a new document starts with
`translate`	string	The field type’s default (`text` and `link` are `locale`; `number`, `geo` and `phone` are `none`)	How values vary by locale: `locale` (each locale its own), `language` (shared across locales of one language), `group` (shared within a locale group) or `none` (one value for all)
`translatable`	boolean		Shorthand: `true` is `translate: locale`, `false` is `translate: none`
`structure`	string		For a container field: `shared` (one structure, per-locale text inside) or `per_locale`
`fallback`	string		What shows where a locale has no value: `inherit` (the fallback locale’s) or `empty`
`machine_translate`	string	`allow`	`allow` or `forbid` AI translation drafts for this field
`summary_of`	string		The field this text field summarises, which offers AI summarisation
`site_overridable`	boolean	`false`	A site may set its own value of a shared document’s field
`personal`	boolean	`false`	CRM person fields only: personal data, included in a subject access export and cleared by an erasure
`fields`	list		Child fields, for a `repeater`
`blocks`	list		The blocks a `blocks` field offers: each `key`, `label`, `description`, `item_label` and `fields`, or `use` of a shared block
`options`	list		A `select` field’s options: strings, or objects with their own ids
Any other key			A parameter of the field’s type, such as `max`, `multiline`, `to` or `accept`, checked against that type’s parameters

The parameters of the asset, link and video types (accept, alt, aspect, caption, focal, min_width, max_size, orientation, upload, upload_tags, tags, kinds, attributes, rel, styles, text, sources, hosts, poster, captions, transcript) are listed with their field types in Fields.

schema/_shared.yaml

Named field groups any field list includes with - use: <group>.

field_groups:
  contact:
    - name: phone
      type: phone
    - name: website
      type: link

Key	Type	Meaning
`field_groups.<group>`	list of fields	The group’s fields, with the field keys above

blocks/_index.yaml

Shared block definitions a blocks field includes with - use: <block>.

Key	Type	Meaning
`blocks[].key`	string	The block’s key; its template is `blocks/<key>.html`
`blocks[].id`	string	Its stable id, written for you
`blocks[].label`	map of strings	Its name per locale
`blocks[].description`	map of strings	What it is for, per locale
`blocks[].item_label`	string	The field whose value labels an item in the editor
`blocks[].fields`	list of fields	Its fields

crm/organisation.yaml, crm/person.yaml and portal/enquiries.yaml

engine-dmo

This feature is part of the DMO bundle (engine-dmo).

Custom fields on CRM organisations and people, and the fields a partner keeps against an enquiry in the portal. Each file has one key, fields, a list of field definitions with the keys above, limited to the field types the CRM supports; engine-dmo check names the allowed types if you use another. engine-dmo dev field add organisation <name> adds one with its id.

Key	Type	Meaning
`fields`	list of fields	The custom fields

The type fileCopy Anchor Link

A fieldCopy Anchor Link

schema/_shared.yamlCopy Anchor Link

blocks/_index.yamlCopy Anchor Link

crm/organisation.yaml, crm/person.yaml and portal/enquiries.yamlCopy Anchor Link

On this page

The type file

A field

schema/_shared.yaml

blocks/_index.yaml

crm/organisation.yaml, crm/person.yaml and portal/enquiries.yaml