Routes Format
The route file format
A route is one text file. This page is the whole specification: what the file holds, what makes it valid, and a blank one to copy.
What a route file holds
A question worth following. The move it makes: understand, decide, make, practice, teach or organize. A stated time. Three to nine stations, each with a type, a task and its sources. What you leave with, and the ways out. Two fields need a note:
- would_change
- What would make the author restructure the route. A route that cannot name one has not been tested against anything.
- standard (optional, added in 0.2)
- The published criterion the finished work is checked against: its name, publisher, date and link, what meeting it means, who checks it, and any figures a learner can compare. A route without one says so. Files in 0.1 remain valid.
Eight station types
| orient | Get your bearings from something with visible provenance. |
|---|---|
| source | Read, watch or examine one thing closely. |
| counterpoint | Meet a credible disagreement from outside the route. |
| person | Speak with someone. |
| place | Go somewhere real. |
| practice | Attempt the skill. |
| make | Produce the thing you keep. |
| reflect | Close the route and say what changed. |
The list is closed: a new type needs a new version of the format, and that is what keeps a forked route walkable in someone else's walker.
What makes a file valid
- It parses, and its format field names a version a walker knows.
- It has three to nine stations. At least one can correct the person walking it (a counterpoint, a person with a different relationship to the question, or a tested practice), and at least one happens away from the page (a person, a place, a practice or a making).
- Every counterpoint cites at least one source whose origin is a published work, a person or a dataset, with an author and a date. An objection written by the route’s own author does not count. The measured reason is in my research on checking AI: three checkers from different model families outvoted a trick aimed at one of them (0.0742 of correct work flagged, against 0.8991 alone) and all fell to a trick aimed at all three (0.9941), so a second opinion counts only as far as its failures differ from the first.
- Every source carries a date, or the walker prints "undated" beside it.
- would_change is present and not empty.
- A file with no correcting station or no active station is still valid, but only as kind: reading-list, and a walker titles it that way. The reading shelf takes its name from this rule.
A starter file
Copy it, fill it in any text editor, and put it beside one of the walkable routes to compare. Each of those has its own route.json one click from its page.
{
"kind": "route",
"format": "kosplora-route/0.2",
"question": "",
"move": ["understand"],
"audience": "",
"time": { "solo": "2h" },
"authors": [{ "name": "", "date": "" }],
"would_change": "",
"standard": null,
"stations": [
{ "type": "orient", "time": "30m", "task": "",
"sources": [{ "title": "", "author": "", "date": "", "url": "", "origin": "published" }] },
{ "type": "person", "time": "40m", "task": "" },
{ "type": "counterpoint", "time": "20m", "task": "",
"sources": [{ "title": "", "author": "", "date": "", "origin": "published" }] },
{ "type": "make", "time": "45m", "task": "" }
],
"artifact": { "keeps": "" },
"exit": ["keep", "share", "fork", "close"],
"revisions": [{ "date": "", "change": "First version.", "by": "" }]
}What's happening. This is everything a route needs, empty. Four stations are enough to pass every rule above: an orientation, a person, an outside counterpoint and something you make.
Why it matters. A route kept in a file outlives this site. You can fork it, print it, or open it in a walker I did not write, and you can check any route page here against the route.json it was built from.
Devil's advocate. The rules check the shape of a claim and not its truth. The audit confirms that a counterpoint names a dated source with an author and an origin other than "generated". It cannot tell whether that source says what the route says it says, or whether "published" is true. A careful liar passes. Checking still takes a person reading the source.
Rabbit hole. Open the second-mapper route's file and find its counterpoint. Then read my research on checking AI on when a second opinion is really a second opinion.
Anyone can write a route in this format without asking me, which is how any of those numbers could change.
Write a route for something you actually know. If the format cannot hold it, that is a bug in the format, and I want to hear about it. Write in.