Overview

Blueprints are built from 14 field types. This page lists each type's purpose and options, and shows how its value looks in Liquid templates and in API and MCP responses.

Type	Use it for	Liquid value	API value
`text`	Short plain text	String	String
`rich_text`	Formatted body copy (visual editor)	HTML string	HTML string
`raw_html`	Exact HTML and embed codes, stored verbatim	HTML string	HTML string
`image`	One image	Path string	Path string
`gallery`	Several images or videos	Array of item objects	Array of item objects
`video`	A YouTube or Vimeo URL, or a video from your library	`{url, video_id, thumbnail}`	`{url, video_id, thumbnail}`
`entity`	Hand-picked reference(s) to other entries	Entry (or array of entries)	Expanded entry object (or array)
`collection`	An automatic, filtered list of entries from a collection	Array of entries	Array of entry objects
`template`	Choosing a Liquid template	`{template}` (handle)	`{template}` (handle)
`number`	Integers or decimals	Number	Number
`toggle`	On/off	Boolean	Boolean
`enumerate`	One choice from a fixed list	String	String
`list`	A repeatable list of text items	Array	Array
`dictionary`	Key/value pairs	Object	Object

In the examples below, the entry belongs to a collection with handle posts, so a template reads its fields as {{ posts.<field_handle> }}. API responses include each field as a top-level key named by its handle. When you create or update a blueprint through the API or MCP, use the type names above, such as rich_text.

Options every field accepts

Every field has a handle, a display label, a type, a position and an options object. {% form_for %} reads these options when a field is rendered in a public form:

Option	Purpose
`required`	The form rejects a submission that leaves this field empty.
`placeholder`	Placeholder text for the input
`help_text`	Hint shown with the input
`input_type`	HTML input type, such as `email` or `tel` (default `text`)

Text fields

text

Single-line plain text for titles, names, short descriptions and meta descriptions. Text fields are included in full-text search.

<p class="lede">{{ posts.excerpt }}</p>

API: "excerpt": "A short summary"

rich_text

Formatted content from the visual editor: headings, lists, links, bold and italic text, and embedded attachments. The value is an HTML string. Rich text is included in search, and the first rich-text field supplies the full content of an entry's feed item.

<div class="prose">{{ posts.body }}</div>

API: send and receive an HTML string, for example "body": "<p>Hello</p>".

raw_html

HTML that is stored and output exactly as entered, with no editor changes and no sanitising. Use it for embed codes, custom markup or content imported from another system where the exact HTML matters. Only put trusted content in this field: any scripts in it will run on your site. Tags are stripped for search indexing. If an entry has no rich-text field, its raw HTML field supplies the feed item content.

{{ posts.embed_code }}

Media fields

image

A single image, uploaded or picked from your files. The value is the image's URL path as a string, not an object, so use the field directly. {{ posts.hero_image.url }} renders nothing.

{% if posts.hero_image %}
  <img src="{{ posts.hero_image }}" alt="{{ posts.title }}">
{% endif %}

API response: a path such as "/rails/active_storage/blobs/redirect/…/photo.jpg". To set an image, send an asset ID (actast_…), a filename, or a folder/filename path of an asset you have already uploaded. See the Assets API.

gallery

An ordered set of images or videos. Options: max_items, the most items the editor lets you add (default 20).

The value is an array of items. Each item has type, url, id, thumbnail, filename, width and height. Keys without a value are left out.

{% for item in posts.photos %}
  <img src="{{ item.url }}" width="{{ item.width }}" height="{{ item.height }}" alt="">
{% endfor %}

video

A video URL (YouTube, Vimeo or a direct link) or a video picked from your video library. The value is an object with url, video_id and thumbnail. Pass the URL to the video_player filter, which renders a YouTube or Vimeo embed, or the built-in player for other videos:

{{ posts.intro_video.url | video_player }}

API: send a URL string ("intro_video": "https://youtu.be/…") or an object {"url": "…", "video_id": "…", "thumbnail": "…"}. Responses always return the object.

Relationship fields

entity

A reference to one or more entries that an editor picks, such as an author, a category or a parent page.

Option	Purpose
`collection_id`	Limits the picker to entries from one collection. If it is not set, the picker offers entries from all collections.
`multiple`	`true` allows several entries. Default `false`.

In Liquid, a single entity field gives you the referenced entry itself, with title, handle, content_path, published_at and all of its own fields. A multiple field gives you an array of entries.

By <a href="{{ posts.author.content_path }}">{{ posts.author.title }}</a>

{% for tag in posts.tags %}<span>{{ tag.title }}</span>{% endfor %}

API response: the referenced entry expanded as an object with id, title, handle, its field values, content_path and published_at. A multiple field returns an array. To set the field, send an entry ID (cnety_…), "collection_handle:entry_handle", a bare entry handle, or an array of entry IDs for a multiple field.

An entity field can also be part of a URL. A routing pattern such as courses/:course/lessons/:handle uses the handle of the entry referenced by the course field. See Routing.

collection

A list of entries that is worked out when the page renders, such as "latest five news posts" or "all events that reference this entry". Nobody has to maintain it by hand.

Option	Purpose
`collection_handle`	Default source collection. Each entry can pick a different one.
`max_items`	Maximum entries returned (default 10)
`default_filter_field`	Handle of a field on the source entries to filter by
`default_filter_value`	Value(s) to match, separated by commas. `{{self}}` stands for the current entry's handle. `true`/`false` match toggle fields.
`default_filter_operator`	`equals` (default) or `not_equals`
`default_orderable`	`no` (use the collection's ordering), `ascending` (oldest first) or `descending` (newest first)

Filtering on an entity field matches entries that reference the given entry. For example, on a Course entry, default_filter_field: course with default_filter_value: {{self}} lists that course's lessons. Editors can override the filter and ordering on each entry.

{% for lesson in courses.lessons %}
  <a href="{{ lesson.content_path }}">{{ lesson.title }}</a>
{% endfor %}

API response: an array of expanded entry objects, in the same shape as entity fields.

template

Lets an editor choose one of your Liquid templates, for example to pick a section layout. The value is an object whose template key holds the chosen template's handle:

{% if posts.sidebar.template == "sidebar_wide" %}…{% endif %}

API: send a template handle or ID (tmplt_…). Responses return {"template": "sidebar_wide"}.

Value and choice fields

number

A numeric value, such as a price, a quantity or a rating.

Option	Purpose
`number_type`	`decimal` (default) or `integer`. Integer values are rounded to whole numbers when saved.
`decimal_places`	For decimals, the number of places to round to when saving. Leave empty for no rounding.

Values that are not numbers are saved as empty (null).

{{ products.price | money }}

toggle

A true/false switch that defaults to false. The API accepts true/false or equivalents such as "true" and "1".

{% if posts.featured %}<span class="badge">Featured</span>{% endif %}

enumerate

One value chosen from a fixed list of strings.

Option	Purpose
`enumerations`	The allowed values, as an array of strings, for example `["draft", "review", "final"]`
`display_as`	`select` (dropdown, default) or `radio` (radio buttons)

The value is the chosen string:

<article class="status-{{ posts.status }}">

Structured data fields

list

An ordered list of text items, such as bullet points, features or ingredients. Options: max_items (default 10).

<ul>{% for feature in products.features %}<li>{{ feature }}</li>{% endfor %}</ul>

API: an array, for example "features": ["Fast", "Hosted"].

dictionary

Key/value pairs, such as specifications or social links. Options: max_items (default 10).

<dl>{% for pair in products.specs %}<dt>{{ pair[0] }}</dt><dd>{{ pair[1] }}</dd>{% endfor %}</dl>
Weight: {{ products.specs.weight }}

API: an object, for example "specs": {"weight": "2 kg", "color": "Blue"}.

Notes

A field with no saved value is nil in Liquid and null in the API. Wrap optional fields in {% if %}.
In globals and navigation items, entity and collection values are plain objects with the same keys as entries (title, handle, content_path and the entry's fields).
Entries never have a .url property. Link to them with content_path.
Only text, rich_text and raw_html fields are indexed for full-text search.
Changing a blueprint's fields through the API or MCP replaces the whole field list. See Blueprints API.