Skip to content

Field Types

Every field on a content model has a type. The type decides the JSON value stored under data.<key> on an entry, which settings the field accepts, and which query operators work on it. This page lists all 23 types. For adding and configuring fields in the console, see Fields.

Type Console label Value on read Filter operators Title field List item Object sub-field Form
text Text string all yes yes yes yes
rich_text Rich text string all yes yes yes no
number Number number all yes yes yes yes
boolean Boolean true / false all no yes yes yes
date Date string "2026-05-11" all yes yes yes yes
time Time string "14:30:00" all yes yes yes yes
datetime Date & time string "2026-05-11T20:30:00Z" all yes yes yes yes
json JSON object $is_null no yes yes yes
image Image object with media_id $is_null no no yes no
file File object with media_id $is_null no no yes no
reference Reference object with content_id $eq $ne $in $nin $is_null no no yes no
user User object with user_id $is_null no no no no
email Email string all yes yes yes yes
url URL string all yes yes yes yes
phone Phone string, E.164 all yes yes yes yes
color Color string "#1a2b3c" all no yes yes yes
select Select string all yes yes yes yes
multi_select Multi-select array of strings $is_null no yes yes yes
object Object object $is_null no yes no yes
list List array $is_null no no yes yes
tags Tags array of strings $is_null no no yes yes
computed Computed string all yes no yes no
blocks Blocks object {version, root} $is_null no no no no

Column notes:

  • Filter operators are what where:data.<key> and filters accept for the field. “all” means $eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $like, $ilike, and $is_null. Any other operator on a structured field returns 400 entry_query_invalid. See the Content API reference.
  • Title field means the type can be a model’s title_field, the field an entry’s title is read from.
  • List item means the type can be a list field’s item_type.
  • Object sub-field means the type can be a field inside an object (inline or shared). The items of a list of objects also exclude list and computed.
  • Form means the type can be used on a form.

Sorting with sort:data.<key> is accepted for any field and orders by the stored value. It is only meaningful for the scalar types.

Every field, whatever its type, is a row with these properties. In the model API and in model YAML they sit beside the type-specific settings, ui, and validation objects.

Property Type Meaning
key string API name. Lowercase letters, digits, and underscores, starting with a letter (^[a-z][a-z0-9_]*$). Unique within the model. Cannot change after the field is saved.
name string Label shown to editors. Required.
type string One of the types on this page. Cannot change after the field is saved.
required boolean The entry must have a non-empty value. See Required values.
unique boolean No other entry of the model may hold the same value. Checked on every write; a clash is 409 entry_field_value_taken. The scope is the whole model: every site and every locale.
localized boolean Marks the field as varying by locale. Informational: every entry already belongs to one locale, so no read or write changes because of it. Not allowed on forms.
private boolean Hidden from public API keys. The field is removed from public reads and cannot be used in a public key’s where:, sort:, include, or hydrate:.
hidden boolean Hides the field from the entry editor. A hidden field is not required, and an update keeps its stored value.
visible_when string A JavaScript expression over data. The field is shown, and validated, only when it is true. Ignored when hidden is true. See Conditional visibility.
sort_order integer Position in the editor. Explicit values must be unique; omitted values are assigned in order.
settings object How the field behaves. Per type, below.
ui object How the console presents the field. Every type accepts help_text, shown under the input.
validation object Constraints on the value. Per type, below.

The settings, ui, and validation objects are checked against a closed schema when the model is saved. An unknown key is rejected with 422 model_field_schema_invalid, and the error’s vars.path points at the bad key.

When an entry is written, the server always checks:

  • The value’s JSON shape for the field’s type. For example, a number must be a JSON number and an image must be an object with a media_id.
  • required and unique.
  • phone values match E.164 (^\+[1-9]\d{1,14}$), and color values match #rrggbb or #rrggbbaa.
  • Unknown field keys are rejected with 422 entry_field_unknown.

The server also enforces these validation keys:

Type Enforced validation keys
text min_length, max_length (counted in characters), regex
phone allowed_country_codes, plus full number validity
color allow_alpha, allowed

Every other settings and validation key is stored and used by the console’s editors, but the server does not check it on write. That includes select and multi_select options, email and url format, min_items / max_items, number bounds, and date bounds. If values arrive through the API rather than the console, validate them in your own code or in a transformer.

A rule failure returns 422 entry_field_rule_violation with vars.field and vars.rule. A shape failure returns 422 entry_field_schema_invalid with vars.field and vars.message.

Entry writes send field values in a fields object; reads return them in data. A write replaces data wholesale, so a field you leave out is cleared.

To clear a single field explicitly, send null. For phone, email, url, color, select, date, time, datetime, and number, an empty string "" also clears the field. In text and rich_text, "" is stored as an empty string.

Clearing a required field fails with 422 entry_field_required.

The server never applies a field’s settings.default. The console uses it to pre-fill new entries; an API write gets no defaults.

required: true means the value is present and non-empty:

Type Counts as empty
text, rich_text, email, url, phone, color, select, date, time, datetime absent or ""
number, boolean, json, object absent or null
multi_select, list, tags absent or []
image, file no media_id
reference no reference_id / content_id, or empty reference_ids
user no user_id, or empty user_ids
blocks no root key (an empty root: [] counts as present)

A field hidden by hidden or by a false visible_when is never required.

Short or medium plain text: titles, names, labels, summaries, slugs.

"title": "Spring sale starts Monday"
Group Key Values Notes
settings trim boolean Strips leading and trailing whitespace before validation and storage. Applies inside objects and list items too.
ui control input, textarea, slug slug formats input as a URL-friendly slug.
ui placeholder, autocomplete string autocomplete is the HTML input hint (name, tel, url, …).
validation min_length integer ≥ 0 Enforced. Counted in characters.
validation max_length integer ≥ 1 Enforced.
validation regex string Enforced. Go (RE2) regular expression syntax.

text has no default.

Formatted text stored as one string of Markdown or HTML.

"body": "## Hours\n\nWe are open **9 to 5** on weekdays."
Group Key Values Notes
settings format md, html Which markup the string holds.
settings allowed_blocks array of paragraph, heading, blockquote, ordered_list, unordered_list, code, image, embed Editor hint.
settings sanitize boolean Editor hint.
ui control rich_text_editor, markdown_editor, html_editor
ui placeholder string
ui toolbar array of strings
ui preview boolean
validation min_length, max_length, min_words, max_words integers Not enforced by the server.
validation regex string Not enforced by the server.
validation disallow_html boolean Not enforced by the server.

Render the string with your own Markdown or HTML pipeline. Plenary does not sanitize it on read.

"price": 49.95
Group Key Values Notes
settings default number Console pre-fill only.
settings format integer, float, decimal Editor hint. Any JSON number is accepted.
settings precision integer ≥ 0 Editor hint.
settings unit string Editor hint.
ui control number_input, slider, range
ui step, placeholder, prefix, suffix
validation min_val, max_val number Not enforced by the server.
validation multiple_of number > 0 Not enforced by the server.

Filter values are converted to numbers: ?where:data.price.$lt=50. A value that is not a number returns 400.

"featured": true
Group Key Values Notes
settings default boolean Console pre-fill only.
ui control switch, checkbox, radio
ui true_label, false_label string

Filter with true or false: ?where:data.featured=true.

A calendar date with no time or timezone, as YYYY-MM-DD.

"published_date": "2026-05-11"
Group Key Values Notes
settings format "date" Fixed.
settings default null, "today" Console pre-fill only; today is the editor’s local date.
ui control date_picker, date_input
ui display_format, placeholder string
validation min_date, max_date string Not enforced by the server.
validation allow_past, allow_future boolean Not enforced by the server.

The server stores the string as sent and does not check its format, so send YYYY-MM-DD. Filters on date fields compare strings, which orders correctly in this format.

A time of day with no date or timezone.

"opens_at": "09:30:00"
Group Key Values Notes
settings format 24h, 12h Editor display.
settings include_seconds boolean
settings default string or null Console pre-fill only.
ui control time_picker, time_input
ui step_minutes integer ≥ 1
ui placeholder string
validation min_time, max_time string Not enforced by the server.

A precise moment, stored as an RFC 3339 timestamp in UTC.

"starts_at": "2026-05-11T20:30:00Z"
Group Key Values Notes
settings timezone_mode utc, editor_local, site_timezone Which zone the console shows and accepts input in. Storage is always UTC.
settings default string or null Console pre-fill only (the console offers "now").
ui control datetime_picker, datetime_input
ui display_format string
ui show_timezone boolean
validation min_timestamp, max_timestamp string Not enforced by the server.
validation allow_past, allow_future boolean Not enforced by the server.

The server stores the string as sent and does not parse it. Write UTC values in one consistent format so that string comparisons in filters and sorts order correctly.

A free-form JSON object for configuration, integration payloads, or anything without a dedicated type.

"embed_config": { "provider": "youtube", "autoplay": false }
Group Key Values Notes
settings allowed_types array of object, array, string, number, boolean, null Editor hint.
settings schema any Editor hint.
ui control json_editor, code_editor, textarea
ui mode tree, code
validation json_schema any Not enforced by the server.
validation max_bytes integer ≥ 1 Not enforced by the server.

The value must be a JSON object. An array, string, or number is rejected with 422 entry_field_schema_invalid (“got array, want object”). Wrap other values in an object.

A reference to an image in the Media Library, with alt text, caption, focal point, and generated variants.

Write shape:

"cover": {
"media_id": "17992148-aa28-4ebc-b582-643b58513f5f",
"alt": "Volunteers at the spring food drive",
"caption": "Spring food drive, 2026",
"focal_point": { "x": 0.49, "y": 0.36 }
}

media_id is required. alt, caption, and focal_point are optional. When focal_point is present, both x and y are required, each from 0 to 1, measured from the top-left corner. No other keys are accepted.

Read shape. When the field declares variants, reads add a variants map with one URL per variant key:

"cover": {
"media_id": "17992148-aa28-4ebc-b582-643b58513f5f",
"alt": "Volunteers at the spring food drive",
"caption": "Spring food drive, 2026",
"focal_point": { "x": 0.49, "y": 0.36 },
"variants": {
"card": { "url": "/media/17992148-aa28-4ebc-b582-643b58513f5f/622a5ace95c45761.webp" }
}
}
Group Key Values Notes
settings variants array of variant specs See below. Declaring variants queues their generation on every save.
settings focal_point boolean Shows the focal-point editor and makes cropping variants crop around the value’s focal point.
settings require_caption boolean Not enforced by the server.
settings multiple boolean Accepted, but the value must still be a single object.
ui allow_upload, allow_library_browse boolean Picker options.
ui allowed_file_extensions array of strings Picker filter.
validation min_items, max_items, min_width, max_width, min_height, max_height, max_file_size_bytes numbers Not enforced by the server.
validation aspect_ratio number Not enforced by the server. A decimal such as 1.7778, not "16:9".

Each variant spec:

Key Type Meaning
key string, required Name of the variant in the variants map.
width integer ≥ 1 Target width in pixels.
height integer ≥ 1 Target height in pixels.
format jpeg, png, webp Output format. Defaults to webp.
quality number, 0 to 1 Encoder quality. Ignored by lossless formats.
crop boolean With width and height, fill the box and crop the overflow. Without crop, the image is scaled to fit inside the box.

A variant needs width, height, or both; a spec with neither is skipped. Images are never scaled up.

Variant URLs are paths on your instance, so prefix them with the instance origin. A variant URL can return 404 for a short time after a save while the file is generated; fall back to the original until it resolves. The URL is derived from the variant spec and, for cropping variants, the focal point, so it changes whenever either changes.

The variants map is generated by the server. You can send a read value straight back in a write; the server strips variants before validating.

The entry value does not include the original file’s URL. Fetch GET /api/v1/media/{media_id} for original_url, dimensions, and each variant’s status. If the asset was deleted from the Media Library, the value keeps its media_id and its URLs return 404.

Variant generation and the variants map apply to image fields at the top level of a model. An image sub-field inside an object stores the same value without variants.

A reference to any Media Library asset: a PDF, video, audio file, archive, or an image you do not need variants for.

"brochure": {
"media_id": "ce221afb-0ef2-4fc6-94d6-8c3da0cc391e",
"alt": "Program brochure",
"caption": "Fall 2026 program"
}

media_id is required; alt and caption are optional. There is no focal point and no variants map.

Group Key Values Notes
ui allow_upload, allow_library_browse boolean Picker options.
ui allowed_file_extensions array of strings Picker filter.

file has no server schema for settings or validation. The console’s file panel stores multiple and require_caption there; the server does not act on them.

To get a download URL, fetch GET /api/v1/media/{media_id} and use original_url.

A link to an entry of another model: an article’s author, an event’s venue.

Write one of these shapes:

"author": { "reference_id": "bc5b8881-d9df-4ac5-afe7-041ea5faf82e" }
"related": { "reference_ids": ["bc5b8881-d9df-4ac5-afe7-041ea5faf82e", "285e3e7f-c343-45b0-8df3-1325b1495448"] }

A single reference is stored and read as the target’s id plus its model key:

"author": { "content_id": "bc5b8881-d9df-4ac5-afe7-041ea5faf82e", "model_key": "person" }

The read shape is also accepted on write, so you can read an entry, change another field, and write it back. The server re-resolves model_key from the field’s settings. A multiple reference is stored and read exactly as written: { "reference_ids": [...] }.

Group Key Values Notes
settings model_id model UUID The target model. In model YAML this is model: <model key>.
settings multiple boolean Pick several entries (reference_ids).
settings on_delete restrict, set_null What deleting the target does. See below.
settings published_only boolean Only published entries may be linked. Checked when linking from the target’s References tab; the console’s picker applies it too.
settings unique boolean Checked when linking from the target’s References tab.
ui control autocomplete, dropdown
validation min_items, max_items integers Not enforced by the server.

on_delete decides what deleting a referenced entry does:

  • restrict: the delete is refused with 409 entry_referenced while anything points at the entry.
  • set_null, or unset: the delete goes through, then the pointer is cleared on every referencing entry. Each of those entries records an update revision and fires entry.updated.

A required single reference always restricts, whatever on_delete says.

Hydration. Add hydrate:data.<key>=* (or a comma-separated field list) to a read to replace a single reference with the target entry. A hydrated value is not a valid write; reduce it to { "reference_id": "…" } before writing. Multiple references are not hydrated.

Filtering. A single reference takes $eq, $ne, $in, $nin, and $is_null, matched against the target’s id: ?where:data.author=<entry id>. Multiple references support only $is_null.

Normalization, hydration, and filtering apply to reference fields at the top level of a model.

A link to a Plenary user account, such as an author or owner.

Write:

"owner": { "user_id": "6a1d0c4e-2f0b-4c55-9d1e-7f0a5b1c9e21" }

or, with settings.multiple, { "user_ids": ["…", "…"] }.

Every read adds the resolved profile beside the id, under user (single) or users (multiple, in the same order). No hydrate: parameter is needed:

"owner": {
"user_id": "6a1d0c4e-2f0b-4c55-9d1e-7f0a5b1c9e21",
"user": {
"id": "6a1d0c4e-2f0b-4c55-9d1e-7f0a5b1c9e21",
"username": "alee",
"first_name": "Ann",
"last_name": "Lee",
"avatar_url": "/media/…/….webp"
}
}

The profile holds at most id, username, display_name, first_name, last_name, and avatar_url; empty keys are omitted. Every caller, including public API keys, gets the same profile. Email addresses and roles are never included. An id that names no account resolves to { "id": "…", "missing": true }.

The write schema accepts only user_id or user_ids. Remove user / users before writing a read value back.

Group Key Values Notes
settings multiple boolean
"contact_email": "editor@example.com"
Group Key Values Notes
settings normalize, allow_display_name boolean Editor hints.
ui control email_input, text_input
ui placeholder, autocomplete string
validation allow_plus_addressing boolean Not enforced by the server.
validation allowed_domains, blocked_domains array of strings Not enforced by the server.
validation max_length integer ≥ 1 Not enforced by the server.

The server accepts any string. Validate the address format yourself if values come from outside the console.

"website": "https://www.example.org/visit"
Group Key Values Notes
settings normalize boolean Editor hint.
settings default_protocol string Editor hint.
ui control url_input, text_input
ui placeholder, autocomplete string
ui show_open_link boolean
validation allowed_protocols, allowed_domains, blocked_domains array of strings Not enforced by the server.
validation max_length integer ≥ 1 Not enforced by the server.

A telephone number in E.164 form.

"phone": "+14155552671"

Every write must match ^\+[1-9]\d{1,14}$. The console converts national numbers using default_country_code; API writers must send E.164 themselves.

Group Key Values Notes
settings default_country_code ISO 3166-1 alpha-2, e.g. US Console conversion only.
ui control phone_input, text_input
ui placeholder, autocomplete string
ui display_format national, international, e164 Console display.
validation allowed_country_codes array of ISO codes Enforced, along with full number validity, when the field has a validation object.

A hex color.

"accent": "#1a2b3c"

Every write must be #rrggbb or #rrggbbaa. Three-digit shorthand, color names, and rgb() are rejected. Case is stored as sent; the console writes lowercase.

Group Key Values Notes
settings default hex string Console pre-fill only.
ui presets array of hex strings Swatches in the picker. Does not restrict values.
validation allow_alpha boolean, default false Enforced: accept #rrggbbaa.
validation allowed array of hex strings Enforced: the value must be one of these, compared case-insensitively.

One choice from a fixed list. The stored value is the option’s value.

"category": "press-release"
Group Key Values Notes
settings options array of { "label": string, "value": string } Both keys required.
settings allow_custom boolean Lets editors type a value not in the list.
ui control select, radio, segmented
ui placeholder string
ui searchable, clearable boolean

Filter and store by value; treat label as display text that may change. The server does not check that a written value is one of the options.

In a computed field, {{data.category}} and {{data.category.value}} render the value, and {{data.category.label}} renders the option’s label.

Zero or more choices from a fixed list.

"topics": ["news", "featured"]
Group Key Values Notes
settings options array of { "label", "value" }
settings allow_custom boolean
settings preserve_order boolean Keep the order editors picked.
ui control multi_select, checkbox_group, tag_picker
ui placeholder string
ui searchable, clearable boolean
validation min_items, max_items integers Not enforced by the server.
validation unique_items boolean Not enforced by the server.
validation allowed_values array of strings Not enforced by the server.

The value must be an array of strings. Filters support $is_null only.

A group of sub-fields stored as one value: an address, an SEO block, a call to action.

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

An object’s schema comes from one of two places:

  • Inline: the sub-fields belong to this field only. Send settings: { "fields": [ … ] } when saving the model. The server stores the definition as a hidden object model and rewrites the setting to object_id.
  • Shared: the field points at an object model (kind object, key prefixed obj_) that any model can reuse. Send settings: { "object_id": "<object model UUID>" }.

Model reads return settings.object_id plus a read-only settings.object snapshot of the schema (id, key, name, is_shared, fields).

Sub-field values are checked against their own types: input shape, required, and the enforced rules for text, phone, and color. An unknown sub-field key is rejected with 422 entry_subfield_unknown. An object cannot contain another object. Sub-fields support hidden, but not private or visible_when.

Computed sub-fields inside an object reference their siblings by bare key, such as {{first_name}} {{last_name}}. See Computed fields.

You cannot filter on a sub-field: ?where:data.physical_address.city=Denver returns 400 entry_query_invalid. The object field itself supports $is_null.

An ordered array of values of one item type: FAQ items, links, opening hours.

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

A list of a scalar type stores plain values, for example ["Mon 9–5", "Tue 9–5"] for a text list.

Group Key Values Notes
settings item_type type identifier, required One of text, rich_text, number, boolean, date, time, datetime, email, url, phone, color, json, select, multi_select, object.
settings item_settings object For object items: fields (required) and an optional title_field. For other item types: that type’s settings, such as options for a select.
settings sortable boolean Editors can reorder items.
ui control list_editor, tag_list, gallery, table
ui add_label string Text of the add button, such as “Add link”.
ui collapsible_items, collapsed_by_default boolean
validation min_items, max_items integers Not enforced by the server.
validation unique_items boolean Not enforced by the server.
validation item_validation object Not enforced by the server.

Lists of objects. With item_type: "object", item_settings.fields declares the sub-fields of each item, one level deep. Item sub-fields cannot be object, list, or computed. Each item is validated like an object value, and errors carry the item’s position in vars.index (for example 422 entry_list_subfield_required).

item_settings.title_field names the sub-field the console shows on a collapsed item. It must be one of the item’s sub-fields (otherwise model_list_title_field_unknown) and a title-eligible type (otherwise model_list_title_field_type_invalid). Without it, the console shows the first text-like sub-field. It affects the editor only; entries carry no per-item title.

{
"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" }
}

Image, file, and reference values cannot be list items; use the field’s own multiple setting instead.

Free-form short strings that editors type in.

"tags": ["announcements", "product"]
Group Key Values Notes
ui placeholder string
validation min_items, max_items integers Not enforced by the server.
validation item_validation { min_length, max_length, regex } Not enforced by the server.

tags has no settings. The value must be an array of strings.

A string rendered by the server on every save from a template of other values. Editors cannot type into it.

"full_name": "Pastor Mike Degner"
Group Key Values Notes
settings source string, required The template.
settings dependencies array of strings Derived from source on save. Anything you send is replaced.

The template is literal text with {{…}} holes:

Reference Renders
{{data.<field>}} A field’s stored value.
{{data.<object_field>.<sub_field>}} A value inside an object field.
{{data.<select_field>.label}} A select option’s label. .value, or no suffix, renders the stored value.
{{id}}, {{site_key}}, {{slug}}, {{locale}}, {{status}}, {{published_at}}, {{created_at}}, {{updated_at}}, {{path}}, {{folder_id}} A property of the entry. Timestamps render in RFC 3339, UTC.

Inside an object, a computed sub-field names its siblings without a prefix ({{first_name}} {{last_name}}) and cannot reference the entry.

A reference to an unknown field is rejected when the model is saved (422 model_field_computed_source_invalid or an unknown-reference error). A reference that resolves to nothing renders as an empty string. {{title}} is not valid.

Computed values are rendered after transformers and validation. A computed value sent in a write is discarded, so you can write back a read value unchanged. A transformer that sets one fails the write with entry_field_computed_read_only. Saving the model re-renders the computed values of every entry. Publishing does not re-render, so a template using {{status}} or {{published_at}} reflects the last data save.

A Page Builder component tree. A model with a blocks field has entries that can be edited on the Page Builder canvas.

"body": {
"version": 1,
"root": [
{ "id": "3e45a42e-06fa-426a-838b-f08fb80dd7ab", "component": "hero", "props": { "heading": "Welcome" } }
]
}
Group Key Values Notes
ui label string

blocks has no settings or validation options. The document’s structure is checked on write (422 entry_dom_invalid). Image blocks gain a server-generated variant_url on their media value on read; it is stripped on write. See the Page Builder guide and the @plenary/react reference for rendering.