Records for developers

Four ways to use Records — embed the open-source engine, work with an AI agent, run the CLI, or wire up an MCP server.

Available · Apache-2.0

Embed the engine

Validation directly in your TypeScript code — Node.js, Bun, edge.

Available · MIT

Records for Claude Code

Build or debug FHIR with an AI agent. Local-first.

Records

Records CLI

Validation gates in your terminal and CI pipelines.

Records

MCP server

Let LLMs query your live Records project — runs, baselines, scores.

Available now · Apache-2.0

Embed the validation engine

The 8-aspect TypeScript engine is open source — published on npm. Use it standalone, no server, no account.

install

npm install @records-fhir/validator

validator.ts

import { recordsValidator } from '@records-fhir/validator';

const resource = { resourceType: 'Patient', id: 'example' };
const profile = 'http://hl7.org/fhir/StructureDefinition/Patient';

const issues = await recordsValidator.validate(resource, profile, 'R4');

const errors = issues.filter((i) => i.severity === 'error');
if (errors.length > 0) {
  for (const issue of errors) {
    console.error(`[${issue.code}] ${issue.location?.join('.')}: ${issue.message}`);
  }
  throw new Error(`${errors.length} validation errors`);
}

Supports FHIR R4, R4B, R5, and R6 — see Compatibility for the full list of tested servers and profile ecosystems. The same engine that powers Records — extracted, audited, and published under Apache-2.0. Bundled core profiles (R4/R5) and selected IGs (MII, UK Core) ship as the optional @records-fhir/bundled-profiles package; load custom StructureDefinition resources through the structure-definition-loader entry point. Records (web UI, evidence reports, drift detection, baselines, governance) remains commercial.

View on npm View on GitHub

Available now · MIT

Records for Claude Code

Validate FHIR resources from inside Claude Code. Local-first — clinical data never leaves your machine by default.

install

claude plugin marketplace add medvertical/claude-records
claude plugin install records@medvertical

invoke

/records:fhir-validation validate ./examples

Ships skills for validation, doctor diagnostics, OperationOutcome explanation, and CI gate generation. Wraps @records-fhir/validator so resources stay local by default — no patient data sent to external services unless you explicitly configure it.

View on GitHub

Records CLI

Validation gates for your terminal and CI

The Records CLI ships with Records. Use it for local file validation, server-side validation runs, baselines, and CI gates.

Quick start

One command. No installation.

Terminal

# Validate a local FHIR file or directory — no server, no setup
npx @records-fhir/cli validate-file ./patient.json

# Or against a Records API with installed profiles
npx @records-fhir/cli \
  --api-url=https://records.example.com \
  --auth-token=$RECORDS_AUTH_TOKEN \
  validate-file ./bundle.json

Runs via npx — no global install required. Works on any machine with Node.js 18+.

Commands

The full DataOps loop — validate, compare, export — from your terminal.

Command	Description
`records validate-file <path>`	Validate a local FHIR file or directory — structural by default, full 8-aspect via API
`records validate <server-id>`	Check the latest validation run for a registered server, or trigger a new one
`records baseline set <run-id>`	Promote a validation run to the known-good baseline
`records baseline compare`	Compare the latest run against the current baseline (delta)
`records server list`	List all registered FHIR servers
`records server add <url>`	Register a new FHIR server endpoint
`records profile install <package>`	Install an IG package (e.g., hl7.fhir.us.core, de.basisprofil.r4)
`records export <run-id\|latest>`	Export validation results as JSON, CSV, or evidence PDF
`records status`	Show connection status and current configuration

All commands support --json for machine-readable output and --quiet for silent operation. Full Unix composability.

Exit codes

CI-native. The exit code IS the signal.

0PASS

All validations passed within configured thresholds

1FAIL

Validation errors exceed configured thresholds

2WARN

Warnings present but within acceptable bounds

3ERROR

Execution error (connection failure, invalid config)

No parsing required. if records validate 1; then deploy; fi — the exit code follows Unix convention and integrates with any CI system.

CI/CD integration

Add FHIR validation to your pipeline in under 5 minutes.

GitHub Actions

# .github/workflows/fhir-gate.yml
- name: FHIR Validation Gate
  run: npx @records-fhir/cli \
    --api-url=${{ secrets.RECORDS_API_URL }} \
    --auth-token=${{ secrets.RECORDS_AUTH_TOKEN }} \
    validate-file ./fhir-resources \
    --format junit

GitLab CI

# .gitlab-ci.yml
fhir-validation:
  stage: test
  image: node:20
  script:
    - npx @records-fhir/cli
        --api-url=$RECORDS_API_URL
        --auth-token=$RECORDS_AUTH_TOKEN
        validate-file ./fhir-resources
        --format junit

Works with GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, CircleCI, Bitbucket Pipelines — any CI system that runs Node.js.

IG author workflow

Regression-test your Implementation Guide on every pull request.

Validate test corpus against installed IG

# Install your IG package once (uses --activate to make it the default)
records profile install your.ig.package --activate

# Validate the test corpus on every PR — full 8-aspect via API
records --api-url $RECORDS_API_URL --auth-token $RECORDS_AUTH_TOKEN \
  validate-file ./test-corpus/ --format junit

Install your IG once with records profile install, then point validate-file at your test resources. Records validates your profiles against real data on every PR. Constraint regressions surface in the PR check — not in downstream implementations weeks later.

Single npx command

A single npx invocation gates every PR. No global install, no extra dependencies to manage.

PR-level delta

Every PR compared against test baseline. New conformance errors block the merge. Resolved errors tracked.

Defect corpus testing

Validate your IG against known-bad resources. Catch constraint regressions before they reach downstream implementers.

Deterministic output

Same inputs → same results. Exit codes follow Unix convention. JSON output for scripting and automation.

Design principles

API-first

Every CLI command maps to a documented REST API call. The CLI never bypasses the API.

Signals, not enforcement

Reports pass/warn/fail via exit codes. Never blocks, rejects, or mutates. Pipelines decide.

Deterministic

Same inputs produce same outputs. No hidden state, no interactive prompts in non-interactive mode.

Unix-composable

Output formats support piping. --json, --quiet, --no-color. Exit codes follow convention.

Try it on your own data.

We'll set up a validation gate in your pipeline — live, in 30 minutes.

CI/CD Use Case