Skip to content

Fields

Fields are what an entry holds: a headline, a cover image, a link to an author. Each field on a content model has a key, a name, and a type, plus flags and type-specific settings. This page covers adding and configuring fields. For every type’s value shape and options, see the Field Types reference.

  1. Open the model from Content (select Settings on its card) and go to its fields.
  2. Select Add field. The picker lists every type, grouped as Text, Numbers & logic, Date & time, Documents & media, Structure, Relationships, and Advanced.
  3. Pick a type, then set the field’s Name. The Key is filled in from the name.
  4. Set the flags you need (below) and any options on the Settings, Editor, and Validation tabs.
  5. Select Save model.

The Key and Type cannot be changed after the model is saved, because stored values are keyed by them. To rename a field’s key or change its type, add a new field, copy the values across, and remove the old one.

Through the API, fields are the fields array of the model sent to POST /api/v1/models or PUT /api/v1/models/{id}:

{
"key": "summary",
"name": "Summary",
"type": "text",
"required": false,
"unique": false,
"private": false,
"localized": true,
"settings": { "trim": true },
"ui": { "control": "textarea", "help_text": "Shown on cards and in search results." },
"validation": { "max_length": 280 }
}
Console label Property What it does
Required required An entry cannot be saved without a value. 422 entry_field_required if missing.
Unique unique No two entries of the model may hold the same value (409 entry_field_value_taken). Uniqueness covers the whole model: every site and every locale, so translations cannot repeat the value either.
Data visibility: Public / Private private A private field is left out of responses to public API keys and cannot be used in their filters, sorts, or include. Signed-in users and private keys see it. Use it for internal notes or contact details.
Localized localized Marks the field as one whose value differs by language. It is a label for editors: every entry already belongs to one locale, so nothing else changes. See Localization.
Title field the model’s title_field Makes this field the entry’s title. Only one field per model.

The console does not offer Unique on singletons, objects, or forms, or for types where it has no meaning.

The Editor tab holds ui options: the input control (for example a textarea or a slug input for text), placeholder text, and Help text, which the entry editor shows under the input. Help text is the best place to tell editors what a field is for and where it appears on the site.

The Validation tab holds the type’s validation rules. The console checks all of them as editors type. The server enforces a subset on every write, whoever makes it:

  • text: Minimum length, Maximum length, and Pattern (regex).
  • phone: Allowed countries, and that the number is valid.
  • color: Allow transparency and Allowed colors.
  • Every type: Required, Unique, and the basic shape of the value (a number is a number, a phone number is E.164, a color is hex).

Other rules, such as select options, email format, or item counts on lists, are not checked by the server. If your entries are written through the API, enforce those in your own code or in a transformer. The Field Types reference lists exactly what is enforced per type.

Editor visibility decides whether editors are asked for a field:

Option Property Behavior
Visible neither set Always shown.
Hidden hidden: true Never shown in the entry editor. Useful for values set by a transformer or an import.
Visible on condition visible_when Shown only when the condition is true.

A condition is a JavaScript expression over the entry’s data, entered under Show this field when:

data.link_type === "external"
data.event_kind === "online" && data.registration_required

A select value is its stored option value, so compare against values, not labels.

The same condition runs in two places. The console evaluates it as editors type, to show and hide inputs. The server evaluates it on every write. When a field is hidden for an entry, by hidden or by a false condition:

  • It is not required, and its validation rules are skipped.
  • On an update, its stored value is kept, so hiding a field never deletes data.

The model save rejects a condition that does not compile, or that names a field the model does not have (422 model_field_visible_when_invalid, 422 model_field_visible_when_unknown_ref). Conditions can read data only. If a condition throws while running, the field is treated as visible.

Sub-fields inside an object can be Hidden but cannot have a condition.

A computed field holds text the server builds from other values every time the entry is saved. Editors see it but cannot type in it. Use one to make a display title, a full name, or a sort key.

Set its Source template to literal text with {{…}} holes:

{{data.first_name}} {{data.last_name}}
{{data.name}} - {{data.physical_address.city}}, {{data.physical_address.state}}

What a hole can name:

Reference Value
{{data.<field>}} A field of this model.
{{data.<object_field>.<sub_field>}} A sub-field of an object field.
{{data.<select>.label}} A select option’s label. {{data.<select>}} and {{data.<select>.value}} give the stored value.
{{slug}}, {{locale}}, {{site_key}}, {{id}}, {{status}}, {{path}}, {{folder_id}}, {{created_at}}, {{updated_at}}, {{published_at}} A property of the entry. Timestamps are RFC 3339 in UTC.

Rules to know:

  • Holes are replaced, never evaluated. There are no conditionals, formatting, or arithmetic. For those, write a transformer that sets an ordinary field.
  • A hole that resolves to nothing renders as nothing, so {{data.subtitle}} on an entry without a subtitle leaves a gap rather than an error.
  • The template is checked when the model is saved. Naming an unknown field, or {{title}}, is refused.
  • Computed fields render after transformers and validation, in field order. A later computed field can use an earlier one.
  • Saving the model re-renders every entry’s computed values. Publishing does not, so a template using {{status}} or {{published_at}} shows the value as of the last save of the entry’s data.
  • Values sent for a computed field in a write are ignored, so you can write back what you read.

A computed sub-field of an object refers to its sibling sub-fields by bare key, with no data. prefix:

{{first_name}} {{last_name}}

An object cannot see the entry around it, because the same object may be embedded in many models. Entry properties such as {{slug}} are not available inside an object. Object computed fields render before the entry’s own computed fields, so an entry-level template can use {{data.person.full_name}}.

Lists of objects cannot contain computed sub-fields.

An object field groups sub-fields into one value, such as an address:

"physical_address": { "street_address": "7979 Meade Street", "city": "Westminster", "state": "CO", "zip_code": "80030" }

When you add an object field, choose where its sub-fields come from:

  • Define new object: sub-fields that belong to this field only. Use this for a one-off group.
  • Use shared object: point at a shared object model that any model can embed. Use this for a structure you repeat, such as an address or an SEO block. Editing the shared object updates every model that uses it, and rewrites the entries that embed it.

To create a shared object, go to Content, select New model, and choose the Object kind. Its key starts with obj_. With Shared on, it appears under Use shared object in every model’s field panel.

Object sub-fields can be most field types, with these limits:

  • An object cannot contain another object, a user field, or a blocks field.
  • Sub-fields can be Required and Hidden, but not private or conditionally visible.
  • You cannot filter entries on a sub-field’s value. Use a top-level field, or a computed field that copies the value, for anything you need to query.

A list field holds an ordered array of values of one Item type: text, numbers, dates, URLs, selects, and other scalar types, or objects.

"opening_hours": ["Mon–Fri 9:00–17:00", "Sat 10:00–14:00"]

A list of objects is how you model repeating groups such as links, FAQ items, or pricing features. Choose Object as the item type and add the item’s fields under it:

"nav_links": [
{ "label": "Pricing", "url": "/pricing" },
{ "label": "Docs", "url": "https://docs.example.com" }
]

List settings:

  • Title field names the sub-field shown on each collapsed item in the editor, such as label or question. It must be a text-like field. Without one, the editor shows the first text-like sub-field.
  • Sortable lets editors drag items into order. The stored array is in that order.
  • Add button label customizes the add button, such as “Add link”.
  • The Editor tab’s control can show the list as a table, which suits short objects like links.

Item sub-fields of a list of objects cannot be objects, lists, or computed fields. Image, file, and reference fields cannot be list item types on their own; use the field’s Allow multiple setting instead, or put the field inside a list of objects.

For a free-form set of labels, the tags type is simpler than a list.

Drag fields to reorder them; the order is the order of inputs in the entry editor. To remove a field, delete it in the model editor and save. Saving removes the field and its values from every entry. Until you save, Restore field brings it back.