Appearance
A block type's versions, and upcasters
A block type in jtk/schema.json carries a version, v, and every block a document holds says the v it was written at. While a type stays as it is, both say 1 and nothing happens. When a type changes in a way the content already written can feel — a field renamed, a value of a choice renamed, a field gone — you raise v and say, in the type's upcast, how a block of the older version becomes the newer one. The platform does the rest: it brings every block written at an older version up when it reads it, and the next save writes the current one into your files.
Contract 3 only. A contract-2 site's v stays 1.
What a step is
json
{
"type": "hero",
"v": 3,
"label": "Hero",
"fields": [
{ "key": "title", "label": "Titel", "kind": "text", "client_editable": true },
{ "key": "align", "label": "Ausrichtung", "kind": "select",
"options": [{ "value": "left" }, { "value": "center" }] },
{ "key": "tone", "label": "Ton", "kind": "select",
"options": [{ "value": "light" }, { "value": "dark" }] },
{ "key": "items", "label": "Fragen", "kind": "list", "of": [
{ "key": "question", "label": "Frage", "kind": "text" },
{ "key": "answer", "label": "Antwort", "kind": "text" }
] }
],
"upcast": [
{ "from": 1, "rename": { "heading": "title" },
"values": { "align": { "centre": "center" } } },
{ "from": 2, "drop": ["subtitle"], "set": { "tone": "light" },
"rows": { "items": { "rename": { "q": "question" } } } }
]
}Each step makes a block of version from a block of version from + 1. A block written at version 1 goes through both steps above, in order; one written at 2 through the second only. A step's changes are made in this order:
| change | what it does |
|---|---|
rename | {"old": "new"} — the value moves to the new name. Where the new name already says something, the old value goes to _orphans instead. |
rows | {"list": {…}} — the same changes inside every row of a list, and once more for a list inside a row. Each row keeps its _key. |
values | {"field": {"old": "new"}} — a choice's value renamed, in a single value or in a list of them. Renaming an option's value is a migration, and this is it. |
drop | ["field"] — the field is gone. Its value goes to _orphans, which nothing serves and nothing loses. |
set | {"field": value} — a new field's first value, written only where the block has none. |
There is no other change, and no code. The schema is your file, but the platform runs nothing from it.
The rules the judge holds a step to
validate_schema refuses a step with JTK_E_UPCAST_INVALID when:
- its
fromis not an older version of the type (1 up tov - 1), or two steps share one; - it names something that is not a field's name, renames a field to itself, or renames two fields into one;
- it is the last step — the one from
v - 1— and writes, renames into, changes the rows of, or sets a field the type does not declare now, or drops one it still declares. An earlier step's names belong to a version nobody declares any more, and only their spelling is held.
Every version content may still be at needs its step. A version that changed nothing stored content can feel — a field added, a bound widened — still says it, empty: {"from": 2}. A block at a version with no step is refused, never guessed at: JTK_E_BLOCK_BEHIND, naming the file, the block, its v and the type's. A block whose v is newer than its type's is refused the same way; that is a schema not pushed with its content.
Where it happens
| when | what is brought up |
|---|---|
an import (import_branch, a push, the panel's sync) | every block of every page, entry, the shared text and a module's settings, as the branch's files are read; then every stored copy the branch did not bring — the draft, the version and the live copy — so the three stages compare one shape with one shape |
| any write in the panel | the document being written, so a version restored from before the change is written at the current version |
| a save | the files it writes say the current v |
So the order of work is: change the type, raise v, add the step, push. You do not have to rewrite the content files by hand. If you do, the steps leave what is already in the new shape as it is — a rename moves a value only where the new name says nothing, set writes only where nothing is, a value is renamed only where it is the old one — so a tree half rewritten by hand and half not is brought up all the same.
An entry's own values. An entry's fields carry no v of their own. They are read as written against the schema the platform held when they were written: when a push raises the version of a collection's type, the import takes that collection's entries through the steps from the version the platform had, and the next save writes them in the new shape.
A translation is not brought up: it holds only words, named by the original's keys, and has no type of its own. When a step renames a field that has words in other languages, rename it in the translation files (<name>.<locale>.json) in the same commit; the import refuses a translation that names a field the schema does not declare, and says which file.
The template
Your template reads the content through the kit's door, and sees only the current version: the build reads the files a save wrote. Until the first save after the push, a build of the pushed commit reads the files as you pushed them — so change the template and the content in one push, or push and then commit_and_build, which saves before it builds.