Skip to content

Versioning

The context and the schemas are published under a version segment:

https://bibframe-json.org/v0.1/context/bibframe.jsonld
https://bibframe-json.org/v0.1/schema/linked.json

A 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.

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.

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 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)
import bibframe_json
bibframe_json.VERSIONS # ("v0.1",) oldest first
bibframe_json.CURRENT # "v0.1", the one written today
bibframe_json.context("v0.1") # that version's context
bibframe_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.