composition-builder

Composition Builder

Validation and format conversion here are guided / manual — the workflow walks through them against the target template; there is no MCP validate-or-convert tool. The loaded simplified_formats/* guides are authoritative over any inline summary.

Step 1: Load Guides (MANDATORY)

Before building any composition, load the authoritative guides:

guide_get("openehr://guides/simplified_formats/principles")
guide_get("openehr://guides/simplified_formats/rules")
guide_get("openehr://guides/simplified_formats/idioms-cheatsheet")

Consult worked examples (when applicable)

For sample payloads on common concepts (e.g. blood pressure / vital signs, encounter with RM attributes, coded-text handling, raw-escape patterns), consult examples_search(kind="flat") or examples_search(kind="structured") before hand-crafting. Curated samples live under openehr://examples/{flat|structured}/{name} with pattern and related-guide metadata. Skip this step for novel or highly template-specific payloads.

Step 2: Retrieve Template

Load the target template to understand the structure:

ckm_template_get("<template-id>")

Important: Simplified format field identifiers are ONLY valid for the specific target OPT. Always state the target template and validate paths against it. A field identifier valid for one template may be invalid or mean something different in another.

This reveals the archetype structure, constraints, and required fields.

Step 3: Choose Format

FLAT Format

Pipe-delimited paths with value suffixes. Best for simple integrations and form submissions.

{
  "ctx/language": "en",
  "ctx/territory": "NL",
  "ctx/composer_name": "Dr. Smith",
  "vitals/body_temperature/any_event/temperature|magnitude": 37.2,
  "vitals/body_temperature/any_event/temperature|unit": "Cel"
}

Key suffixes: |magnitude, |unit (DV_QUANTITY); |code, |value, |terminology (DV_CODED_TEXT — |value/|terminology required only for external terminologies); |code, |value, |ordinal (DV_ORDINAL); |numerator, |denominator, |type (DV_PROPORTION — |type is a PROPORTION_KIND integer; magnitude is output-only); |other (free-text branch of an open value set, listOpen: true — mutually exclusive with |code/|value/|terminology); |name; |raw (embed canonical RM JSON with _type)