Appearance
Field kinds
There are 19, and the set is closed. Each one costs a validator on the server, a form control in the admin, a zod schema in the browser and a rule in the annotation lint — so the twentieth is a decision rather than a convenience, and a site's schema naming one that is not here is refused with JTK_E_KIND_UNKNOWN. sku and picks are contract 3's alone; the older contract 2 has the other 17.
min and max do not mean one thing. They count characters for text, the value itself for a number, and items for a list or a gallery. The column below is the whole answer; getting it wrong is the most common mistake in a first schema. Absent is unbounded, and 0 is a bound.
Per language is whether a translation holds the value: the words are per language and the facts are one value in every language, by the kind, unless the field says localized — which a field may say only where the column says what it changes (translations). A translation that holds a value that is not per language is refused with JTK_E_TRANSLATION_SHARED.
Tappable is whether an element rendering the value must carry a data-jtk-path: every value a page draws, a list by its rows and a switch by what it switches, so the owner taps whatever they see. A value the page does not draw — a link behind a button, an hour a countdown counts to — is no_tap_target and needs none. Where the column says advice, a value drawn without its path is JTK_W_UNANNOTATED_FIELD for now, not a refusal.
At a glance
| kind | in the file | min / max count | per language |
|---|---|---|---|
text | string — "Haircut" | characters | yes; localized: false: one value |
textarea | string, line breaks kept — "Line one\nLine two" | characters | yes; localized: false: one value |
richtext_lite | string — "A **short** passage" | characters | yes; localized: false: one value |
markdown | string of markdown — "# Title\n\nText" | characters | yes; localized: false: one value |
number | JSON number, never quoted — 3; whole where the field says integer | the value | no |
money | {"minor": 4500} — whole minor units, ≥ 0: 45.00 in the site's one currency; "from": true or "on_request": true beside it where qualifiers allow | the value, in minor units | no |
duration | whole number of minutes, ≥ 0 — 60 | the value, in minutes | no |
ref | string: the id of an entry of a collection in ref.to — "0193a5c3-0a11-7d02-9f3c-1e2d3c4b5a71"; with many, a list of ids | — | no |
time_of_day | whole number of minutes from local midnight, 0–1439 — 540 is 09:00 | minutes from midnight | no |
bool | true or false | — | no |
select | string, the value of one of options — "daily" | — | no |
tel | string as written — "+41 44 123 45 67" | characters | no |
email | string, one address — "hello@example.ch" | characters | no |
url | string, http(s), /path, #fragment, mailto: or tel: — "/kontakt#form" | — | no; localized: true: the whole value |
date | string YYYY-MM-DD — "2026-10-20" | — | no |
media | {"src": "media/…", "alt": "…", "focus": "50% 30%", "poster": "…"}, all but src optional; with multiple, a list of them, each with its _key | pictures, with multiple; one picture takes none | its alt; a gallery, each picture's alt, by _key; localized: true: the whole value |
list | list of rows, each {"_key": "r1", …} with the fields of of; a row may hold one list of its own | rows | the words in its rows, by _key; localized: true: the whole value |
sku | string, a letter or digit then letters, digits, ., _, - — "OAK-TABLE-180" | — | no |
picks | object from an option's _key to one of its values' _key, each a row key — {"size": "s", "colour": "red"}; {} picks nothing | — | no |
On contract 2, the older contract, four values are written otherwise — a price is the bare number, 4500; a reference is the entry's slug, "manicure"; one picture is its key, "media/…"; a list's rows need no _key — and its schema writes a select's options as strings. Every other value is the same in both.
What each one holds
| kind | holds | min / max | tappable |
|---|---|---|---|
text | One line of plain text — a heading, a name, a price as it is written. | Characters, counted as characters rather than bytes — an eighty-character Ukrainian title is eighty. | yes |
textarea | Several lines of plain text — a paragraph, an address. | Characters. | yes |
richtext_lite | A short passage with emphasis and links in it. | Characters. | yes |
markdown | A document: the body of an entry, hundreds or thousands of words. | Characters. | yes |
number | A number — a price, a count, a year. | The value itself: min: 1, max: 5 is one to five, not one to five digits. | yes — advice for now |
money | An amount of money — what a service costs, what a product is priced at. | The amount itself, in minor units — max: 100000 is a ceiling of 1000.00. | yes |
duration | A length of time in whole minutes — how long an appointment takes. | The value in minutes: min: 15, max: 480 is a quarter of an hour to eight hours. | yes |
ref | A reference to an entry of one of the schema's own collections — the service a master does, the range a product is in. | Nothing. The collection is the constraint. | no |
time_of_day | A time on a clock face — when the doors open. | Minutes from midnight, so min: 720 is afternoons only. | yes — advice for now |
bool | A switch — whether a section shows, whether a form is on the page. | Nothing. Bounds mean nothing here. | no |
select | One of a set of choices the schema names. | Nothing. The choices are the constraint. | yes — advice for now |
tel | A telephone number as it is written on a sign. | Characters. | yes — advice for now |
email | One email address. | Characters. | yes — advice for now |
url | A link. | Nothing. | yes — advice for now |
date | A day, as YYYY-MM-DD. | Nothing. | yes — advice for now |
media | A picture or a clip — one, or a gallery of them with multiple. | With multiple, the number of pictures. One picture takes none on contract 3; on contract 2 they counted the characters of its key, which is almost never what anybody means. | yes |
list | Rows of fields — three cards, five steps, a table of prices. | The number of rows. | no |
sku | A product's stock-keeping code — OAK-TABLE-180. Contract 3's alone. | Nothing. The pattern is the constraint. | no |
picks | A variant's choice among its product's options, by key — {"size": "s", "colour": "red"}. Contract 3's alone. | Nothing. The shape is the constraint. | no |
text
One line of plain text — a heading, a name, a price as it is written.
Refused: Text, and nothing else. A number arrives as a number and is refused.
min and max: Characters, counted as characters rather than bytes — an eighty-character Ukrainian title is eighty.
Per language: yes; localized: false: one value
Tappable: yes
textarea
Several lines of plain text — a paragraph, an address.
Refused: Text. Line breaks are kept; markup is not interpreted.
min and max: Characters.
Per language: yes; localized: false: one value
Tappable: yes
richtext_lite
A short passage with emphasis and links in it.
Refused: Text. The editor limits which marks exist; the server checks the length.
min and max: Characters.
Per language: yes; localized: false: one value
Tappable: yes
markdown
A document: the body of an entry, hundreds or thousands of words.
Refused: Text, written as markdown. It is committed to the repository as markdown and rendered by the site's own pipeline.
min and max: Characters.
Per language: yes; localized: false: one value
Tappable: yes
number
A number — a price, a count, a year.
Refused: A JSON number. A numeral in quotation marks is refused rather than converted, because coercion is how a price becomes the string "0". On contract 3 a field that says integer takes whole numbers only.
min and max: The value itself: min: 1, max: 5 is one to five, not one to five digits.
Per language: no
Tappable: yes — advice for now
money
An amount of money — what a service costs, what a product is priced at.
Refused: An amount in whole minor units, {"minor": 25000} for 250.00 — with "from": true or "on_request": true beside it where the field's qualifiers allow. A fraction of a minor unit is refused, and so is a negative amount. The currency is the site's and is not part of the value. Contract 2, the older contract, writes the bare number, 25000.
min and max: The amount itself, in minor units — max: 100000 is a ceiling of 1000.00.
Per language: no
Tappable: yes
duration
A length of time in whole minutes — how long an appointment takes.
Refused: A whole number of minutes, never negative. Minutes are the unit slot arithmetic works in, so nothing converts it on the way.
min and max: The value in minutes: min: 15, max: 480 is a quarter of an hour to eight hours.
Per language: no
Tappable: yes
ref
A reference to an entry of one of the schema's own collections — the service a master does, the range a product is in.
Refused: The id of an entry of a collection the field's ref: {to: […]} names — with many: true, a list of ids. Refused unless that entry exists. A ref into its own collection is a tree — a category's parent — and one that leads back to the entry is refused. Contract 2, the older contract, holds the entry's slug and names one collection, ref: "services".
min and max: Nothing. The collection is the constraint.
Per language: no
Tappable: no
time_of_day
A time on a clock face — when the doors open.
Refused: A whole number of minutes from local midnight, 0 to 1439: 540 is nine in the morning. No zone travels with it — the zone is the site's, declared once.
min and max: Minutes from midnight, so min: 720 is afternoons only.
Per language: no
Tappable: yes — advice for now
bool
A switch — whether a section shows, whether a form is on the page.
Refused: true or false.
min and max: Nothing. Bounds mean nothing here.
Per language: no
Tappable: no
select
One of a set of choices the schema names.
Refused: A string that is the value of one of options, which contract 3 writes as [{"value": "daily", "label": …}]. Anything else is refused.
min and max: Nothing. The choices are the constraint.
Per language: no
Tappable: yes — advice for now
tel
A telephone number as it is written on a sign.
Refused: Digits, spaces and the punctuation a phone number is written with. Deliberately loose: a number is whatever a person writes.
min and max: Characters.
Per language: no
Tappable: yes — advice for now
email
One email address.
Refused: A single address, parsed. A display name beside it is refused — this is an address, not a header.
min and max: Characters.
Per language: no
Tappable: yes — advice for now
url
A link.
Refused: http or https with a host; a page of the site from its root, /kontakt or /kontakt#form; a fragment like #lead-form for somewhere on the same page; mailto: an address; tel: a number. Any other scheme is refused, which is what keeps javascript: out of a client's call to action.
min and max: Nothing.
Per language: no; localized: true: the whole value
Tappable: yes — advice for now
date
A day, as YYYY-MM-DD.
Refused: A calendar date. Times and zones are not part of it.
min and max: Nothing.
Per language: no
Tappable: yes — advice for now
media
A picture or a clip — one, or a gallery of them with multiple.
Refused: One picture is {"src": …, "alt"?: …, "focus"?: "50% 30%", "poster"?: …}, its src a key in our own bucket or a path to a file the repository ships; a gallery (multiple) is a list of them, each with its _key. Never a URL: a field that accepted one would let a client's page be made to load anything from anywhere. Contract 2, the older contract, holds one picture as its key alone, a string.
min and max: With multiple, the number of pictures. One picture takes none on contract 3; on contract 2 they counted the characters of its key, which is almost never what anybody means.
Per language: its alt; a gallery, each picture's alt, by _key; localized: true: the whole value
Tappable: yes
list
Rows of fields — three cards, five steps, a table of prices.
Refused: An array of rows, each checked against of and each with its _key on contract 3. A row may hold one list of its own on contract 3 and none on contract 2: deeper has no form control and no annotation path.
min and max: The number of rows.
Per language: the words in its rows, by _key; localized: true: the whole value
Tappable: no
sku
A product's stock-keeping code — OAK-TABLE-180. Contract 3's alone.
Refused: A letter or a digit, then letters, digits, ., _ and -, sixty-four characters at most. Meant to be unique within its role on the site, and never changed once a record names it.
min and max: Nothing. The pattern is the constraint.
Per language: no
Tappable: no
picks
A variant's choice among its product's options, by key — {"size": "s", "colour": "red"}. Contract 3's alone.
Refused: An object from an option's _key to the _key of one of its values, every key and value a row key: a lowercase letter, then lowercase letters, digits and dashes, thirty-two characters at most. {} is a variant that picks nothing, a product without options. The same in every language. Whether each key names an option of the product, and each value one of its values, is judged by the product's collection, not by the field.
min and max: Nothing. The shape is the constraint.
Per language: no
Tappable: no