---
title: "Versions, compatibility | Observatory Protocol"
description: "How the protocol and its contracts are versioned, what counts as a breaking change, and how a part is retired."
url: https://nexusobservatory.com/development/versioning/
publisher: GCRI Canada
updated: 2026-11-18
---

[Observatory Protocol](https://nexusobservatory.com/)[Open development](https://nexusobservatory.com/development/)Versioning

# Versions, compatibility and deprecation

How the protocol and its contracts are versioned, what counts as a breaking change, and how a part is retired.

**Version**: 0.1.0-draft
**Status**: Draft specification
**Specification**: CC BY 4.0
**Code**: Apache-2.0
**Steward**: GCRI Canada
**Source**: obsp-0.1-foundation

[Propose a change](https://nexusobservatory.com/development/proposals/)

[Read the text](https://nexusobservatory.com/development/text/)

## Protocol and contract versions

Until version 1.0, a minor version may break compatibility. From 1.0, only a major version does. Wire contracts carry schemaVersion 3.1.0 for OBSP 0.1. (OBSP 0.1 §10)

- Protocol versions are `obsp/<major>.<minor>` . Until 1.0, a minor version MAY break; from 1.0, only a major version breaks. Wire contracts carry `schemaVersion` `3.1.0` for OBSP 0.1; a breaking contract change needs an OIP and a new `schemaVersion` .
- Changes are proposed as Observatory Improvement Proposals (OIPs): `DRAFT → REVIEW → ACCEPTED → IMPLEMENTED` , or `WITHDRAWN` . An OIP that changes a function MUST update this file, `registers/functions.yaml` , the affected schemas and the conformance tests in the same change.
- Stewardship, licences and the contribution terms are recorded in `GOVERNANCE.md` .

## Versions and compatibility

How the protocol, the contracts and the tools are versioned. (Observatory Protocol policy, Versions and compatibility)

**`VER-1`**: The protocol version is obsp/<major>.<minor>; releases are tagged v<major>.<minor>.<patch> with an optional pre-release suffix, matching VERSION.
**`VER-2`**: Before 1.0 a minor version may break compatibility; from 1.0 only a major version may.
**`VER-3`**: Wire contracts carry schemaVersion; a schema change that rejects previously valid documents is breaking.
**`VER-4`**: Every release is a reproducible bundle with a manifest and SHA256SUMS; anyone can rebuild it from the tag and compare digests.

## Deprecation and withdrawal

How an element of the protocol is retired without stranding operators. (Observatory Protocol policy, Deprecation and withdrawal)

**`DEP-1`**: An element is deprecated in one release and removed no earlier than the next minor release before 1.0, and the next major release from 1.0.
**`DEP-2`**: A deprecation names the replacement and the migration path; an element without a replacement needs an OIP that says why.
**`DEP-3`**: Identifiers, rule ids, requirement ids and schema ids are never reused for another meaning.

## Identifiers and names

How the protocol names its own artifacts and binds them to the Nexus Standards identifiers. (Observatory Protocol policy, Identifiers and names)

**`IDN-1`**: Schema ids are urn:obsp:schema:v<schemaVersion>:<name>, one per schema; the validator rejects any other form.
**`IDN-2`**: Every protocol artifact published by the Consortium carries a UNI under the Nexus Standards (NS-1) in scope OPS, with the category in registers/relations.yaml.
**`IDN-3`**: Operators choose their own display names through name packs; the protocol never imposes an organisation's name on a deployment.
**`IDN-4`**: Names of external standards and their stewards are used only to identify their documents.

## Records and corrections

How the repository and conforming deployments keep history. (Observatory Protocol policy, Records and corrections)

**`COR-1`**: Records are correction-addressable; a correction supersedes a version and never deletes it (principle P9).
**`COR-2`**: Released bundles are immutable; an error in a release is fixed by a new release and an entry in CHANGELOG.md.
**`COR-3`**: A correction to protocol evidence cited by Nexus Reports or GRIx is published as a correction notice so dependent values are marked stale and recomputed.

## Releases

How a release is cut and published. (Observatory Protocol, Release guide)

1. Merge an OIP or editorial change with every check green.
2. Update VERSION and CHANGELOG.md in a pull request.
3. Tag `v<VERSION>` on `main` . CI repeats every check, verifies that the tag matches `VERSION` , and builds the bundle. It publishes `obsp-<version>.tar.gz` , `obsp-<version>.manifest.json` and `SHA256SUMS` as a GitHub release.
4. Anyone can verify a release: \`\` `sh git checkout v<version> python3 tools/release.py --out /tmp/check diff /tmp/check/SHA256SUMS SHA256SUMS # from the release` \`\`
5. Register the release UNI ( `ST` for the specification, `SC` for the contracts) with the Nexus Standards registry through the Secretariat.

Released bundles are immutable (`COR-2`). A defect is fixed by a new release.

## References

Sources cited on this page, in order of first citation. Addresses were last checked on the date shown.

1. [OBSP 0.1 §10: Versioning and change](https://nexusobservatory.com/development/text/#c-10) Observatory Protocol 0.1 (draft), CC BY 4.0.
2. [Observatory Protocol policy, Versions and compatibility: registers/policies.yaml versioning](https://nexusobservatory.com/development/versioning/#pol-versioning) Observatory Protocol 0.1 (draft), CC BY 4.0.
3. [Observatory Protocol policy, Deprecation and withdrawal: registers/policies.yaml deprecation](https://nexusobservatory.com/development/versioning/#pol-deprecation) Observatory Protocol 0.1 (draft), CC BY 4.0.
4. [Observatory Protocol policy, Identifiers and names: registers/policies.yaml identifiers-and-naming](https://nexusobservatory.com/development/versioning/#pol-identifiers-and-naming) Observatory Protocol 0.1 (draft), CC BY 4.0.
5. [Observatory Protocol policy, Records and corrections: registers/policies.yaml records-and-corrections](https://nexusobservatory.com/development/versioning/#pol-records-and-corrections) Observatory Protocol 0.1 (draft), CC BY 4.0.
6. [Observatory Protocol, Release guide:](https://nexusobservatory.com/development/versioning/#doc-docs-guides-releasing) Observatory Protocol 0.1 (draft), CC BY 4.0.

On this page

1. Protocol and contract versions
2. Versions and compatibility
3. Deprecation and withdrawal
4. Identifiers and names
5. Records and corrections
6. Releases
7. References

- [View the source](https://nexusobservatory.com/development/text/)
- [Report a defect](https://nexusobservatory.com/development/take-part/)
- [Propose a change](https://nexusobservatory.com/development/proposals/)
- [Changes](https://nexusobservatory.com/governance/changes/)
