Model YAML
Every content model and form can be written as a YAML file. The CLI’s plenary metadata pull writes these files, plenary metadata push applies them, and the console’s Export YAML and Import YAML use the same format. Keeping the files in your site’s repository lets you review model changes in pull requests and apply them on deploy. For the workflow, see Models as Code.
File layout
Section titled “File layout”One file per model, named by its key:
| Path | Holds |
|---|---|
models/<key>.yaml |
Collections, singletons, and shared object models |
forms/<key>.yaml |
Forms |
On import, either directory may hold any kind. A full plenary metadata pull also writes roles/ and sites/ files; those are covered in the CLI reference.
Files refer to other models by key, never by id, so the same tree can be applied to any instance. Field order in the file is the order fields appear in the editor.
Model keys
Section titled “Model keys”| Key | Type | Required | Default | Meaning |
|---|---|---|---|---|
key |
string | yes | Model key. Lowercase letters, digits, and underscores, starting with a letter. Object models must start with obj_. Cannot be changed once the model exists. |
|
kind |
string | yes | collection, singleton, object, or form. Cannot be changed once the model exists. |
|
name_singular |
string | yes | Display name for one entry, such as Blog Post. |
|
name_plural |
string | yes for collections and singletons | Display name for many, such as Blog Posts. Forms have none. |
|
description |
string | no | empty | Shown in the console. |
title_field |
string | no | none | Key of the field an entry’s title is read from. Must be a title-eligible type: text, rich_text, number, date, time, datetime, email, url, phone, select, or computed. |
is_active |
boolean | yes in exports | false |
Whether the model is available in the console. Inactive models are hidden from the content catalog by default; an inactive form rejects new form entries. Write true. |
is_private |
boolean | no | false |
Hide the model and all its entries from public API keys. Not used on objects or forms. |
is_shared |
boolean | objects only | true for a shared object model that other models embed. |
|
site_key |
string | see Site | The one site that owns the model. Every kind has one: collections, singletons, objects, and forms. Cannot be changed once the model exists. | |
show_preview |
boolean | no | false |
Give entries a live preview in the console. |
preview_url |
string | no | none | URL template for the preview, such as https://www.example.com/blog/{{slug}}. Kept only with show_preview: true. See Live Preview. |
open_in_page_builder |
boolean | no | false |
Open entries in the Page Builder instead of the form editor. Kept only with show_preview: true. |
require_change_notes |
boolean | no | false |
Every create, update, delete, and restore of an entry must carry a note. Needs track_revisions. |
track_revisions |
boolean | no | true |
Record a revision for every change to an entry. Turning it off deletes the history already recorded. |
always_published |
boolean | no | false |
Entries are published the moment they are saved. Turning it on publishes existing drafts. |
fields |
list | yes | The model’s fields, in order. See Field keys. | |
transformers |
list | no | none | Pre-save scripts. See Transformers. |
relationships |
list | no | none | Names for references that point at this model. See Relationships. |
Unknown keys are an error, so a typo fails the preview instead of being ignored.
What the file does not hold:
- Webhooks and a form’s email notifications. They can carry secrets, so they stay on the instance. An import leaves the stored ones untouched.
- Ids and timestamps.
Every model, form, and object belongs to exactly one site, named by site_key. There is no list of sites: a model cannot be shared between sites. To give two sites the same structure, give each site its own model; both may use the same key, because keys are unique within a site only.
Whether a file carries site_key depends on the tree it is in:
| Tree | site_key in the file |
|---|---|
One site’s tree: plenary metadata pull, diff, and push with a site configured, or the console’s Export all and Import on the YAML menu, which work on the site selected in the site switcher |
Left out. The tree’s site owns every model in it. A file may still name a site_key, as one from a model’s own Export YAML button does, but it must be that site or the import fails. |
The whole instance: plenary metadata with --all-sites |
Required on every model, form, and object. It must name a site that exists on the instance or is defined in the same tree’s sites/ directory. |
A model’s reference fields and object fields may only point at models on the same site.
Field keys
Section titled “Field keys”| Key | Type | Required | Meaning |
|---|---|---|---|
key |
string | yes | Field key. Lowercase letters, digits, and underscores, starting with a letter. Unique within the model. |
name |
string | yes | Label shown to editors. |
type |
string | yes | A field type identifier. Cannot be changed once the field exists. |
required |
boolean | no | The entry must have a non-empty value. |
unique |
boolean | no | No two entries of the model may hold the same value. |
localized |
boolean | no | Marks the field as varying by locale. Not allowed on forms. |
private |
boolean | no | Hidden from public API keys. |
hidden |
boolean | no | Hidden from the entry editor. |
visible_when |
string | no | JavaScript expression over data; the field shows only when it is true. Omit when hidden is true. |
object |
string | object fields using a shared object |
Key of the shared object model, such as obj_address. |
settings |
map | no | Type-specific settings. |
ui |
map | no | Type-specific editor options. |
validation |
map | no | Type-specific validation rules. |
settings, ui, and validation take exactly the keys listed for each type in the Field Types reference. Two settings are written differently in YAML than in the model API, because the file names models by key:
| Field type | In YAML | In the model API |
|---|---|---|
reference |
settings.model: <model key> |
settings.model_id: <model UUID> |
object (shared) |
object: <object model key> |
settings.object_id: <object model UUID> |
object (inline) |
settings.fields: [ … ] |
settings.fields on save, settings.object_id afterwards |
An inline object’s sub-fields use the same field keys as top-level fields. A computed field’s settings.dependencies is derived from its source; exports include it, and you can omit it in hand-written files.
Transformers
Section titled “Transformers”transformers: - name: Read time source: | data.read_time = null active: true| Key | Type | Required | Default | Meaning |
|---|---|---|---|---|
name |
string | yes | Unique within the model. Imports match stored transformers by name, so renaming one is a delete plus an add. | |
source |
string | yes | The JavaScript. It must compile, or the import fails. | |
active |
boolean | no | true |
Whether the transformer runs. |
Transformers run in the listed order. The file is the source of truth: a model file with no transformers key removes any the model has. Forms cannot have transformers. See Transformers for what a script can do.
Relationships
Section titled “Relationships”relationships names, from this model’s side, the reference fields on other models that point here. It controls what the entry editor’s References tab calls each group.
relationships: - source_model: staff source_field: primary_store key: managers label: Managers description: Staff whose primary store is this one. hidden: false| Key | Type | Required | Meaning |
|---|---|---|---|
source_model |
string | yes | Key of the model holding the reference field. |
source_field |
string | yes | Path of the reference field on that model, such as primary_store, or venue.host for a reference inside an object field. |
key |
string | yes | API name of the relationship, unique on this model. |
label |
string | yes | Name shown on the References tab. |
description |
string | no | |
hidden |
boolean | no | Hide the group from the References tab for everyone except model editors. |
Relationships are only meaningful on collections and singletons. See Content Models.
Example: a collection
Section titled “Example: a collection”# Plenary content model. Import it back through the console or `plenary metadata push`.
key: article # API name: /api/v1/content/articlekind: collectionname_singular: Articlename_plural: Articlesdescription: News and long-form posts, served at /news/{slug}.title_field: title # entries' `title` comes from this fieldis_active: true # no site_key: the tree's site owns the modelshow_preview: truepreview_url: https://www.example.com/news/{{slug}}fields: - key: title name: Title type: text required: true settings: trim: true validation: max_length: 120 # enforced by the server
- key: summary name: Summary type: text ui: control: textarea help_text: Shown on cards and used as the meta description.
- key: cover name: Cover Image type: image settings: focal_point: true # crops follow the editor's focal point variants: - { key: card, width: 800, height: 450, crop: true, format: webp } - { key: hero, width: 1600, format: jpeg, quality: 0.8 }
- key: category name: Category type: select required: true settings: options: - { label: News, value: news } - { label: Opinion, value: opinion }
- key: author name: Author type: reference settings: model: person # a model key, not an id on_delete: set_null published_only: true
- key: seo name: SEO type: object object: obj_seo # a shared object model defined in its own file
- key: links name: Further Reading type: list settings: item_type: object sortable: true item_settings: title_field: label # what a collapsed item shows in the editor fields: - { key: label, name: Label, type: text, required: true } - { key: url, name: URL, type: url, required: true } ui: add_label: Add link
- key: body name: Body type: rich_text required: true settings: format: md ui: control: markdown_editor
- key: read_time name: Read Time (minutes) type: number hidden: true # set by the transformer below, not by editors
transformers: - name: Read time source: | let words = 0 if (data.body) { const parts = data.body.split(' ') for (let i = 0; i < parts.length; i = i + 1) { if (parts[i].trim().length > 0) { words = words + 1 } } } data.read_time = Math.max(1, Math.ceil(words / 200))The seo field above needs a shared object model in the same tree (or already on the instance):
key: obj_seo # object model keys start with obj_kind: objectname_singular: SEOname_plural: SEOis_active: trueis_shared: true # lets any model embed itfields: - key: meta_title name: Meta Title type: text - key: meta_description name: Meta Description type: text ui: control: textareaExample: a singleton
Section titled “Example: a singleton”A singleton has one entry per site and locale. This one holds site-wide navigation and footer content, and skips the draft step.
key: site_settingskind: singletonname_singular: Site Settingsname_plural: Site Settingsdescription: Navigation and footer shared by every page.is_active: truealways_published: true # every save goes live; no drafts or schedulingfields: - key: announcement name: Announcement type: text ui: help_text: The banner above the header. Leave empty to hide it.
- key: nav_links name: Navigation Links type: list settings: item_type: object sortable: true item_settings: title_field: label fields: - { key: label, name: Label, type: text, required: true } - { key: url, name: URL, type: text, required: true } ui: control: table add_label: Add link
- key: cta_banner name: CTA Banner type: object settings: # an inline object: sub-fields live here fields: - { key: heading, name: Heading, type: text, required: true } - { key: button_label, name: Button Label, type: text } - { key: button_url, name: Button URL, type: url }
- key: copyright name: Copyright Line type: textValidation on import
Section titled “Validation on import”An import previews first, and the preview validates exactly what an apply would. These all fail the whole import with 422 metadata_invalid and a message naming the file and field:
- YAML that does not parse, or an unknown key.
- A model or field key that breaks the key format.
- An unknown
kindor fieldtype. settings,ui, orvalidationkeys the field type does not accept.- An
object:that names no object model, or a model that is not kindobject. - A reference
settings.modelthat names no model in the tree or on the instance. - A
title_fieldthat is not a field, or is not a title-eligible type. - A transformer with no name, a duplicate name, empty source, or source that does not compile.
- A model with no
site_keyin an instance-wide tree, asite_keythat names no site, or, in one site’s tree, asite_keyfor another site. - A
siteslist with more than one site, or asitesentry that disagrees withsite_key. - A reference or object field that points at a model on another site.
Applying is not transactional: models are written one at a time. If an apply fails part-way, fix the cause and run it again; models already applied report as unchanged.
What an import changes
Section titled “What an import changes”- A file whose key is new on its site creates the model there. A file whose key exists on its site updates it to match the file.
- A model with no file is left alone. Only
plenary metadata push --prunedeletes models that have no file. - Removing a field from a file removes the field and its values from every entry when applied.
- Turning
always_publishedon publishes the model’s draft entries. Turningtrack_revisionsoff deletes the recorded history of the model’s entries. - Saving a model re-renders every entry’s computed fields.
Related
Section titled “Related”- Models as Code: the pull, diff, and push workflow.
- CLI reference:
plenary metadatacommands and flags. - Field Types: every type’s
settings,ui, andvalidationkeys. - Content Models: what each model setting does.