Skip to content

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.

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.

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.

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:
- 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 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.

plenary/models/article.yaml
# Plenary content model. Import it back through the console or `plenary metadata push`.
key: article # API name: /api/v1/content/article
kind: collection
name_singular: Article
name_plural: Articles
description: News and long-form posts, served at /news/{slug}.
title_field: title # entries' `title` comes from this field
is_active: true # no site_key: the tree's site owns the model
show_preview: true
preview_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):

plenary/models/obj_seo.yaml
key: obj_seo # object model keys start with obj_
kind: object
name_singular: SEO
name_plural: SEO
is_active: true
is_shared: true # lets any model embed it
fields:
- key: meta_title
name: Meta Title
type: text
- key: meta_description
name: Meta Description
type: text
ui:
control: textarea

A singleton has one entry per site and locale. This one holds site-wide navigation and footer content, and skips the draft step.

plenary/models/site_settings.yaml
key: site_settings
kind: singleton
name_singular: Site Settings
name_plural: Site Settings
description: Navigation and footer shared by every page.
is_active: true
always_published: true # every save goes live; no drafts or scheduling
fields:
- 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: text

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 kind or field type.
  • settings, ui, or validation keys the field type does not accept.
  • An object: that names no object model, or a model that is not kind object.
  • A reference settings.model that names no model in the tree or on the instance.
  • A title_field that 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_key in an instance-wide tree, a site_key that names no site, or, in one site’s tree, a site_key for another site.
  • A sites list with more than one site, or a sites entry that disagrees with site_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.

  • 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 --prune deletes models that have no file.
  • Removing a field from a file removes the field and its values from every entry when applied.
  • Turning always_published on publishes the model’s draft entries. Turning track_revisions off deletes the recorded history of the model’s entries.
  • Saving a model re-renders every entry’s computed fields.