Versioning

Phosra pins versions at four layers — the API path, the OCSS spec version, dated Annex B editions, and the SDK semver. Each is stable and additive, so code you ship today keeps working.

The four layers

API version — it is in the path

The major version is the first path segment. Everything under /api/v1 shares one contract, and additions inside v1 are backward-compatible. A future breaking change gets a new path — v1 is never mutated under you.

BASE=https://phosra-api-sandbox-production.up.railway.app
curl -s -o /dev/null -w "v1 → %{http_code}\n" "$BASE/api/v1/platforms"   # → v1 → 200
curl -s -o /dev/null -w "v2 → %{http_code}\n" "$BASE/api/v2/platforms"   # → v2 → 404 (no v2 yet)

OCSS spec version

The protocol carried over the API has its own version, OCSS-v1.0-pre. You can read the census's binding of it directly from the (unmetered, unauthenticated) trust list:

BASE=https://phosra-api-sandbox-production.up.railway.app
curl -s "$BASE/.well-known/ocss/trust-list" \
  | python3 -c "import sys,json; d=json.loads(json.load(sys.stdin)['document']); \
print('ocss_version =', d['ocss_version']); print('schema_version =', d['schema_version'])"

ocss_version = OCSS-v1.0-pre
schema_version = 1

On signed census writes, your client declares which spec it built against by setting the OCSS-Spec-Version request header (covered by your RFC 9421 signature). Send OCSS-v1.0-pre; the census pins its own side via ocss_version, so a mismatch is detectable rather than silent.

Dated artifacts — Annex B editions

Governed content (the rule registry, statute mappings) is published as frozen, numbered Annex B editions. An edition is content-addressed and immutable: once edition N is cut, its bytes never change, and its ETag is the artifact hash. Pin to an edition number and you have pinned to exact bytes forever.

BASE=https://phosra-api-sandbox-production.up.railway.app
curl -s -o /dev/null -w "edition 1 → %{http_code}\n" "$BASE/api/v1/annex-b/editions/1"
# → edition 1 → 404   (the sandbox census is pre-Edition-1; no editions frozen yet)

Conditional reads and caching

Discovery artifacts (the trust list, profiles, editions) return a strong ETag and Cache-Control: public, max-age=300. Send the ETag back as If-None-Match to get an empty 304 when nothing moved — free, and it does not count against your rate limit.

BASE=https://phosra-api-sandbox-production.up.railway.app
# 1. First read — capture the ETag
ETAG=$(curl -s -D - -o /dev/null "$BASE/.well-known/ocss/trust-list" \
  | tr -d '\r' | awk 'tolower($1)=="etag:"{print $2}')
 
# 2. Conditional read — 304 while unchanged, 200 + body when it moves
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "If-None-Match: $ETAG" "$BASE/.well-known/ocss/trust-list"
# → 304

The trust list also carries a monotonic issue serial so you can detect a change without diffing the body — a higher issue.number means the census re-issued:

curl -s "$BASE/.well-known/ocss/trust-list" \
  | python3 -c "import sys,json; i=json.loads(json.load(sys.stdin)['document'])['issue']; \
print('issue #', i['number'], 'at', i['issued_at'])"
# e.g. → issue # 136 at 2026-07-06T06:44:43Z

SDK versioning — pin exact

The published SDKs follow semver. Pin the exact version you tested against and bump deliberately; do not float on a caret range in production.

# Pin exact — reproducible installs, no surprise breaks
npm install @phosra/[email protected] @openchildsafety/[email protected]

Staying forward-compatible

Next steps