Content types and fields

A content type is the shape of one kind of content — a Post, a Recipe, an Event. You define content types in the admin, give them typed fields, and Cusp wires up the editor form, the public permalink, and the REST endpoint for you. There is no schema file in the repository and no redeploy: the shape of your content lives in your own database, and you change it from the browser.

Collections and documents

In Cusp a content type is a collection, and a single entry is a document. A fresh install ships two collections — Posts and Pages — and you add as many of your own as you like from the Content types screen. Each collection carries four things: a slug, a singular and plural name, an optional hierarchy, and a permalink pattern.

• Slug — lowercase letters, digits, and underscores. It names the collection in URLs and in the REST API (/api/v1/{slug}). It is set once at creation and cannot be changed afterwards, so choose it deliberately.
• Names — the singular and plural display names (Recipe / Recipes) used throughout the admin.
• Hierarchy — tick "hierarchical" if documents can have a parent, the way Pages nest. Most collections are flat.
• Permalink pattern — the public URL shape, using {slug} for the document's own slug and, for hierarchical types, {parent} for its parent's. A few prefixes are reserved (/api, /admin, /login, /setup, and the like) and rejected.

Create a content type

Open Content types in the sidebar and choose New content type. Fill in the slug, the singular and plural names, and the permalink pattern, tick hierarchical if you need it, and save. The collection is immediately live: it appears in the sidebar, its public listing renders, /api/v1/{slug} starts answering, and you can create documents in it. You never edit a config file or run a migration by hand to get here.

Add fields

Open a content type and choose Add field. Pick a type, give the field a name — the label editors see — and a slug, which is its key in the document's data and in the API. Fields render as a form above the block editor, ordered by position; drag to reorder them. A document always has a title and a slug; the fields you add are everything else that makes it structured data rather than a wall of prose.

Seven field types are available today:

• Text — one line of plain text.
• Rich text — a formatted passage with headings, links, and lists, stored as Portable Text.
• Number — whole or decimal numbers.
• Boolean — true or false.
• Date — a calendar date.
• Media — an image picked from the Media library.
• Reference — a link to another document.

Each type carries its own options — length bounds on text, a minimum, maximum, and integer-only switch on numbers, a date that can default to today, a maximum size on a media field (which is always image-only), and a reference pointed at a target collection. The field types reference lists every option and which types you can filter and sort on through the API.

Repeating and structured fields

A repeater field holds a list of repeating sub-fields — a recipe's ingredients, a page's list of links. Repeater fields are editable directly on the document form: add a row, fill its columns, remove a row, or reorder them, and the structured array round-trips to the API and your theme. The editor infers the row's columns from the data that is already there, or lets you name the first sub-field when you start from empty.

Defining a brand-new repeater field — and the related group and block field types — is still gated as experimental in the content-type builder, because the visual sub-field-schema builder is on the roadmap. Those three types appear in the picker marked "experimental — not yet editable" and cannot yet be added to a content type. Any data already stored in them is preserved, and for repeater fields it is fully editable on the form.

Changing a field later

You can rename a field, adjust its options, or change its type after documents exist. Changing a field's type on a populated collection runs the MigrateField workflow, which rewrites every document's value into the new type and applies a fallback for values that cannot convert cleanly. Because every step is a versioned write, the migration is auditable and you can roll back the affected entities through version history.

Everything is versioned

Collections and field definitions are versioned entities, exactly like your documents and settings. Rename a field and the previous shape is preserved; restore an earlier version of a content type, or time-travel the whole site to a past moment, and the schema travels with the content. The shape of your data has the same complete history as the data itself.