0. Conformance

Requirement prefix: C0.

This section defines the language the rest of the specification is written in, and what a claim made in it means.

Normative language#

• C0.1 The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in RFC 2119.
• C0.2 A sentence without one of those keywords is explanatory. It gives the reason for a requirement; it is not itself one.
• C0.3 Where this specification and the openEHR specifications conflict, and this specification does not explicitly declare a departure, the openEHR specification governs and this document has a defect. Record it in audit.md.

Requirement identifiers#

• C0.4 Every normative statement MUST carry an identifier of the form <prefix><section>.<ordinal>[<suffix>], where the prefix is fixed per section by the index — D3.7, X11.7a, Q12.9.
• C0.5 Identifiers are permanent. They MUST NOT be renumbered and MUST NOT be reused for a different requirement.
  • Withdrawing a requirement keeps its number, marked withdrawn.
  • Amending a requirement keeps its number.
  • Splitting one uses letter suffixes (D3.7 → D3.7a, D3.7b); the parent survives and says what it was split into.
  • Adding one takes the next unused ordinal in the section. Never insert mid-sequence by shifting.
• C0.6 Section numbers have no gaps in this specification, and any that appear later MUST NOT be closed.

What a conformance claim means#

• C0.7 A requirement is satisfied when the code implements it and a test demonstrates it.
• C0.8 A requirement is unverified when the code appears to implement it and no test exercises it. Unverified is recorded as ? in the conformance matrix, never as satisfied.
• C0.9 A gap that is not written down reads as a pass. Every known gap between this specification, the documentation, and the code MUST appear in audit.md with evidence a reader can check.
• C0.10 A test that cannot fail does not verify anything. Every test cited as evidence for a requirement MUST have been shown to fail when the behaviour it checks is removed or inverted (T13.2).
• C0.11 Documentation MUST NOT claim more than is verified. In particular, "the same code path works elsewhere" is not evidence for a requirement here.

Departures from openEHR#

• C0.12 Where this crate does not do what an openEHR specification says, it MUST be recorded as a numbered requirement that names what it departs from and states what holds instead.
• C0.13 A departure MUST state which of the amended requirement's guarantees survive, so a reader can tell a narrowing from a contradiction.
• C0.14 Implementing something different from openEHR and mentioning it only in a code comment is a defect, not a departure.

Amending this specification#

• C0.15 An amendment edits the section in place, keeping the identifier (C0.5), and states the reason in the commit message.
• C0.16 An amendment made to match what the code already does MUST say so. A considered generalization and a rubber stamp are indistinguishable afterwards.
• C0.17 Every amendment MUST be checked against the conformance matrix — does it change a status? — and against audit.md — does it close a finding, or open one?
• C0.18 A requirement withdrawn because the behaviour was removed MUST keep its identifier and be marked withdrawn, with the release in which it went.

Vocabulary#