Skip to content

The files under jtk/ ​

What a site's repository holds under jtk/, file by file, in the shape the platform reads and writes them. You can seed a repository before anybody opens the panel, and an import reads back exactly what you wrote. This is contract 3, the contract every new site is written in, and npx @jtakeit/astro create lays it out. A site made before 12 November 2026 may still be on contract 2. Its files are at the end, and nothing new is written that way.

jtk/
  schema.json                          the schema: what the owner may edit — yours, written by `jtk schema`
  pages/index.json                     a page, named for its address: `/` is index.json
  pages/prices.json                    /prices
  pages/prices.en.json                 its English, beside it — a translation
  entries/services/manicure.json       an entry of the collection `services`
  entries/services/manicure.en.json    its English
  shared.json                          the text on every page: the contacts, a footer note
  shared.en.json
  modules/bookings.json                the diary's settings, when the schema turns bookings on
  site.json                            the platform's, to the site: its id, slug, media host, currency
  design.json                          the template's own: the editor's chrome

What every file keeps to ​

  • The directory is the kind. A page is under pages/, an entry under entries/<collection>/, a module's settings under modules/. A file under any of them says what its place says. A path, collection or slug that disagrees with the file's place is refused with JTK_E_DOCUMENT_INVALID.
  • One identity per thing, minted once. A page and an entry have an id, a lowercase UUID (version 7 when new). A block, a row of a list and a picture of a gallery have a _key: a lowercase letter, then lowercase letters, digits and hyphens, up to 32. Nothing is named by its place in a list. npx @jtakeit/astro schema (jtkit schema on another generator) mints every name a file lacks, and so do the platform's saves. A file written by hand without them is refused (JTK_E_UNNAMED, JTK_E_DOCUMENT_INVALID).
  • Empty is absent. Leave a value nobody wrote out of the file. Never write null, "" or []; an import folds them away.
  • No key a document has not got. A key that is neither the file's own nor a field the schema declares is refused. Inside an object the reserved keys are _key and _orphans, and in a block also type, v and view; any other _ key is refused.
  • Values are what their kinds say (field kinds). A price is {"minor": 4500}, a picture {"src": …, "alt": …}, a reference the entry's id. Contract 2's shapes — a bare number, a picture's key, a slug — are refused here.
  • One form. The platform writes a file as JSON.stringify(value, null, 2) does, with one newline at the end. The top-level keys come in the order this page gives. In every object below them, _key, type, v and view come first, the rest in byte order, and _orphans last. A file you wrote that says the same as the save would is kept byte for byte, so the form is the platform's habit, not your rule.
  • Whose each file is. The schema is yours. site.json is the platform's. Pages, entries, the shared text and a module's settings are the owner's, through the three stages: you seed them, import_branch reads them into the panel, and every save writes them back as a commit. Records — enquiries, bookings, orders — are never in git.

A place in a file is named by keys in an annotation, data-jtk-path, and in a translation. The kit's door writes the annotations, so a template never spells one:

placenamed
a field of a block on the pageblocks[hero].title
a field of a rowblocks[faq].items[r7k2].answer
a part of a pictureblocks[hero].image.src, blocks[hero].image.alt
an entry's own value, on its own pagetitle
an entry's value where it is listedentry:0193a5c3-…:title
another page's blockpage:0193a5c2-…:blocks[hero].title
the shared textshared:blocks[contacts].phone
a module's settingmodule:bookings:hours[mon].opens

schema.json — the schema ​

The site's declaration of what its content is made of: the schema format. On the scaffold, npx @jtakeit/astro schema writes it from src/content/blocks.ts, which says CONTRACT = 3. On another generator you write it by hand or with your own tool. The platform reads it and never writes it.

pages/<path>.json — a page ​

A page at its address: / is pages/index.json, /prices is pages/prices.json, and /team/anna is pages/team/anna.json. The keys come in this order:

json
{
  "id": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
  "path": "/prices",
  "name": "Preise",
  "seo": { "description": "Was ein Termin bei uns kostet.", "title": "Preise" },
  "blocks": [
    {
      "_key": "hero",
      "type": "hero",
      "v": 1,
      "image": { "alt": "Der Salon am Morgen", "focus": "50% 30%", "src": "media/2f0c…/a1b2c3d4.jpg" },
      "title": "Preise"
    },
    {
      "_key": "list",
      "type": "priced_list",
      "v": 1,
      "items": [
        { "_key": "r7k2", "price": { "from": true, "minor": 4500 }, "title": "Haarschnitt" }
      ]
    }
  ]
}
  • id is the page's own and never changes. An import knows a file by it, so a file moved or renamed in git is the same page at its new address, with its history. When the version at the new address goes live, the platform sends the old address on to it (301), so no redirect of your own is needed. A new file may carry a fresh UUID; jtk schema mints one where there is none.
  • path is the address, and it agrees with the file's place.
  • name is what the panel calls the page — Preise, Team, Kontakt — in the site's own language. It is required, and a page without one is refused. Visitors never see it, and the owner may rename it.
  • seo holds the fields the schema's page_seo declares. Leave it out for none.
  • blocks are the page in order. Each block carries its _key, its type, its type's v, view if its type has views, and then its fields' values. A block at an older v is brought up by its type's upcast steps when it is read, and the next save writes the current one — upcasters.

A block may also carry _orphans: the values of fields the schema no longer declares, kept so that a field renamed or removed in the schema loses nothing. A page draws nothing from it. Leave it where it is, and delete a key from it only to drop that value on purpose.

entries/<collection>/<slug>.json — an entry ​

An entry of a collection: its directory is its collection and its file name is its slug. Its address is the collection's route with the slug in it, so /services/manicure for {"detail": "/services/{slug}"}. An entry of a collection with route: "none" has no page and no address. It is shown where shown_on says, /prices#manicure, and read by the diary.

json
{
  "id": "0193a5c3-0a11-7d02-9f3c-1e2d3c4b5a71",
  "collection": "services",
  "slug": "manicure",
  "rank": "a0",
  "visible": true,
  "fields": {
    "costs": { "minor": 4500 },
    "takes": 60,
    "title": "Manicure"
  }
}

The keys come in this order: id, collection, slug, rank, visible, show_at, hide_at, seo, fields and blocks.

  • fields holds the entry's own values, the fields of its collection's type. They are annotated on its own page by their keys alone (title), and wherever the entry is listed as entry:<id>:title. Because the values sit under fields, a field may take any name, collection and slug included.
  • blocks is the entry's body, of the block types the collection's blocks allows: a post's paragraphs and pictures. Leave it out for an entry with none.
  • rank is the entry's place in a collection ordered by hand, which is the default: a short key compared as bytes (a0 < a0V < a1). The owner's moves in the panel write it. Read it and do not renumber it; an entry without one comes after the ranked ones. A collection ordered by a field has no rank.
  • visible is always written: whether the owner shows the entry. An entry the owner takes off the site or puts back in the panel is built as they said from the next build on, and the next save writes the same visible into the file. An entry with a page of its own that the owner hides or deletes in the panel may send its address somewhere — its listing by default — and the platform redirects it, as it does an address an entry moved from; the owner sees and changes these in the panel (the panel). Write no redirect of your own for them.
  • show_at and hide_at are moments in RFC 3339 and UTC — "2026-12-01T00:00:00Z" — for an entry meant to appear later or to go on a date. Outside its window the entry is treated as hidden: it is off the listing, the feed, the sitemap and the diary, and the edge answers a visitor 404 at its address while the people editing the site still see it. The platform builds the saved commit a few minutes ahead of the moment and points the site at it when the moment comes. A hide_at not after the show_at is refused. On a collection whose entries are over by their date (ends_by, the schema) write the date, never a moment: the platform works out when each is over, and with then: hide its hide_at too. Never compare the date with today in the template — read ended.
  • seo is only for an entry with a page of its own, and it holds the same fields as a page's.

A body field is markdown inside the JSON, never a .md file. Entries were markdown with frontmatter once, and an import refuses that shape by name.

An entry of a collection a module books — a service, a master, a car — is in every language, always (translations).

shared.json — the text on every page ​

One document, with no id and no address: the blocks of the types the schema's shared lists, usually one contacts block whose fields say their role. The structured data a search engine reads is built from those roles. A shared field is annotated wherever it is drawn as shared:blocks[contacts].phone.

json
{
  "blocks": [
    {
      "_key": "contacts",
      "type": "contacts",
      "v": 1,
      "city": "Winterthur",
      "email": "praxis@example.ch",
      "name": "Orthopädie Bischofsberg",
      "phone": "+41 52 350 91 25",
      "postal_code": "8400",
      "street": "St. Georgenstrasse 6"
    }
  ]
}

modules/<module>.json — a module's settings ​

The module's own document: v, the version of its settings, and settings, whose keys the modules reference lists. Every row of a list in it has its _key. Seed it in the commit. npx @jtakeit/astro schema writes an empty one when the schema turns the module on. import_branch reads it into the diary, so the preview takes bookings before anybody opens the panel. The owner changes it under the diary afterwards, and the next save writes it back.

json
{
  "v": 1,
  "settings": {
    "cancel_until": 1440,
    "closed": [
      { "_key": "xmas", "from": "2026-12-24", "until": "2027-01-03" }
    ],
    "confirm": "auto",
    "hold": 1440,
    "horizon": 60,
    "hours": [
      { "_key": "mon", "closes": 1080, "day": "monday", "opens": 540 },
      { "_key": "tue", "closes": 1080, "day": "tuesday", "opens": 540 },
      { "_key": "fri", "closes": 1020, "day": "friday", "opens": 540 }
    ],
    "lead": 120,
    "page": "/book",
    "party": 1,
    "payment": "no",
    "slot_every": 30,
    "zone": "Europe/Zurich"
  }
}

Times of day are minutes from midnight (540 is 09:00), durations are whole minutes, and money is {"minor": …}. A closing time before the opening one is after midnight, so a bar's Friday of 18:00–01:00 is one row. deposit is a share of the price, 1–100, and belongs only beside "payment": "deposit". A zero is refused, so leave it out when nothing is paid up front. Anything beside v and settings, or a value a setting's kind refuses, is refused with JTK_E_DOCUMENT_INVALID. CI judges this example with the same judge import_branch applies, so it cannot go stale.

<name>.<locale>.json — a translation ​

A page, an entry, the shared text or a module's settings in another of the site's languages is a file beside its original: pages/prices.en.json, entries/services/manicure.en.json, shared.en.json. It holds only the words, named by the original's keys. A value that is the same in every language is never in it. Translations has the file, which values belong in it, and how the platform tells what is missing and what is outdated.

site.json — the platform's file ​

The platform writes it on every save: the site's id, its slug, where the owner's uploads are served from, and its currency. Do not seed id. An import reads back only currency, and only while the site has none, as create_site takes it. Once the site has a currency, a person changes it in the panel (The site → The business). An import or a validate_schema that brings another currency is refused with JTK_E_CURRENCY_SET. The business's name, address and phone are not here. They are content, in shared.json.

json
{
  "id": "05d84518-b91f-44be-85a4-e2cb1ed11a13",
  "slug": "orthopaedie-bischofsberg",
  "media_base": "https://media.jtakeit.com/",
  "currency": "CHF"
}

design.json, and dist/_meta.json ​

design.json is the template's own file, not the contract's: the editor's chrome (the field, the ground, the accent). The scaffold ships an empty one that the panel fills.

dist/_meta.json is written by the site's build, not committed under jtk/. It says redirects ([{"from": "/old", "to": "/new", "status": 301}]), immutable (the directories whose files are named by their contents) and cache ([{"prefix": "/clips/", "maxAge": 86400}]), and nothing else. Which entries a visitor may not see is the platform's to say, so contract 3 has no drafts. Anything else is refused with JTK_E_META_INVALID.

Contract 2, the older contract ​

A site made before contract 3, and not yet moved, keeps these files. The platform's team moves such a site with jtk upgrade contract-3, in one commit. Never start a site in them. A tree that holds both jtk/schema.json and jtk/catalogue.json is refused.

jtk/
  catalogue.json                    the schema, "contract": 2 — written by `jtk catalogue`
  content/index.json                a page, {id, path, name, seo, blocks}
  content/de/prices.json            a page in another language: a full copy at /de/prices
  content/services/manicure.json    an entry under its collection's prefix
  shared.json, shared.de.json       the text on every page
  bookings.json                     the diary's settings, one bookings_config block
  site.json                         the platform's, with the business's facts under `business`

On contract 2, an entry is {path, collection, visible, seo, blocks}, and its own values are the fields of blocks[0]. A file under a collection's prefix without collection is refused with JTK_E_ENTRY_NO_COLLECTION. Values take contract 2's shapes: a price as a bare number of minor units, a picture as its key with its description in a sibling <key>_alt field, and a reference as a slug. A place is named by position, blocks[0].title.

bookings.json, contract 2 ​

One block of type bookings_config, whose fields are the same settings, in the shape a save writes. Anything else is refused with JTK_E_MODULE_FILE_INVALID.

json
{
  "blocks": [
    {
      "type": "bookings_config",
      "v": 1,
      "zone": "Europe/Zurich",
      "slot_every": 30,
      "confirm": "auto",
      "payment": "no",
      "hours": [
        { "day": "monday", "opens": 540, "closes": 1080 }
      ]
    }
  ]
}