# Xenon demo: a Technical Specification computed from decision records Nine Architecture Decision Records (ADRs) for a fictional Order Service, one linkbase recording which decisions replace which, and a set of standard XSLT and Schematron files that turn them into: - **the Technical Specification as it stands today**, with no superseded ("fossil") decisions in it, and the full lineage of every decision in the margin; - **the same specification as it stood on any past date**; - **a JSON export** of the same model, for JSON-first tools; - **a validator** that reports broken or contradictory links in plain English. Nothing in `out/` is edited by hand. ## Layout ``` spec.xml narrative skeleton of the spec (no decisions in it) adr/adr-0001.xml … 0009 the decision records; they contain no links at all links/supersession.xml the linkbase: every "replaces" relationship links/broken-example.xml a deliberately broken linkbase, for the validation demo xsl/xpointer.xsl resolves XLink hrefs with XPointer fragments xsl/supersession.xsl the model: in force, superseded, proposed, lineage xsl/spec-html.xsl the computed Technical Specification (HTML) xsl/decisions-json.xsl the same model as JSON schematron/linkbase-rules.sch integrity rules (ISO Schematron) schematron/report.xsl SVRL report to plain text vendor/iso-schematron/ the ISO Schematron reference implementation (MIT) out/ generated files ``` ## Standards used | Standard | Status | Used for | |---|---|---| | XML 1.0 + Namespaces, `xml:id` | W3C Recommendations | the records and stable ids for every decision | | XLink 1.1 | W3C Recommendation (2010) | extended links, locators, arcs, linkbases | | XPointer Framework, `element()` scheme | W3C Recommendations (2003) | pointing at one decision inside another file | | Dublin Core Elements and Terms | DCMI, ISO 15836 | `dc:date`, `dc:creator`, and `dcterms:replaces` as the arc role | | XSLT 3.0, XPath 3.1 | W3C Recommendations (2017) | computing the spec, the history view and the JSON | | Schematron | ISO/IEC 19757-3 | validation rules with human-readable messages | | SVRL | part of ISO Schematron | the machine-readable validation report | No vocabulary is invented for the relationships themselves: the arc role is the Dublin Core URI `http://purl.org/dc/terms/replaces`. ## Run it All paths in this README are relative to the `xenon-adr-demo/` folder. The download is a `.zip`, so open it with `unzip`, not `gunzip`: ``` unzip Xenon_adr_demo.zip # only if you have the outer bundle unzip xenon-adr-demo.zip cd xenon-adr-demo pip install saxonche # Python 3.9 or later python3 run.py ``` Use `python3`; many Linux systems have no `python` command. Then open `out/spec-current.html` in a browser. `out/` already holds a prebuilt copy, so you can look at the pages before running anything. Or with Saxon-HE on Java: ``` java -jar saxon-he.jar -s:spec.xml -xsl:xsl/spec-html.xsl -o:out/spec-current.html java -jar saxon-he.jar -s:spec.xml -xsl:xsl/spec-html.xsl -o:out/spec-2025-06-30.html as-of=2025-06-30 java -jar saxon-he.jar -it -xsl:xsl/decisions-json.xsl -o:out/decisions-current.json ``` The HTML pages load fonts and the Mermaid diagram library from public CDNs. Offline, the diagram falls back to its source text. ## What the example contains | Pattern | Where | |---|---| | Partial supersession: one decision of a record replaced, the other still in force | ADR-0004 replaces decision 2 of ADR-0001; PostgreSQL (decision 1) stands | | One decision replacing three, across two records, with one arc | ADR-0006 replaces all of ADR-0003 and decision 2 of ADR-0002 | | A chain three deep, with a surviving sibling | ADR-0005 → ADR-0007 decision 1 → ADR-0008; ADR-0007's outbox decision survives | | A pending change | ADR-0009 is proposed; its arc is shown as a proposal, not applied | | A pointer without an id | the `element(adr-0002/6/2)` XPointer in the linkbase | ## Demos, in presentation order **1. The records don't know about each other.** Open any `adr/*.xml`. No "Status: superseded by …" line, no links. Then open `links/supersession.xml`. Every relationship is there, typed, and pointing at individual decisions, not whole files. **2. The spec has no fossils.** Open `out/spec-current.html`. Every decision in force, grouped by topic, with who decided it and when. The margin shows what it replaced, and what that replaced, struck through. The superseded decisions are still available at the bottom, kept for the record. **3. Status is computed, never stored.** Nothing in any ADR says "superseded", so nothing can go stale. Supersession is worked out from the linkbase every time the spec is built. **4. Time travel is a parameter.** Follow the link to `out/spec-2025-06-30.html`: sessions, Redis, static partner keys and LISTEN/NOTIFY are all back, because on that date they were in force. Same files, same stylesheet, `as-of=2025-06-30`. **5. A new decision touches nothing old.** Live, accept ADR-0009 by changing its `status="proposed"` to `status="accepted"`, then rerun `python3 run.py`. PostgreSQL moves to the superseded list, CockroachDB appears under Persistence with its lineage, and the diagram updates. To add a brand-new record instead: create `adr/adr-0010.xml` and append one `` element to the linkbase. No existing file changes. **6. Bad links are caught, in plain English.** `python3 run.py` validates both linkbases. The broken one reports: ``` links/broken-example.xml: 4 problems found. - Broken pointer in "Broker change": ../adr/adr-0007.xml#adr-0007-d3 does not point at anything. ... - In "Identity model", ADR-0002 decision 2 (2025-02-03) claims to replace ADR-0006 (2025-09-02). ... - In "Events" the arc goes from "new" to "older", but no locator in this link has older as its label. - ADR-0001 decision 2 is replaced by both ADR-0004 and ADR-0007. Decide which one holds, ... ``` The last one is a semantic conflict, two accepted decisions both claiming to replace the same thing, found by one short rule. **7. JSON is just another view.** `out/decisions-current.json` is produced by the same model in about forty lines of XSLT. The XML stays the source of truth. ## What a folder of Markdown and JSON would need to match this Each of these exists in the XML stack as a published standard with interoperable implementations. In a Markdown or JSON setup each is a local convention you write and maintain yourself: - **Pointing at part of another document.** `adr-0001.xml#adr-0001-d2` names one decision. A Markdown link reaches a file, or a heading anchor whose spelling depends on the renderer. - **Links stored outside the documents they connect**, typed with a role from a public vocabulary, and able to join more than two ends with one arc. This is what lets old records stay untouched. - **A transformation language that follows those links across files** and produces new documents: the current spec, a past spec, JSON. - **Rules that check the links and explain failures in sentences**, with a standard report format other tools can read. JSON has standards of its own (JSON Pointer, JSON Patch, JSONPath, JSON-LD), and JSON-LD in particular can express typed links. The difference is that in XML the addressing, linking, transformation and validation standards were designed to work together, and mature implementations of all of them exist.