Skip to content

Executable Contract Backlog

Intent

Make requirements testable using conformance statements + examples + tests, tracked to issues.

Structure

The executable contract backlog is a linked set of requirements, artifacts, and tests that can be run automatically. Structurally, it combines: conformance statements (what must be true), artifacts that enforce them (profiles/terminology/examples), and checks that prove them (CI gates).

  • Statement registry: RFC2119-style statements with stable IDs and rationale
  • Artifact links: each statement points to the enforcing profile rule, terminology binding, and example(s)
  • Test links: each statement has at least one positive test (and negative test for high-risk rules)
  • Work tracking: statements map to issues/PRs so progress is visible and reviewable
  • Definition of Done: objective acceptance criteria that must be satisfied before a statement is considered implemented

Key Components

Conformance statements

  • Write requirements as RFC2119-style statements (MUST/SHOULD/MAY)
  • Assign stable IDs so statements can be referenced and tracked
  • Attach rationale so reviewers understand the ‘why’
  • Link to the profile/terminology element that enforces it
  • Keep statements small and independently testable

Test cases

  • For each statement, define positive and (when risk is high) negative tests
  • Use examples as inputs whenever possible
  • Specify what tooling runs the test (IG Publisher, terminology server, etc.)
  • Keep quick feedback tests in the PR gate
  • Track flaky tests separately and fix root causes
  • Link statements to issues/requirements in a tracker
  • Link statements to profiles, ValueSets, examples, and tests
  • Keep traceability lightweight but consistent
  • Use consistent identifiers in filenames and commit messages
  • Make it easy to answer: ‘what changed and why?’

Definition of Done

  • Define the minimum bar for accepting a requirement into the IG
  • Include validation, rendering, example coverage, and review expectations
  • Ensure DONE is objective (pass/fail), not subjective
  • Revisit the DoD when releases get blocked by repeated issues
  • Keep the DoD visible in the repo

Behavior

Backlog lifecycle

Requirements move through a small lifecycle: propose → implement → validate → ship. The ‘executable’ part is what keeps the backlog honest.

Define

  • Write a conformance statement with a stable ID and rationale.
  • Decide how it will be enforced (profile constraint, binding strength, invariant, terminology policy).
  • Define how it will be tested (validator, terminology server op, cross-product harness).

Implement

  • Add the enforcing artifact changes (FSH, terminology artifacts, narrative).
  • Add/update examples so the requirement is demonstrably met.
  • Add CI checks so violations fail fast with actionable messages.

Operate

  • Triage failures: distinguish tool drift vs true regressions.
  • When changes are needed, update statement, artifact, and tests together.
  • Ship with release notes so implementers can track what changed and why.

Benefits

  • Less rework
  • Automated gating
  • Vendor alignment

Trade-offs

  • Needs discipline and triage

References

Example

For each MUST statement: provide example(s) and a CI check that fails when violated.