sdk · version policy

Canonical URLs, pinning, and changelogs.

Canonical URLs are stable identifiers. Package versions are not — in v0.x, minor versions may carry breaking changes. Pin to an exact version and upgrade deliberately.

← SDK Hub

Canonical base URL

All canonical URLs use one base.

The canonical base for all FHIR StructureDefinitions, CodeSystems, NamingSystems, and other artifacts in the Praxis IG is:

https://fhir.cognovis.de/praxis/

StructureDefinitions

https://fhir.cognovis.de/praxis/
  StructureDefinition/arrival-time

CodeSystems

https://fhir.cognovis.de/praxis/
  CodeSystem/scheinart

NamingSystems

https://fhir.cognovis.de/praxis/
  NamingSystem/pvs-id

Legacy URLs

Legacy URLs using the mira.cognovis.de/fhir domain must be migrated to the canonical base. The constant CANONICAL_BASE from @polaris/fhir-de always reflects the current canonical base — use it when constructing dynamic URLs.

import { CANONICAL_BASE } from '@polaris/fhir-de'
// CANONICAL_BASE = 'https://fhir.cognovis.de/praxis'

Version pinning

Pin to exact versions in v0.x.

The package follows semver. However, in the v0.x series, minor versions may carry breaking changes — this is the standard v0.x convention. Do not use ^0.1.1 in your lockfile; pin to the exact version you tested against.

Correct — exact pin in package.json

{
  "dependencies": {
    "@polaris/fhir-de": "0.1.1"
  }
}

Exact version without caret or tilde. Bun and npm both honor this.

Avoid — caret range in v0.x

{
  "dependencies": {
    "@polaris/fhir-de": "^0.1.1"  // resolves to >=0.1.1 <0.2.0 — unsafe in 0.x
  }
}

For 0.x packages, minor version bumps (0.1.x → 0.2.x) MAY contain breaking changes to extension URLs, builder signatures, or generated types. Pin to an exact version or a patch range (~0.1.1) to avoid surprises.

Check the current published version

# Query the registry directly
curl -s https://npm.cognovis.de/@polaris/fhir-de | jq '."dist-tags".latest'

# Or check the associated IG versions
curl -s https://npm.cognovis.de/de.cognovis.fhir.praxis | jq '."dist-tags".latest'

Changelog format

What changes between versions.

Each release marks which surfaces changed. Breaking changes in extension URLs, builder signatures, and generated types are marked explicitly.

Extension URL changes

When an IG version renames a StructureDefinition URL, the constant in @polaris/fhir-de is updated to match. Existing FHIR resources stored with the old URL require migration. The changelog notes all URL changes explicitly with the old and new value.

Builder signature changes

Builder argument types may change when the underlying IG profile adds required elements. The TypeScript types will produce compilation errors at the call site — this is intentional and surfaces the breaking change at build time.

Generated type changes

Generated profile classes (in generated/) are regenerated from IG packages on each release. New required properties or removed optional properties constitute breaking changes in a v0.x release.

Upgrade procedure

01 Read the CHANGELOG.md for the target version — check for URL renames and signature changes.
02 Update the exact version in package.json and run the install.
03 Run bun x tsc --noEmit — TypeScript will flag broken call sites.
04 If extension URLs changed, migrate existing Aidbox resources to the new canonical URL before deploying.

v1.0 stability promise

Once @polaris/fhir-de reaches v1.0.0, the public API surface (builder signatures, exported constants, client API) will follow strict semver — breaking changes only in major versions. The v0.x series is explicitly pre-stable.

Registry as source of truth

The registry at npm.cognovis.de is the canonical package source. The dist/ folder in the source repo is a local build artifact and is not authoritative — always install from the registry.