Content types and Page templates

Every content record in Typeroll CMS is a Page. An article, checklist, product, team profile and homepage use the same editor, history, preview, publication states and API. A Content type supplies custom fields, a URL pattern and an optional default Page template.

This model requires Core 0.2.0 and MCP 0.45.0. Existing installations must complete the unified Pages migration before starting that Core version.

For the concepts, read Pages, blocks and templates. For a complete walkthrough, follow Create a Page template. This reference covers the schema, permissions and API details.

In the editor

Open your site and choose Pages to see all content. Filter by content type or publication status. Choose Content types to create or edit a type. Each page already has its title, slug, block body, SEO settings and status; do not add duplicate custom fields for these values.

On a saved page, use Content type in its metadata to change type. Save or discard pending edits first. The page keeps its identity, body, status and existing URL. Fill in the new type’s required fields before saving the change. Fields removed by the change remain in revision history.

Create a content type

{
  "name": "articles",
  "label_singular": "Article",
  "label_plural": "Articles",
  "route_template": "/articles/{slug}",
  "fields": [
    { "name": "excerpt", "label": "Summary", "type": "textarea" },
    { "name": "featured_image", "label": "Cover image", "type": "image" },
    {
      "name": "related",
      "label": "Related pages",
      "type": "page_ref_list",
      "ref_content_type": "articles"
    }
  ]
}

Send this to create_content_type or POST /api/v1/sites/{siteId}/content-types. Type IDs use lowercase letters, digits, hyphens and underscores. Custom field IDs use lowercase letters, digits and underscores, starting with a letter. Display labels can use any language.

Create each article with create_page: pass content_type: "articles", common metadata at the top level, custom values in fields, and its body in blocks. The returned Page ID is used for every later read, edit, preview and deletion.

list_content_types, read_content_type, update_content_type and delete_content_type manage definitions. A type cannot be deleted while Pages use it. change_page_content_type reassigns a saved Page; an explicit fields object replaces its entire custom-field set, so review it before submitting.

URLs

route_template can contain {slug} and custom field tokens, such as /products/{category}/{slug}. A Page’s explicit path overrides the pattern. Migrated pages keep explicit paths so a later schema edit does not silently move existing URLs. A type with an empty pattern has no public detail pages; its records can still supply data to other Pages.

Fields and references

Fields support text, rich text, numbers, booleans, dates, images, files, URLs, choices, objects and arrays. page_ref and page_ref_list refer to Page IDs; ref_content_type optionally limits the selectable type. References do not create a second content store.

required marks a completeness requirement. rendered: false prevents a custom field from reaching public rendering. writable_by can restrict edits to portal, owner, agent, app or import. Rejected ownership conflicts return HTTP 409. page_field_rules configures write authority for supported common metadata, including title, author and SEO fields.

API keys and MCP write with the same authority as an editor in the portal. They may write every field that writable_by opens to portal or agent, and a value written through the portal, the API or MCP can be replaced through any of them; the latest edit wins. agent also covers machine passes inside Typeroll, such as the portal chat assistant and AI workflows: they never replace a value an editor set. Replacing a value the listed business set itself through its edit link needs override_reason on the write, in the portal and the API alike.

Shared templates

Use Templates → New template or create_page_template. Choose a starting layout (article, blog, checklist, team, events, products, profile, landing or custom) or supply a block tree. Templates use template/page_title, template/page_featured_image, template/page_date and template_content_slot. The content slot renders the Page’s own body blocks; its width is configurable.

Assign the template ID to the content type’s template. Individual Pages can choose their own template. list_page_templates, read_page_template, update_page_template and delete_page_template expose the same operations to agents. Block tools address templates with target: { kind: "template", id }.

Template bindings use {{page.title}}, {{page.excerpt}} and other Page fields. Every Page has a built-in excerpt; a type that defines its own excerpt field stores it there instead (see Page excerpt). Inside a repeater, {{item.title}} refers to the current listed Page.

Listings and related content

Add core/page_list with content_type: "articles" to any Page. The listing reads saved Pages at preview/build time, so adding, changing or deleting an article is reflected on the next build without regenerating listing HTML. Set sort_by, sort_order, limit or paginate to control the list.

Related and backlink repeaters use Page reference fields. Content types can also declare facets for generated topic listing pages. These are derived routes; the editable source remains the same Page records.

Versions and saving

Pass the same version to type, template and Page operations when working on a site branch. Definitions and saved Pages inherit from the base version until changed. Working copies stay local to the selected version.

Page content edits require save: true or commit_working_copy. Structural operations, including changing type or editing a template definition, are saved immediately. Publishing builds saved content only.

Sorting and template choices

Content types and templates have separate roles: the type defines fields, URL patterns and listing defaults; a template presents a Page’s body and metadata. Several templates can use the same content type, and compatible templates can be reused across types. A listing’s card/row layout is independent of the detail Page’s template.

In Content types → select a type, set Default sort field and direction. Listings without their own sort setting and previous/next links use that order. Use Manual page order and set Page order in each Page’s metadata for authored ordering. Lower numbers come first in ascending order; empty values come last and Page IDs break ties consistently. Explicit listing sort settings override the default; explicitly selected Page IDs retain their supplied order. The Pages overview groups types and uses each type’s order within its group.

Under Page templates, optionally enable Limit the templates editors can choose, select the allowed templates and choose Default template. The default must be included in that selection. Without a restriction, all compatible templates are allowed. Only published templates appear in the Page editor’s choices. On a Page, select an alternative under Template, or choose Use content type’s default template, then save the Page. Inherited choices follow future default changes; explicit choices stay attached to their template. Content type definitions save immediately; Page template choices and manual order use the Page’s working copy and Save/Discard flow.

API/MCP fields: ContentType.sort_field, sort_dir, template and allowed_templates; Page.sort_order and template. An absent or null allowed_templates permits all compatible templates, while [] permits none. Set a Page’s template to null or an empty string to restore inheritance; set sort_order to null to clear manual order. update_page (PATCH) accepts sort_order on its own; like other content edits it lands in the working copy until saved. read_page, batch_read_pages and list_pages return it. list_pages with content_type inherits its order; sort_by/sort_order override it. Unfiltered API lists use stable Page IDs unless a sort field is specified. Keep query settings unchanged while following pagination cursors.

The same rules apply to UI, API and MCP writes in the selected site version. The server rejects incompatible or missing templates, removal of templates that are still configured, and allowed-list changes that invalidate saved Page overrides. A working copy is checked again when saved. Changing type preserves an explicit template only if the new type allows it; reset the Page to its current default and save before changing to an incompatible type.

Structured field and SEO contracts (Core 0.2.8)

multiselect stores unique strings from required options; email and url are supported string fields. facet_combinations is an array of two-element field-name arrays. schema_field_mode: "mapped" limits automatic JSON-LD to explicit schema_field_map entries and the canonical envelope. Core 0.2.121 and later also accept Page metadata dates as explicit sources: "date_published": "datePublished" and "date_updated": "dateModified". This keeps article dates without adding the body or unrelated fields; see SEO and indexing. Pages, typed fields, list blocks, facets and JSON-LD mapping are generic CMS features. Product-specific app recipes are available through read_app_documentation when the relevant app is installed and enabled.

Present structured fields

Use the native Page field list in a shared Page template to show labels and typed values without empty rows. Select options use their display labels; individual rows can have custom HTML and CSS. Field values remain on the Page, and rendered: false always prevents public output. This requires Core 0.2.12 and its renderer capability.

Structured-data mapping limits

schema_field_map accepts direct properties, for example {"website":"url"}. For Product and SoftwareApplication types, price, currency and rating fields are published inside offers and aggregateRating; see products and software. Dotted properties and reserved prototype keys are rejected on save. Existing unsupported maps must be reviewed before publication; their content fields are not deleted. See Publication checks.