Versions & citation

Versions, pinning, and citation

BXP v2.0 is a stable specification. This page explains how to pin a version so your integration or citation keeps resolving to the same document, and how to cite the work.

Why pinning matters A specification that can change without warning cannot be integrated against. BXP commits to semantic versioning: a breaking change means a new MAJOR version with 18 months advance notice, and MINOR additions are backward compatible by design. Pin to a MAJOR version and a minor release cannot invalidate your integration.

Pinning a version

Want	Use	Means
main	`https://github.com/bxpprotocol/bxp-spec/blob/main/SPEC.md`	Always the latest work. Fine for reading, not for integrating.
v2.0	`.../blob/v2.0/SPEC.md`	The specification as published. Stable, and what conformance is judged against.
<commit>	`.../blob/<sha>/SPEC.md`	Exactly one immutable state. Use this in a paper or a reproducibility record.
DOI	doi:10.5281/zenodo.18906812	Archival, time-stamped, and resolvable forever. Preferred for citation.

For code dependencies, the equivalents are the bxp-sdk package version, or a git submodule pinned to a tag.

Pinning the API contract

The REST contract is committed as an OpenAPI 3.1 document, generated from the reference server so it cannot drift from the implementation:

openapi.json   canonical, machine-readable
openapi.yaml   same document, human-diffable

Pin one of these into your repository and diff it in CI. When it changes incompatibly, you find out in a pull request rather than in production.

Compatibility policy

Change	Version bump	Your integration
New optional field	MINOR	Keeps working. Ignore fields you do not recognise.
New agent under `ext`	MINOR	Keeps working.
New endpoint	MINOR	Keeps working.
Field removed or retyped	MAJOR	Breaks. 18 months advance notice before it ships.
Changed checksum or framing	MAJOR	Breaks. The wire format is frozen within a major version.

Releases

Version	Description	Tag
2.1.0	2026-10-03	`#2.1.0`
2.0.0	March 2026	`#2.0.0`
1.0.0	February 15, 2026 — FROZEN	`#1.0.0`

Citing BXP

The specification and the reference implementation each have a permanent DOI. Cite the specification when referring to the format or the protocol; cite the implementation when referring to the software.

What	DOI
Specification v2.0	doi:10.5281/zenodo.18906812
Reference implementation	doi:10.5281/zenodo.18907003

Machine-readable citation metadata lives in CITATION.cff, so GitHub's “Cite this repository” and tools such as doi2bib resolve authors, title, and version without you maintaining a second copy.

BibTeX

@software{bxp_protocol_2_0_0,
  author    = {Elvarin},
  title     = {BXP Protocol: Breathe Exposure Protocol},
  version   = {2.0.0},
  year      = {2026},
  doi       = {10.5281/zenodo.18906812},
  url       = {https://github.com/bxpprotocol/bxp-spec},
  license   = {Apache-2.0}
}

RIS

TY  - SOFT
AU  - Elvarin
TI  - BXP Protocol: Breathe Exposure Protocol
PY  - 2026
VL  - 2.0.0
DO  - 10.5281/zenodo.18906812
UR  - https://github.com/bxpprotocol/bxp-spec
ER  -

APA 7

Elvarin. (2026). BXP Protocol: Breathe Exposure Protocol (Version 2.0.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.18906812

MLA 9

Elvarin. BXP Protocol: Breathe Exposure Protocol. Version 2.0.0, Zenodo, 2026, doi:10.5281/zenodo.18906812.

Chicago 17

Elvarin. “BXP Protocol: Breathe Exposure Protocol.” Version 2.0.0. Zenodo, 2026. https://doi.org/10.5281/zenodo.18906812.

What to cite carefully

If your work uses bxpHri, say plainly that the index is experimental and not clinically validated. Citing the specification for the data format and privacy model is straightforward; treating the composite index as a validated health metric would misrepresent the state of the work.

Metadata generated from CITATION.cff and CHANGELOG.md in the repository. ORCID 0009-0001-4856-4986.