Versioning
The context and the schemas are published under a version segment:
https://bibframe-json.org/v0.1/context/bibframe.jsonldhttps://bibframe-json.org/v0.1/schema/linked.jsonA document names a context. A $ref resolves against a $id. Both are
promises, and the version segment is what keeps them: a URL you write today
still resolves after the shape moves on.
The segment sits above the trees rather than inside them, so a schema’s
references never change. The split files stay siblings within their version,
and {"$ref": "Work.json"} resolves the same whether there is one version or
six.
What moves it
Section titled “What moves it”A change that invalidates documents written against the version before it.
Remove a term, rename one, or change a term’s @type or @container, and the
same JSON now means something else.
Adding a term does not move it. Neither does a clearer description, or a constraint tightened so that nothing conforming notices.
example/ and conformance/ carry no version. They are illustration and test
material, they track the current version, and no document names them.
Every version is frozen
Section titled “Every version is frozen”A published version’s bytes never change. The 0.x versions are unsettled because the next one may break you with little notice, and because several are expected before v1.
Freezing is what makes migration possible. Data written against v0.1 has to
reach v0.2, and a migration reads one version and writes another. If a
version changed in place, every stored document would say v0 and mean
whichever v0 was live on the day somebody wrote it.
So expect v0.1, v0.2 and onward. Each one is a real move, and each one is
the source of a migration. At v1 the shape becomes something to build on, and
from there the version is major only.
The package version is a separate number
Section titled “The package version is a separate number”The artifact version describes the shape, and every language binding shares
it. A package version describes one binding’s API. The Python package moves
when validate() or document_loader() changes, which has nothing to do with
whether the schemas moved, and the npm and Ruby packages will keep their own
numbers for the same reason.
Shipping a new artifact version alongside the old ones is additive, so it is a minor release. Dropping one, or changing the API, is major.
Ask a package what it ships rather than inferring it from the number.
In Python that is bibframe_json.VERSIONS.
For history, where each artifact version first appeared:
| artifact | first shipped in |
|---|---|
v0.1 |
bibframe-json 0.1.0 (Python) |
Asking for a particular version
Section titled “Asking for a particular version”import bibframe_json
bibframe_json.VERSIONS # ("v0.1",) oldest firstbibframe_json.CURRENT # "v0.1", the one written todaybibframe_json.context("v0.1") # that version's contextbibframe_json.schema("linked", "v0.1")bibframe_json.context_url("v0.1")Ask for a version the package does not ship and you get a ValueError, rather
than a read of some path that happens not to exist.