Concepts

Versions & releases

Canonical version ids, status, and what "release" means for DTPR.

Every version id is canonical — there is no latest shorthand. Discover ids from GET /schemas and pin on one.

Canonical form

<datachain_type>@<YYYY-MM-DD>[-<suffix>]

datachain_type — dtpr, the consolidated type. The superseded ai line is still served for consumers pinned to it.
YYYY-MM-DD — the release's authorship date.
optional -suffix — -beta during authoring. Stable releases drop the suffix.

Examples: dtpr@2026-09-01, dtpr@2026-09-01-beta.

The type id changed at dtpr@2026-09-01-beta. That release merged the ai and device taxonomies into a single dtpr type, so the version prefix moved with it. Earlier versions keep their ai@ ids — the type id is part of the canonical version id, so a rename means a new version, never a rewrite of an old one. The ai@ line receives no further versions.

Status

Every version has a status:

Status	Meaning	Cache-Control
`stable`	Immutable. Content is frozen.	`public, max-age=86400, immutable`
`beta`	In-progress authoring. Content may change.	`no-store`

Beta versions are served without caching so authoring iterations land immediately. Stable versions are aggressively cached.

There are no aliases

Every version is addressed by its canonical id. dtpr@latest is not a thing — the API rejects it with 400 (Use the canonical 'type@YYYY-MM-DD[-beta]' form.), and schemas/index.json publishes no alias field. Each entry carries exactly id, status, created_at, and content_hash.

To pick up the newest version, read it at runtime rather than guessing a name:

LATEST=$(curl -s https://api.dtpr.io/api/v2/schemas \
  | jq -r '.versions | sort_by(.created_at) | last | .id')

curl -s "https://api.dtpr.io/api/v2/schemas/$LATEST/manifest"

For production integrations, resolve the id once via GET /schemas or list_schema_versions, then pin it — following "newest" automatically means a beta re-authoring can change content under you.

Release flow

beta authoring ──► beta preview ──► stable promotion
dtpr@2026-XX-YY-beta               dtpr@2026-XX-YY
   (no-store)                        (immutable)

Once a version is promoted to stable, its content_hash stops changing. The content hash is the deterministic handle you can use to detect drift.

URL encoding

The canonical form contains an @ which should not require URL encoding, but the API accepts both the raw dtpr@2026-09-01-beta and the %40-encoded form:

/api/v2/schemas/dtpr@2026-09-01-beta/manifest
/api/v2/schemas/dtpr%402026-09-01-beta/manifest

Both resolve to the same version.