Developers

Records for developers

Start with a public FHIR validation CLI for local files and CI gates. Then embed the engine, work with an AI agent, or connect to Records for baselines, drift, and evidence.

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.

Public npm · Apache-2.0

Records CLI

Copy/paste FHIR validation gates for terminal and CI.

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-recordsclaude 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

Public npm · Apache-2.0

FHIR validation gates for your terminal and CI

The Records CLI is a public npm package for local FHIR file validation and CI gates. Advanced workflows connect to Records for server-side runs, baselines, drift comparison, and evidence reports.

Copy/paste CI gate

npx @records-fhir/cli validate-file ./fhir \  --engine \  --format junit

Use it when you need:

local validation for FHIR JSON files and directories
pull-request gates in GitHub Actions or any Node.js CI
JSON/JUnit output and deterministic exit codes

GitHub npm GitHub Actions guide

Quick start

One command. No installation.

Terminal

# Validate a local FHIR file or directory — no server, no setupnpx @records-fhir/cli validate-file ./patient.json# Or against a Records API for full configured validationnpx @records-fhir/cli \  --api-url=https://records.example.com/api \  --auth-token=$RECORDS_AUTH_TOKEN \  validate-file ./bundle.json

Free local mode runs without an account or server. Records mode uses the same package with API credentials for full validation, baselines, drift comparison, and evidence workflows.

Commands

Free local validation plus the full Records DataOps loop when connected to a Records instance.

Command	Description
`records validate-file <path>`	Validate a local FHIR file or directory — free local mode by default, Records API mode when configured
`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

validate-file runs locally without Records. Commands that manage servers, profiles, baselines, runs, and exports require a Records API. All commands support machine-readable output for CI.

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-file ./fhir --engine; then deploy; fi — the exit code follows Unix convention and integrates with any CI system.

CI/CD integration

Add FHIR validation to your pipeline with one CLI step.

GitHub Actions

# .github/workflows/fhir-gate.yml- name: FHIR Local Validation Gate  run: npx @records-fhir/cli \    validate-file ./fhir-resources \    --engine \    --format junit

Records API Gate

# Full configured validation with Records- name: Records 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

Works with GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, CircleCI, Bitbucket Pipelines — any CI system that runs Node.js. Use free local validation for quick gates, then connect the same CLI to Records when you need profile packages, baselines, drift, and evidence.

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 APIrecords --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

Local validation runs in-process. Records workflows map to documented REST API calls and never bypass 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.

Talk to us about developer workflows.

Share your context, question, or integration idea. We'll help you identify the right next step.

CI/CD Use Case