Use Case
Release Safety Gate
Validate before every upgrade, profile change, or mapping update reaches production.
For: FHIR platform engineers, gematik TI manufacturers, EHR certification leads
The problem
You're about to push a change. How do you know it's safe?
Every IG profile update, FHIR server version bump, or terminology mapping change risks introducing silent regressions. A new constraint in an ISiK profile might invalidate hundreds of existing resources. A gematik ISiK Stufe update tightens constraints across all TI-connected systems. A HAPI version upgrade might change how references are resolved. An ONC re-certification cycle requires USCDI v3+ conformance — but you upgraded US-Core and never re-validated.
For TI manufacturers, there is an additional constraint: gematik has stated that Java is incompatible with the security architecture of the E-Rezept Fachdienst. HAPI's JVM-based validator cannot run in these environments — you need a validation gate that works without Java.
Without a systematic validation gate, you're relying on hope — hoping nothing broke, hoping no one notices, hoping the next audit or CMS-0057-F deadline won't surface problems.
How Records solves it
A deterministic pass/fail signal before every release.
Records establishes a baseline after every known-good release. When a change is proposed — an IG profile update, a FHIR server version bump, a mapping rule change — Records runs the same validation against the candidate environment and produces a delta. The delta is the decision surface: new errors, resolved errors, and unchanged issues are classified separately.
Each environment — dev, staging, production — maintains its own baseline. The score rings show current conformance at a glance. A release safety gate means comparing the candidate environment's signal against the target environment's baseline.
Every gate run is tracked. The run history shows score progression across releases — pass, warn, or fail. If new errors appear, the gate fails. If the delta is clean, you promote with evidence, not hope.
Baseline & Delta
Every release candidate is compared against the last validated state. New errors surface immediately — before deployment.
Per-environment tracking
Dev, staging, and production each maintain independent baselines. Promote only when the target environment passes.
Pure TypeScript — no JVM
No Java runtime required. Runs where HAPI cannot — including environments where gematik excludes Java for security reasons.
Reproducibility contract
Validator version, IG packages, and terminology snapshot are pinned. The same gate produces the same result tomorrow.
How to integrate
Add a release safety gate to your deployment pipeline.
CLI command
records validate \
--server=<staging-fhir-api> \
--ig=hl7.fhir.us.core \
--ig=<your-project-ig> \
--baseline=latestWhat gets pinned
| Pin | Purpose |
|---|---|
validator_version | Engine behavior determinism across releases |
ig_packages | Profile set + version locked per gate |
environment_label | Isolates staging from production baselines |
thresholds_applied | Pass/fail criteria consistent across runs |
Run directly via npx @records-fhir/cli — no installation required. For German environments: the Germany Pack (ISiK + MII + KBV + HL7 DE) validates all three parallel profile ecosystems in one gate. For air-gapped environments, deploy the Records Docker image behind your firewall — no Java runtime, no outbound internet required.
What you get
Pass/Warn/Fail signal
Clear status per environment before every release. No ambiguity.
Baseline comparison
See exactly what changed since the last validated state — new errors, resolved errors, unchanged.
Root-cause drill-down
From signal to specific resources and field-level errors in seconds.
Reproducible evidence
Audit-grade reports for ONC re-certification, ISiK Stufe upgrades, USCDI migrations, and compliance trails.
Triage lifecycle
Every issue moves from Open to Acknowledged to Verified to Closed — with evidence at each transition.
Environment-aware
Compare signals across dev, staging, and production before promoting any change.
Why a gate needs continuous validation
Snapshot validation proves conformance at validation time. It proves nothing about tomorrow.
| Snapshot ($validate) | Records Release Gate | |
|---|---|---|
| When it runs | Once, at deployment | On every change, continuously |
| What it checks | Single resource | Full dataset against all configured profiles |
| Drift detection | ne | Automatic delta against baseline |
| Evidence output | Pass/fail per resource | Audit-grade report with reproducibility contract |
| Regression tracking | ne | Full history with per-issue lifecycle |
Frequently asked questions
Any change to IG profiles, FHIR server version, mapping configuration, or terminology sources. Records can be triggered manually, via a CI/CD pipeline step, or on a cron schedule.
Records produces a FAIL signal with a delta report showing exactly which new errors appeared compared to the baseline. The deployment is not blocked automatically — Records produces evidence; your team makes the decision.
Depends on dataset size and number of profiles. Typical runs against a few thousand resources complete in 2–5 minutes. Records validates in parallel and reports progress in real time.
No. Records issues only GET and HEAD requests. It never writes, modifies, or deletes data on your FHIR server or any external system.
Yes. Records is available as a Docker container for on-premise deployment. No outbound internet is required. Your data never leaves your network.
See this on your own data.
We'll validate your FHIR server against your profiles — live, in 30 minutes.