Skip to content

Designing a content type

A content type is a base type plus fields that become real columns in its own table — and fifty field names are already taken by the editor.

A content type is a baseType plus a list of fields. The base type decides which behaviour the platform attaches — content, folder, media, event, gallery, link, form or component. The fields decide the shape of one extra table: a type that declares any gets its own kywi_ct_<name>, joined to the base content row by id, with real typed columns rather than a JSON bag.

kywi.config.tsts
{
  name: 'docPage',
  label: 'Doc Page',
  pluralLabel: 'Doc Pages',
  baseType: 'content',
  fields: [
    { name: 'summary', type: 'text', label: 'Summary',
      required: true, validation: { maxLength: 160 } },
    { name: 'surface', type: 'select', label: 'Surface',
      options: ['start', 'editing', 'authoring', 'governing', 'targeting',
                'agent', 'developing', 'integrating', 'operating', 'concepts'] },
    { name: 'persona', type: 'select', label: 'Persona',
      options: ['editor', 'site-admin', 'agent-operator', 'developer', 'operator'] },
  ],
}

Look at that snippet again: summary is on the reserved list two sections down. It is not an oversight — it is this site's own docPage type, unedited, and it is exactly the collision the next callout warns about. It works here only because these pages are never opened in the content editor; the build script writes title/summary/layout straight through the content API, so the admin's "drop it from the custom-field list" behaviour never gets a chance to bite. Reuse this pattern in a type anyone edits by hand and the value becomes unreachable in the UI.

page, folder, link and form are registered as built-ins with no declaration, and the Type Designer refuses to rename or delete them. Everything else is yours to declare. Type names are camelCase starting lowercase; field names are camelCase alphanumeric. No underscores, no hyphens, no leading digit — the validator rejects the config, it does not sanitise it.

Fifty field names are already taken

The content editor keeps every field on a page — Title, Slug, Body, Featured Image, and every Publishing, Navigation, SEO, Layout, Categories, Related and Permissions control — in one flat object keyed by field name, alongside your custom fields. A custom field that reuses one of those names is literally the same value as the built-in it collides with. So the names are reserved: title, slug, body, status, layout, summary, tags, locale, parentId, metaTitle and forty others.

The check is a plain string-set lookup, so it is case-sensitive: Slug is not a reserved name and passes. That is a loophole, not a recommendation — the column it creates is slug after snake-casing, which is the collision you were trying to avoid.

defineContentType turns comments off

The helper spreads commentable: false beneath your object, so a type declared with defineContentType and no explicit commentable rejects comments. The comment route blocks only on an explicit false, so a type declared as a bare object literal — which is exactly what the scaffold emits for its generated page type — leaves the property unset and accepts them. Two type declarations that look identical differ on this the moment one is wrapped in the helper. Set commentable explicitly on any type where it matters.

Types with no natural title

titleRequired: false is the escape hatch for a model whose identity is not a title — a testimonial's person, an FAQ's question. Unset means true, for back-compatibility with every type declared before the flag existed. It governs the admin's Title field: the asterisk and the input's required attribute both read it, in the content form and in the Type Designer.

What a type can only get from code

Three properties hold functions, so they exist in kywi.config.ts and nowhere else: the type's access (read/write/publish/delete predicates), its hooks (validate, the before/after create-update-delete pairs, afterPublish, afterUnpublish), and a field's own access. A type that needs any of them is a config type by definition — see Access control in kywi.config.ts and Hooks: content-type hooks and the event bus. Everything else is available to a type created in the admin; Config types, Type Designer types, and extension attributes is the choice between them.