# Designing a content type

URL: https://kywi-docs-production.up.railway.app/developing/designing-a-content-type
Type: docPage

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.

{ 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'] }, ], }

## kywi.config.ts

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.

## Only the Type Designer enforces the list — config does not

Adding a field through the admin returns `409 CONFLICT`: `'slug' is a built-in field name and cannot be used for a custom field`. The config validator has no such check. A field named `slug` in `kywi.config.ts` loads cleanly, gets a `slug` column in the type's table, and is then **silently dropped from the editor** — the content form filters reserved names out of the custom-field list rather than rendering a second input for a value it cannot own. You get a column nothing writes to and no error anywhere. Check the name yourself before you declare it.

## 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](/developing/access-control-in-kywiconfigts/) and [Hooks: content-type hooks and the event bus](/developing/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](/developing/config-types-type-designer-types-and-extension-attributes/) is the choice between them.
