Skip to content

Profile Minimalism with Justification

Intent

Every constraint must have a reason, an example, and a test; keep profiles lean.

Structure

Profile minimalism is a constraint architecture: only add constraints that have a rationale, an example, and a test. Structurally it organizes constraints, invariants, and MustSupport expectations so they remain bounded and implementable.

  • Rationale capture: each non-trivial constraint has an explicit ‘why’ tied to a workflow step/force
  • MustSupport policy: a written interpretation (producer/consumer obligations) with bounded lists
  • Invariant library: reusable, named invariants rather than duplicated FHIRPath
  • Example set: small, representative examples that validate and render, including edge cases
  • Test mapping: statements/tests that prove constraints work and remain stable over time

Key Components

Constraint rationale

  • Record why each constraint exists (interoperability, safety, policy)
  • Link rationale to a force or use-case step
  • Note implementer impact and alternatives
  • Require rationale before adding complex constraints
  • Keep rationale close to the artifact (comments or narrative)

MustSupport policy

  • Define what MustSupport means for producers and consumers
  • Keep MustSupport lists bounded
  • Tie MustSupport to workflow needs and tests
  • Avoid MustSupport as a proxy for ‘important’ without evidence
  • Revisit MustSupport as scope evolves

Invariant library

  • Reuse invariants instead of duplicating FHIRPath expressions
  • Name invariants predictably
  • Test invariants via examples
  • Keep invariants readable and documented
  • Avoid overly complex expressions without tests

Example coverage

  • Ensure examples cover required slices, bindings, and edge cases
  • Add negative examples for high-risk rules
  • Keep example set small but representative
  • Ensure examples validate in CI
  • Link examples to statements/tests

Behavior

Constraint decision behavior

Constraints are added slowly and deliberately, and removed/refined when they don’t improve interoperability.

Before adding a constraint

  1. State the interoperability problem the constraint solves.
  2. Check if a simpler approach works (example guidance, MustSupport policy, terminology change).
  3. Define how you will test it and what failure should look like.

After adding a constraint

  1. Add/adjust examples so the rule is demonstrably satisfied.
  2. Run validator gates and ensure failures are understandable.
  3. Collect implementer feedback; remove or adjust constraints that create friction without benefit.

Benefits

  • Easier adoption
  • Less validator friction

Trade-offs

  • Stakeholders may push for more constraints early