The `openehr` crate specification

This directory is normative for the openehr crate. It says what must be true; the code says how. When the two disagree, reconcile them — do not let them drift.

Requirements use RFC 2119 keywords (MUST, SHOULD, MAY) as defined in §0 Conformance, and every one carries a stable identifier that is cited from the code, the tests, and this documentation. That trace — openEHR specification → requirement → code → test → matrix — is what makes a claim about this crate checkable years later by someone who was not here.

Relationship to the openEHR specifications#

openEHR is specified at specifications.openehr.org. Those documents are the authority; this directory is not. What lives here is everything that a Rust implementation has to decide and openEHR does not say:

openEHR says	This spec says
`DV_DATE.value` is an ISO 8601 date string	which forms are accepted, and that partial precision is preserved (`D3.9`)
`DV_ORDERED` declares `is_strictly_comparable_to`	that non-comparable values yield `None`, not `false` (`D3.14`)
`_type` is required where the declared type is abstract	which classes emit it and which infer it on input (`J9.4`)
access control is scheme-agnostic	that an unevaluatable scheme denies and round-trips (`X11.3`)
—	what is out of scope, and how the code says so (`S1.9`)

Where openEHR is ambiguous or its own documents disagree, the resolution is recorded with the reason, not silently chosen. Where this crate departs from openEHR, the departure is written down as a requirement that names what it departs from; an undeclared departure is a defect, not a decision.

Contents#

Framework#

0. Conformance — C0.x. Normative language, requirement-id grammar, what a conformance claim means, how to amend.
1. Scope — S1.x. What is implemented, what is deliberately excluded, and how an exclusion behaves at runtime.

The Reference Model#

2. Identifiers — I2.x. UID, OBJECT_ID and descendants, OBJECT_REF, and the lexical grammars.
3. Data types — D3.x. DATA_VALUE and every descendant, including comparison and ISO 8601 handling.
4. Data structures — R4.x. ITEM_STRUCTURE, CLUSTER, ELEMENT, null flavours, HISTORY and events.
5. Common and archetyping — M5.x. LOCATABLE, ARCHETYPED, LINK, FEEDER_AUDIT, parties, participation.
6. EHR and composition — E6.x. EHR, EHR_STATUS, COMPOSITION, sections, the five entry classes, folders.
7. Demographics — G7.x. PARTY, ACTOR, ROLE, identities, contacts, capabilities.
8. Versioning and change control — V8.x. VERSIONED_OBJECT, VERSION, CONTRIBUTION, AUDIT_DETAILS, ATTESTATION.

Cross-cutting#

9. Serialization — J9.x. openEHR canonical JSON: what is emitted, what is accepted, and what round-trips.
10. Validation — L10.x. Which invariants are checked, where, and what a passing validation does not mean.
11. Security — X11.x. The trust boundary, access control, the audit chain, redaction, and PHI in output.
12. Paths and query — Q12.x. openEHR path syntax and navigation; AQL lexing, parsing, and static checks.

Assurance#

13. Conformance testing — T13.x. What must be tested, how a test proves it can fail, and what a skipped check must say.
14. Compliance mapping — a table, not requirements. Which requirements a regulator's control maps onto.

Status, not requirements#

Conformance matrix — which requirements are satisfied and verified today. Non-normative: it records reality, not intent.
Audit — the findings register: every known gap between what this spec requires, what the documentation claims, and what the code does.

The rules that cost nothing to keep and cannot be repaired once broken#

Requirement ids are permanent (C0.5). Never renumber, never reuse.
A gap that is not written down reads as a pass (C0.9). Unverified goes in audit.md and shows as ? in the matrix, not •.
Do not claim above what is verified (C0.11). "The code is shared with a path that works" is ?, not •.
Behaviour is decided here first. Discovering a requirement while implementing is normal; the fix is to write it here before the commit lands.

The openehr crate specification