Skip to content

What changed, by contract ​

The schema's contract is a whole number that answers one question: can this service read this file. It is not a semver, and a minor could never change what the validator does — the toolkit and this documentation carry the semver, and their major names the contract they speak.

Every contract has an entry here. A test refuses a service whose contract number has no section on this page, because a format that moved with nothing written down is a format nobody can be moved off.

A schema written for contract 1 is upgraded to contract 2 on the way in and never rewritten in your repository. Contract 2 and contract 3 are two sets of files, so a site moves from one to the other in one commit, with jtk upgrade contract-3. One written for a newer contract is refused whole, with JTK_E_CONTRACT_UNKNOWN: half-reading it would accept the keys we happened to recognise and silently drop the rest, which is a site quietly losing half its blocks.


Contract 3 ​

12 November 2026: every new site is written in it.

The files. The schema is jtk/schema.json and says "contract": 3. A page is jtk/pages/<path>.json with a required name. An entry is jtk/entries/<collection>/<slug>.json, with its own values under fields and its body under blocks. A module's settings are jtk/modules/<module>.json, {"v": 1, "settings": {…}}. jtk/site.json is the platform's, and its currency is read only while the site has none. The directory is the kind, and a tree holding both schema.json and catalogue.json is refused — the files under jtk/.

One identity per thing. A page and an entry have an id; a block, a row and a gallery's picture have a _key. Annotations, references and translations name things by these, never by position: blocks[hero].title, entry:<id>:title, a ref holding an entry's id.

The schema refuses every key it has not got, at every depth (JTK_E_SCHEMA_KEY_UNKNOWN). A collection says where its entries are with route and shown_on instead of prefix, pages, listing and per_page; its body types are blocks; a reference is {to, many?, on_delete?}; an option is {value, label}. sku, picks (a variant's choice among its product's options, {"size": "s"}, the same in every language), integer, a price's qualifiers, localized, role and shared are new, and business_facts and deprecated are gone — the schema has the table of both contracts' words.

Values. A price is {"minor": 4500}, a picture {"src", "alt"?, "focus"?, "poster"?}, and a reference an entry's id. Empty is absent.

A block's v means something. A type whose version is raised says, in upcast, how a block of each older version becomes the next — a field or a choice's value renamed, a field dropped into _orphans, a new field's first value — and content written at an older version is brought up when it is read and saved at the current one (upcasters). A block no step reaches is refused, JTK_E_BLOCK_BEHIND.

Translations. A language is a translation beside each original, <name>.<locale>.json, holding only the words, and not a full copy of every document. Which values are per language is the kind's, unless a field says localized. What a module books is in every language — translations.

Stock, 13 November 2026. A shop's counts are in no file: they are kept by SKU on the platform. The MCP tool set_stock sets the starting stock, one SKU a line (FOX-S-RED 3), for the SKUs that have not sold; one that has sold is the owner's to correct in the panel, and is left as it is and named (the shop). A product page asks what is left of each variant at GET /api/stock?product=<id>, the first address of the shop's protocol, shop/1 (the shop protocol).

Checkout and orders, 14 November 2026. The shop protocol gains three addresses on the site's own host: POST /api/shipping prices a cart and says the methods its country is offered, and whether the parcel is sent abroad; POST /api/checkout prices it again, holds its stock for 31 minutes and answers Stripe's page; GET /api/order?token= is the page after payment. A page names its version in X-Jtk-Shop, absent being 1 — a version the platform does not answer is refused with JTK_E_SHOP_PROTOCOL — and sends fields the contract has: others are refused to the studio and dropped for a stranger (the shop protocol).

try_order, 14 November 2026. preflight takes try_order, and no tool is added: it prices a cart of one product on sale, checks out to a Stripe test session under your own session, has billing expire that session, and waits for Stripe's own message to lapse the order and give its stock back — a check for each step, and a webhook that does not hear checkout.session.expired is found there (driving it from an agent).

The shop in the panel, 15 November 2026. The owner runs the shop from a Shop group: the products with their variants, the orders — fulfilled with a tracking number and the buyer's letter, refunded or cancelled with the items put back — the stock and the shipping (the panel, by hand). A SKU is made for a product added in the panel and for a copy, and a SKU an order named stays its variant's: a draft that changes it or gives it to another variant is refused with JTK_E_SKU_ORDERED, by the save, by import_branch and by validate_schema; a variant removed, like a product deleted, keeps its SKUs from every other.

VAT and the buyer's own currency, 15 November 2026. On a site that sells, the business's Payments screen has two switches, each off until it is turned on, and no tool, file or commit sets either. Today both act on the shop's orders and on nothing else: a booking's payment is not taxed by them. VAT: Stripe Tax calculates the VAT inside the prices as typed, by each product's tax code, once Stripe says the account is ready for it, and the order, its letters and its export say the VAT charged, per rate. The buyer's own currency: Stripe's page may show a buyer from abroad the price in theirs, and the order stays in the site's. A shown product's tax_code is Stripe's, txcd_ and eight digits, and another shape is refused with JTK_E_PRODUCT_INVALID; the panel offers a short list of them by name. POST /api/shipping's quote, and the one a refused checkout carries, say vat_included and own_currency — the two switches as they are now — and a checkout whose delivery address Stripe cannot tax answers 422 address (the shop protocol; the panel, by hand).

The storefront and the catalogue, 16 November 2026. A shop is laid over a contract-3 site by npx @jtakeit/astro add shop, whole, beside a booking kit or without one: the products collection bound to the module's products role, the shop's settings with a zone and two methods and no prices, and a storefront to copy — a product's page with its variant picker and customization form, the cart, the checkout step, the page after payment and a listing that may hide what is sold out — whose behaviour is @jtakeit/kit's five elements and whose markup and look are the site's. jtk import products <file.csv> --map <mapping.json> brings a catalogue in from a WooCommerce or a Shopify export: the business's SKUs kept, the pictures fetched on the developer's machine and sent by media_link's jtk media push (--media), the starting stock written for set_stock, and no tool added for any of it. shop/1 gains locale, within version 1: POST /api/shipping and POST /api/checkout take the language the page is in, the order's lines are frozen in it where the product has it, and the buyer's letters are written in it (the buyer's language). get_site says in shop_drops what a stranger's shop page sent outside the contract, as booking_drops says the booking page's. The brief gains a section for a shop (the brief), and the shop on the site says the rest.

The shop's line on the plan, 16 November 2026. A site that sells holds a commerce line on its studio's plan, as a site that takes bookings holds a diary: the launch, the setting-up list and a client's offer ask for it, a plan holds no more of them than sites, and a site short of one is refused with JTK_E_PLAN_SHORT — this site sells, which needs a shop line in this studio's plan. A launched shop whose line is not held takes no new order: POST /api/checkout answers 424 no_payee before anything is priced or held, and the cart, the stock and an order already made answer as before (the shop protocol).

Moving from 2: jtk upgrade contract-3, run by the platform's team for every live site. It rewrites the declaration, moves every document, mints the ids and keys, and writes each language's copy as a translation. A value that differs between languages stops the move and is listed for a person. Until it runs, a contract-2 site keeps working exactly as before, and the reference names contract 2's files and codes as the older contract's.

Contract 2 ​

collects on a block type. A block says what it gathers from a visitor — today, "enquiry" and nothing else. Before it, "does this site collect personal data" was inferred from markup, and a gate that guesses is a gate that is wrong about somebody.

It is a string rather than a flag on purpose. The next thing a block might gather — a booking, a subscription — is a different obligation with different words on the page, and a boolean would have had to be replaced rather than extended.

Upgrading from 1: nothing to do. A schema at contract 1 has collects filled in on the way past, from the tell the scaffold has always used — a block with a form field of kind bool is a block that can put a form on a page. The inference errs towards collecting, which is the safe direction: a false positive asks somebody to name a destination, a false negative is a form with nowhere to send.

Contract 1 ​

The first numbered contract, and the shape everything in a repository today was written against — including the files written before the number existed, which are read as 1 in every respect but the line that says so.

Blocks with fields, field kinds, page SEO, business facts, views, collections and languages. What each of those became is the format reference; this entry exists so that "contract 1" names something.