JsonUI
← SpecLong prose: texts filesA spec's prose fields — `description`, `notes`, a unit case's `intent`, and the other free-text fields listed below — can point into a YAML file beside the spec instead of holding the text inline. The text there is written as Markdown and renders as Markdown on the generated pages; an inline string stays plain text.~6 min read
Why a second fileA JSON string has no line breaks of its own: a long description is one line of `\n` escapes in the file, and it rendered as one paragraph on the page. Specs that carry real contracts — an app contracts spec with a dozen network rules, unit cases whose intent records the rule, both platforms and the state before the fix — reached tens of kilobytes of prose that nobody could read in either place. The texts file moves that prose out of the JSON, into YAML where a `|` block holds Markdown as written. The JSON keeps the structure: targets, cases, rows.
Pointing a field at a textWrite `{"md": "<key>"}` where the text would go. Without a `#`, the key is read from the spec's paired file: `foo.spec.json` → `foo.texts.yaml` in the same directory (a `.component.json` pairs the same way). With a `#`, the part before it names another file — for text several specs share. That part must be a path relative to the spec that ends in `.texts.yaml` (`../shared/x.texts.yaml` is fine); an absolute path, an empty part (`#key`) or any other file is a validation error. The fields that accept a reference are the prose ones: any `description` and `notes` (or one entry of a `notes` array); a unit case's `intent`; `purpose` (decorative elements, wrapper views); `processing` (user actions); `rule` and `handling` (client-side and server-side validation); `meaning` (a branch-contract condition); `note` (a note-only branch); `reason` (outcome rules, excluded outcomes, unreached operations — not under `harnessConditions`, whose reason is written into the generated hook's comments, nor `canonicalDivergence`, which the API canon reads); and `condition` under `transitions` only (under `validation.serverSide` it is the key the parent-spec merger matches entries by, under `displayLogic` an expression). Anywhere else — a name, a destination, `displayName`, `action`, a diagram, an example — it is a validation error: some tool reads those values as names, keys or code.
app_contracts.spec.json
// app_contracts.spec.json — a prose field points into the texts file
{
"metadata": {
"name": "app",
"description": { "md": "overview" } // paired file: app_contracts.texts.yaml
},
"unitContracts": [
{
"target": "UserRepository",
"cases": [
{
"name": "healthCheck_carriesATenSecondPerRequestTimeout",
"intent": { "md": "cases.user_repository.health_check_timeout" }
},
{
"name": "healthCheck_usesTheSharedClient",
"intent": "Short prose stays inline, as plain text."
}
]
}
],
"notes": [
{ "md": "shared/network.texts.yaml#timeouts.default" } // a named file, relative to the spec
]
}
Writing the YAMLThe key is a `.`-separated path through nested mappings, the way i18n keys are: `cases.user_repository.health_check_timeout` is three levels. The value at the end of the path is a string; write it with `|` so the Markdown needs no escaping and keeps its blank lines. Group keys however reads best — by target, by section of the spec — the tools only follow the path.
app_contracts.texts.yaml
# app_contracts.texts.yaml — beside app_contracts.spec.json
overview: |
この面の app が所有し、単一の画面が所有しない unit target の契約。
 
### ネットワーク層の規則
**(1)** 426: どの API 要求でも ForceUpdateManager を立てる。
 
**(2)** 401(/api/auth/* 以外): refresh は 1 本にまとめる(single-flight)。
 
cases:
user_repository:
health_check_timeout: |
**`[api.healthCheck=default]`** GET /api/health は要求単位で **10 秒**。
 
- iOS: `URLRequest.timeoutInterval == 10`
- Android: chain の connect / read / write timeout が 10 秒
 
> 実装前の状態: 両 OS 赤 — 2026-09-25 に実装済み
How it rendersOn the generated spec and unit-test pages, a text from a texts file is rendered as Markdown — headings, lists, code, quotes, tables — styled like the page around it. Raw HTML in it is not rendered, and a `javascript:` link is not made a link. An inline string is still plain text, with one change: its line breaks are now shown. A page with no reference is byte-identical to what it was; the Markdown stylesheet is added only to a page that renders Markdown. The Markdown export of a spec inserts the text as written, and turns its line breaks into `<br>` inside a table cell so the row stays one row. Rendering needs `markdown-it-py`. A spec page cannot be generated without it (validation refuses the spec first), but a unit-test page does not pass through validation: there the text is shown as plain text, and `generate html` prints one `WARNING [doc-markdown]` line for the whole run.
What validate checks`jsonui-doc validate spec` resolves every reference and checks the YAML it reads. Each rule below exists because the permissive reading is a silent wrong answer: YAML reads `yes:` / `on:` as booleans and `1:` as a number, so such a key cannot be named in a reference (quote it); `.` is the path separator, so a key containing one is ambiguous; YAML keeps the last of two equal keys, so the first would vanish; a list has no stable key; a merge key (`<<:`) is not supported — write each key out. A named file must be relative and a `.texts.yaml`: every tool that reads the spec follows the reference, so an absolute path works on one machine only, and any other file would be quoted into generated pages and code. A key of the paired file that no field references is a warning — usually a rename done on one side only. A named file may be shared, so its keys are not checked for use. PyYAML and markdown-it-py are needed only by a spec that uses a reference: such a spec fails validation naming the `pip install` when either is missing, and a spec with none passes without them (a paired file beside it gets a warning that its unused-key check was skipped).
jsonui-doc validate spec / jsonui-test
$ jsonui-doc validate spec app_contracts.spec.json # one defect per run
[ERROR] texts: unitContracts[0].cases[1].intent: 'app_contracts.texts.yaml#cases.x' is not defined
[ERROR] texts: unitContracts[0].cases[1].intent: 'app_contracts.texts.yaml#cases' is a mapping, not a text — name one of its keys
[ERROR] texts: unitContracts[0].cases[1].intent: 'gone.texts.yaml#k' — gone.texts.yaml does not exist
[ERROR] texts: unitContracts[0].cases[1].intent: '/etc/app.texts.yaml#k' names an absolute path — name the file relative to the spec, so the reference reads the same on every machine
[ERROR] texts: unitContracts[0].cases[1].intent: '../../.env#KEY' names '../../.env', which is not a .texts.yaml file — a reference reads texts files only
[ERROR] texts: unitContracts[0].cases[1].intent: '#k' names no file before '#' — write {"md": "key"} to read the spec's paired file
[ERROR] texts: userActions[0].action: a text reference is read only in description / notes / intent / purpose / processing / handling / rule / meaning / note / reason (not under harnessConditions / canonicalDivergence) / condition (under transitions only)
[ERROR] texts: validation.serverSide[0].condition: a text reference is read only in description / notes / intent / purpose / processing / handling / rule / meaning / note / reason (not under harnessConditions / canonicalDivergence) / condition (under transitions only)
[ERROR] texts: app_contracts.texts.yaml: line 7: key 'yes' is read as a bool, not a string — YAML reads yes / no / on / off / true / false and bare numbers as values; quote the key if it is meant as a name
[ERROR] texts: app_contracts.texts.yaml: key 'cases.a.b' contains '.', which is the path separator — nest it as a mapping instead
[ERROR] texts: app_contracts.texts.yaml: line 9: duplicate key 'retries' (first at line 7) — YAML would keep only the last
[ERROR] texts: app_contracts.texts.yaml: 'cases.list' is a list — a value is a string (use `|` for Markdown) or a mapping of more keys
[ERROR] texts: app_contracts.texts.yaml: line 11: merge keys (`<<:`) are not supported in a texts file — write each key out
[WARNING] texts: app_contracts.texts.yaml: 1 key(s) no field of this spec references: cases.old
 
# without PyYAML: a spec with references / a spec with none (and a paired file beside it)
[ERROR] texts: metadata.description: 'app_contracts.texts.yaml#overview' cannot be read — PyYAML is not installed (pip install pyyaml)
[WARNING] texts: app_contracts.texts.yaml: PyYAML is not installed, so the unused-key check of this file was skipped — pip install pyyaml
# without markdown-it-py: a spec with references
[ERROR] texts: markdown-it-py is not installed, so texts-file references cannot be rendered — pip install markdown-it-py
 
$ jsonui-test generate unit-stubs --check --spec-dir . # 'cases.x' undefined → exit 1
ERROR: 1 spec(s) carry a text reference that could not be resolved — nothing is compared or written until it is:
app_contracts.spec.json: 1 text reference(s) could not be resolved, so this spec was not read — unitContracts[0].cases[1].intent: 'app_contracts.texts.yaml#cases.x' is not defined
Every reader gets the textReferences are resolved where a spec is read, once, so no reader sees `{"md": ...}`: the doc generator, `jui generate` / `build` / `verify`, and `jsonui-test`'s unit-contract check and stub generator (a stub's failure message carries the intent's text). A reference that cannot be resolved stops `jsonui-test` the same way validate reports it: `generate branch-tests` and `contracts coverage` report it as that spec's problem (exit 1 / not evaluated), and `generate unit-stubs`, with or without `--check`, stops before comparing or writing anything. Split specs resolve each sub-spec against its own texts file only, before the merge. The MCP `read_spec_file` tool returns each reference with its text beside it, so an agent sees both what the field says and where to edit it. The MCP `search_specs` tool does not search texts-file text: it matches the spec JSON only, so it finds a reference's key but not the words the key points to — search the `.texts.yaml` files for those.
read_spec_file
// read_spec_file (MCP) — each reference comes back with its text
"intent": {
"md": "cases.user_repository.health_check_timeout",
"text": "**`[api.healthCheck=default]`** GET /api/health は…"
}
// "text" is for reading only. Edit the YAML file; validate refuses a
// "text" key written back into the spec.
When to keep it inlineA sentence or two stays inline — it reads fine in the JSON and needs no structure. Move a text out when it is longer than a few lines or needs headings, lists or a separate paragraph per rule. Do not move a text back inline to simplify a diff: the page loses its structure and the JSON is one escaped line again. Renaming a key is two edits, the YAML key and every reference to it; validate after either.
Keep goingWhere the rest of a spec is described, and how it is checked.
The anatomy of a screen specEvery top-level key of a screen spec and what reads it./spec/anatomy
Validation + drift detectionWhat validate and verify check, and when each runs./spec/validation-and-drift