Skip to content

Example-Driven Profiling

Intent

Use examples as first-class design artifacts; every profile/value set validates and renders.

Structure

Example-driven profiling makes examples the primary design artifacts that drive constraints and documentation. Structurally it relies on curated example bundles, explicit negative examples, and narrative links that keep guidance aligned with executable artifacts.

  • Example bundles: one per core scenario, containing all referenced resources so the story is complete
  • Validation alignment: examples must validate against the current profiles/terminology and render in the IG
  • Negative examples: small failing cases that prove gates work and explain boundaries
  • Narrative wiring: pages link directly to examples so readers can click from text to executable content
  • Regression role: examples become stable test inputs used by CI and cross-product matrices

Key Components

Example bundles

  • Maintain one focused example per main scenario
  • Bundle related resources so context is complete
  • Keep identifiers and references consistent
  • Ensure examples render and validate
  • Use examples to drive review conversations

Negative examples

  • Create examples that intentionally fail key constraints
  • Use them to prove validator gates work
  • Keep negative scope small and focused
  • Label them clearly to avoid accidental reuse
  • Use them to document ‘what not to do’
  • Link examples from narrative guidance
  • Ensure readers can find the executable artifact from the text
  • Keep narrative aligned with actual constraints
  • Update narrative when artifacts change
  • Avoid ‘theory-only’ pages without examples

Behavior

Example-first workflow

Examples lead; profiles follow. Each iteration starts from a concrete instance and then refines constraints only as needed.

Start with an example

  1. Create or update an example that represents the intended workflow.
  2. Run validation and observe what fails (missing data, wrong bindings, unclear requirements).
  3. Decide whether to fix the example (data) or change the rules (constraints/terminology).

Stabilize

  1. Once green, add a small negative example to lock in the boundary.
  2. Link the example from the narrative and conformance statements.
  3. Keep examples small so they remain maintainable as regression assets.

Benefits

  • Regression tests
  • Usable IG

Trade-offs

  • Examples require maintenance