Open source
The validation engine, in the open.
The same eight-aspect engine that powers Records, published under Apache-2.0. Pure TypeScript, no JVM, no server, no account. You can inspect its dated conformance evidence yourself.
Source
Inspect the TypeScript engine
Scope
Choose the profiles and checks
Evidence
Review archived results and limits
A newer diagnostic snapshot includes unresolved differences.
CI artifacts measured 2026-09-21, reviewed 2026-09-28. These are case pass counts under each comparison policy, not exact issue equality or a score for the current npm release.
| Comparison | Passed / executed | Failed | Skipped | Interpretation |
|---|---|---|---|---|
| HL7 R4 JSON | 383 / 385 | 2 | 5 | Two failures remain in the raw report; the workflow gate passes with explicit exceptions. |
| HL7 R4B JSON | 8 / 8 | 0 | 0 | Eight measured compatibility cases; this is a small scope. |
| HL7 R5 JSON | 134 / 138 | 4 | 0 | Four comparisons fail in this recorded run. |
| MII reference | 137 / 150 | 13 | 103 | 91 skips for incomplete reference terminology and 12 for unmapped corpus profiles. Failures need engine, comparator and terminology diagnosis. |
| EPS / HAPI | 7 / 8 | 1 | 0 | One comparison misses additional-binding-unavailable coverage evidence. The separate local Records matrix is a different check. |
The quality corpus detected 274/274 seeded issues. Precision was not established: a missing upstream fixture stopped the first clean-input check and later precision steps were skipped. A detection result alone does not measure false positives.
The workflow head was 61a4bca. R4 and R5 reports record dirty working trees and input digests; these measurements do not identify a certified current package. Inspect the dated summary, provenance and source hashes. The older selected archives remain separately described below.
Archived measurements, with their limits.
The selected historical JSON report records 533 of 533 executed cases passing the harness threshold, with three runtime skips. Of those cases, 513 scored exact agreement and 20 retained differences.
Measured by Records 0.10.1 on 2026-08-25 against FHIR/fhir-test-cases at commit 8923095. Both the suite and the commit are public, and the source artifact is conformance-results/report-2026-08-24.json. The archive does not record the tested npm package versions or source revision. Its results cannot be assigned to the currently published v0.9.18 package.
The earlier 536/536 headline was withdrawn after profile-source loading defects were found in its harness. The archive separates passed thresholds, exact scores, residual differences, and skipped cases. Inspect the archived measurement summary and source hashes.
A second reference: the MII lane
Beyond the HL7 suite, Records is measured against the official mii reference validator: 231/231 archived reference cases passed on 2026-07-23, with 22 classified skips outside the measured lane. This separate archive does not certify a site, the MII programme, or the current npm package.
What the number does and does not mean
Passing the recorded harness threshold is different from exact agreement. The archive contains 513 exact scores and 20 residual differences, with 3 runtime skips. It does not mean support for every one of the 969 entries in the upstream manifest. 433 entries sit outside this lane, and they are listed below rather than folded into a friendlier percentage.
What sits outside the lane
Every one of the 433 excluded manifest entries, and why. A conformance number is only useful if its boundary is published with it.
| Excluded | Cases | Status |
|---|---|---|
| XML resources | 299 | The XML adapter ships; its Java-baseline score is a separate lane. |
| Adjacent standards (CDA, HL7 v2, CDS Hooks, SHC, XVer, DSIG, JSON5) | 68 | Each needs a dedicated module and its own score. |
| Legacy FHIR versions (DSTU2, STU3) | 47 | Out of scope unless legacy support becomes a product target. |
| Disabled upstream (`use-test: false`) | 17 | Excluded by the upstream manifest itself. |
| No Java baseline declared | 1 | An upstream teardown workaround, not a validator comparison. |
| Logical model test | 1 | Awaiting a logical-model validation lane. |
XML parsing, NDJSON input, and the FHIR Schema path all ship in the engine. They are reported as their own lanes rather than blended into the headline, because a single averaged percentage across unlike test classes is not a measurement.
Resolve, validate, explain
Keep the selected validation basis and the resulting findings connected.
- Step 1 of 3.
Resolve
Select the FHIR release, the declared and configured profiles, IG packages, terminology sources, and custom rules — before a single check runs.
A finding is only comparable if the basis that produced it is fixed.
- Step 2 of 3.
Validate
Run the eight aspects against the resolved basis. Each aspect is independently configurable by severity and strictness.
Aspects stay separable, so a terminology problem never hides behind a structural one.
- Step 3 of 3.
Explain
Keep severity, resource and element path, the rule or canonical source, the package version, and the configuration fingerprint attached to every finding.
An error message without its basis cannot be acted on or re-checked.
Eight aspects, independently configurable
Each aspect can be enabled, tuned by severity, and read on its own. That separation is what makes a result diagnosable instead of just red.
| Structural | JSON structure, required fields, cardinality, type constraints |
| Profile | StructureDefinition conformance and discriminator-based slicing |
| Terminology | CodeSystem and ValueSet bindings, local expansion with server fallback |
| Reference | Reference existence, target type checking, circular detection |
| Invariant | FHIRPath constraints declared on StructureDefinitions |
| Custom rules | Your own FHIRPath business rules, plus advisor overrides |
| Metadata | `meta` completeness and security labels |
| Anomaly | Statistical outliers across a resource population |
Three ways to run it
Apache-2.0, v0.9.18 on npm. FHIR R4, R4B, R5, and R6.
npx -p @records-fhir/validator records-fhir-validator ./fixtures --fail-on=warningimport { createFilesystemProfileSource, recordsValidator, setProfileSource,} from '@records-fhir/validator';// Extract hl7.fhir.r4.core 4.0.1 here before running:// profiles/hl7.fhir.r4.core#4.0.1/package/*.jsonsetProfileSource(createFilesystemProfileSource({ packageDirs: ['./profiles'], packageVersionPins: { 'hl7.fhir.r4.core': '4.0.1' },}));const issues = await recordsValidator.validateRequest({ resource: { resourceType: 'Patient', id: 'example', active: 'yes' }, profileUrl: 'http://hl7.org/fhir/StructureDefinition/Patient', fhirVersion: 'R4',});// The negative control should flag the string at Patient.active.- uses: medvertical/records-fhir-validator@v0 with: paths: resources/**/*.json fhir-version: R4 fail-on: errorThe TypeScript example needs the extracted R4 core package and a negative control. Use the tested setup, complete script and recorded output. This checks one primitive type; configure and test further dependencies for your implementation guide.
Where the engine ends and Records begins
The boundary is deliberate and stated here rather than discovered later.
Apache-2.0
In the open engine
- The eight-aspect validation runtime
- StructureDefinition loading from FHIR packages
- FHIRPath invariant execution and slicing
- Terminology, reference, metadata, and Bundle validators
- OperationOutcome conversion, CLI, and GitHub Action
Commercial
In Records
- Continuous validation against live FHIR servers
- Baselines, deltas, and drift detection over time
- Quality gates, triage, and cross-server comparison
- Evidence reports with the reproducibility contract
- Workspaces, RBAC, and on-prem deployment
A validator answers is this valid now? Records answers the question a running system actually has: will we know when it stops being valid? The engine is the honest half of that — take it, embed it, fork it. The half that watches it over time is the product.
Start with the engine. Stay for the loop.
Validate a file in the next minute, then see what continuous validation adds on a real public FHIR server.