Conformance specs

A conformance spec says what your interface actually requires, in a form that passes or fails a message rather than describing it in prose. It reads like a document, behaves like a test suite, and is one YAML file.

What a spec is

Base HL7v2 says PID-3 is an identifier. It does not say that yours must carry an MRN from a particular assigning authority, that PV1-2 is only ever I or O, or that a missing PID-5 is the bug that pages someone at 2am. That knowledge usually lives in a PDF nobody opens and in the heads of two people.

A spec is that knowledge written as rules a machine can apply. Every rule has a location, a constraint, and - if you write one - a rationale saying why it exists, which is the part a PDF is actually bad at keeping.

Create one

Go to /specs and pick New spec. You can start blank, or infer one from messages you already have. The second is usually the right call: point it at a folder, a zip, or a single file holding thousands, and it reads what your interface actually does rather than what the standard permits.

What inference gives you that a blank page cannot:

It finds	Why that matters
Required fields, by presence ratio	A field in 100% of messages becomes an error rule; one in half becomes a warning. The thresholds are yours to set.
Custom Z-segments	The segments nobody documented, discovered from the traffic itself.
The value sets you really send	Not "PV1-2 is one of the 30 codes in table 0004" - "PV1-2 is only ever I or O here". That is the rule that catches a vendor sending something new.
Date and number formats	Inferred from the shape of the values themselves.

Patient identifiers are removed on the way in

The messages that make the best spec are real ones, and a real one carries a real patient. Identifiers - names, MRNs, addresses, telecoms, dates of birth, free text - are redacted as the file is read, before anything is stored. Coded values are deliberately kept, because those are categories rather than people and they are exactly what the inference learns from. It runs in your browser; nothing is uploaded to do it.

You do not need an account to try this

Signed out, specs are kept in your browser's IndexedDB and never leave it. Signing in moves them to your organisation so they can be shared, versioned and enforced - at which point the examples saved in a spec are stored with it. See trust & data handling.

The five views

View	What it is for
`Edit`	The document. Rules organised by message type, then segment, each with an optional rationale. This is the view you write in.
`Studio`	Real messages. Click any field to add a rule from what you are looking at, rather than from memory.
`Publish`	The spec as it will read to someone else, and the controls to cut a production version. Export as Markdown or a branded PDF.
`Source`	The raw YAML, editable. Everything the other views do is a change to this file.
`Traffic`	What has actually been validated against this spec - counts, outcomes and timings. No message content.

Rules

A rule targets a segment, a field, or a component within a field, and applies one constraint. The common ones:

Constraint	Means
Required / forbidden	The field must be populated, or must not be.
Equals / not equals	An exact value.
One of / not one of	A closed list of allowed or disallowed values.
Matches	A regular expression, length-capped so a pattern cannot hang the evaluator.
Length and cardinality	Bounds on the value, and on how many times a field may repeat.
Conditional	Any of the above, but only when another part of the message holds - "PID-5 is required when PV1-2 is I".

Field-level rules match a later component too

A rule on a field also passes when a later component matches, so MSH-9 equals ADT means "this is an ADT message" without addressing MSH-9.1. When the position matters, target the component explicitly.

Examples as regression tests

In Studio, save a message against the spec and mark what you expect: a production sample should pass, a counter-example should fail. Both are stored in the spec and re-evaluated every time it changes.

This is the part that makes a spec hold up over time. A rule you tighten six months from now will tell you immediately if it breaks a message you already agreed was valid - which is exactly the failure a prose document cannot catch.

Draft and production

A spec has a draft you are editing and, once you publish, a production version. They are separate on purpose: anything enforcing your spec - CI, the validation API, a Bridge agent - always evaluates the production version, so editing a rule cannot change what a vendor is being held to until you decide it should.

Publish from the Publish view. You give the release a version and optional release notes, and that snapshot becomes what the outside world sees.

Versions and revisions

Every publish is kept. You can see the history, read what changed, and restore an earlier revision if a release turns out to be wrong. Share portals expose a version history tab so the vendor on the other end can see the same thing.

Callers can pin a version rather than tracking production - append @1.2.3 to the spec slug in the CLI, pass ?version=1.2.3 to the validation API, or set version on a Bridge listener. That is how you hold a vendor to the spec you both agreed to while you keep working on the next one.

Enforcing a spec

Where	How
In the browser	Paste a message into the Test panel and see per-rule pass/fail as you type. Free, no account.
In CI	The CLI validates files against a published spec and exits non-zero on failure.
From your own code	POST to the validation API and read a structured report.
On live traffic	The Bridge agent validates MLLP traffic in your network against a signed copy of the spec.

The YAML file

A spec is one file. Export it from the Publish view, keep it in your repository next to the interface it describes, and review changes to it in a pull request like any other code. Import brings a file back in.

# Sketch of the shape - the Source view shows the real thing
slug: adt-strict
name: ADT inbound (strict)
version: 1.2.0
messageTypes:
  - ADT
rules:
  - id: pid-5-required
    selector: { kind: field, segment: PID, field: 5 }
    constraint: { kind: required }
    rationale: >
      Downstream registration rejects a patient with no name, and the
      rejection is silent, so we catch it here instead.
examples:
  - name: Standard admit
    expect: pass
    raw: "MSH|^~\\&|..."

An imported spec is someone else's file

Branding URLs in an imported spec are passed through a scheme allowlist before anything renders them, but treat an imported spec the way you would treat any file from outside: read it before you publish it.

Limits

Plan	Saved specs	Share links
Free	1	None
Solo	5	3
Team	25	25
Production	Unlimited	Unlimited

Authoring and testing a spec in the browser is free and unmetered. What the plans govern is saving them, sharing them, and validating against them from outside the browser. See pricing.