Skip to content

Document the evolution principles in the README #132

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jviotti merged 1 commit into from
Aug 5, 2026
Merged

Document the evolution principles in the README #132

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions README.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,39 @@ designing great APIs.*
| <a href="https://www.xbrl.org/dtr/dtr.html"><img src="./assets/xbrl.svg" alt="XBRL" height="18"></a> | [XBRL DTR](https://www.xbrl.org/dtr/dtr.html) | [XBRL Data Types Registry](https://www.xbrl.org/dtr/dtr.html) |
| <a href="https://www.xbrl.org/specification/utr/rec-2013-11-18/utr-rec-2013-11-18-clean.html"><img src="./assets/xbrl.svg" alt="XBRL" height="18"></a> | [XBRL UTR](https://www.xbrl.org/specification/utr/rec-2013-11-18/utr-rec-2013-11-18-clean.html) | [XBRL Units Type Registry](https://www.xbrl.org/specification/utr/rec-2013-11-18/utr-rec-2013-11-18-clean.html) |

## :seedling: Evolution

The library is designed to evolve without ever breaking its consumers. The
key principles are:

- **Paths mirror the authority**. Each collection is versioned the way its
governing body publishes: edition years for ISO, IEEE, BIPM, and W3C
standards, RFC numbers for the IETF, dated releases for dated registries,
and in-place evolution for living registries. Self-published specifications
live under `other/`.

@augmentcode augmentcode Bot Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

README.markdown:80 — This says self-published specs live under other/, but in the repo layout they appear under schemas/other/; consider clarifying whether paths here are relative to schemas/ to avoid confusion for readers browsing the tree.

Severity: low

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

- **Every schema is individually versioned**. Each concept lives at
`<concept>/v1.json` and there are no unversioned aliases.
- **Versions never change their validation behavior**. A published version

@augmentcode augmentcode Bot Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

README.markdown:83-90 — The “Versions never change their validation behavior” bullet reads like a universal rule, but the next bullet says some “living registries drift in place,” which implies validation can change within a version; consider explicitly scoping the immutability guarantee (or noting the exception) so the principles don’t contradict.

Severity: medium

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

may gain annotations, linked data mappings, or clearer wording, but it
accepts and rejects exactly the same instances forever. Any change that is
visible to validation mints a sibling version instead.
- **Living registries drift in place by contract**. Collections backed by an
evolving registry, such as currency codes or the XBRL UTR, track their
upstream within the same version, since their value space is defined by
the registry rather than by a frozen document.
- **Supersession is explicit**. Replaced versions are marked with
`deprecated: true` and are never deleted.
- **References pin exact versions**, so the blast radius of any new version
is always visible.
- **Linked data carries identity, not metadata**. Schemas mint
dereferenceable IRIs from the governing authorities, and consumers obtain
names, symbols, and classifications by following them. Every IRI is
verified against its authority before it ships, and none are ever
fabricated.
- **Generation follows upstream data**. Schemas are either generated from
vendored authority data or written by hand, never generated from
hand-maintained intermediates.

## :mortar_board: Citing

If you use this library in your research or project, please cite it using the
Expand Down
Loading