The format

A data page, opened up

A page is markdown with five kinds of fenced TOML block in it. This is a way into SPEC.md, not a replacement for it: every key, vocabulary and example below is read out of the validator and the demo page at build time, so nothing here can describe a format the tool no longer enforces.

Anatomy

The five blocks

Pick one. The example beside it is a real block from the page the walkthrough builds.

Vocabularies

What is closed, and what is only recommended

A closed vocabulary is an error outside the list — that is what makes filtering by it worth doing. A recommended one warns, so a project can carry a value the taxonomy hasn't earned yet and propose it upstream once a second independent example turns up.

Lifecycle

The life of an issue

Six stages, and every one of them is a separate act. An issue that has only been registered is worth something; one that has been anchored and validated is worth considerably more, and the difference is visible rather than assumed.

Resolved issues stay on the page. They document eras of the data that still exist in archives, and they are the record that stops the same discovery being made a third time.

Adoption

Core and supplemental

The spec splits itself in two so adoption never demands the whole apparatus at once. A repository that adopts only the core — pages, plus an occasional check — is conformant. The supplemental affordances are where the compounding value is, and they can be adopted independently, in any order.

A page that documents real issues with correct scopes beats a fully instrumented page with thin content. Start core, grow supplemental; empty structure is worse than absent structure.

Reading order

Three tiers, so a page can be read cheaply

Documentation that costs a thousand tokens to consult does not get consulted. The format is arranged for progressive disclosure: the digest is one row per dataset — status, issue counts by effect, and the pitfall line. The page skim is the manifest plus the issue titles. The issue section is the full story, loaded only when its scope intersects the work.

Issues marked core break that rule deliberately: they are read before any contact with the dataset, whatever the slice, because exposure is universal or one misread poisons published work. The validator warns when more than a third of a registry is core, because a page where everything is core has no core.

Tooling

Six commands, one file, no dependencies

Vendored by copying tools/ergo.py into your repository. Usage lines below are its own --help output at this revision.

Everything except check emits a render: digests, JSON exports, served bundles, catalog records. Renders are generated from the page and never authored — edits flow back to the page, never to a render.