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("simplified_formats/principles")
guide_get("simplified_formats/rules")
guide_get("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, |code, |value, |terminology, |name

STRUCTURED Format

Nested JSON mirroring the archetype hierarchy. Best for complex UIs and programmatic construction.

{
  "ctx": { "language": "en", "territory": "NL" },
  "vitals": {
    "body_temperature": [{
      "any_event": [{
        "temperature": [{ "|magnitude": 37.2, "|unit": "Cel" }]
      }]
    }]
  }
}

CANONICAL Format

Full Reference Model representation with _type annotations. Best for archival and CDR interactions.

{
  "_type": "COMPOSITION",
  "archetype_details": { ... },
  "content": [{
    "_type": "OBSERVATION",
    "data": { ... }
  }]
}

Step 4: Composition Metadata

Every composition requires context fields (ctx/ in FLAT, ctx object in STRUCTURED):

• composer (ctx/composer_name): Who created the data (name, optionally ID)
• language (ctx/language): ISO 639-1 code (e.g., en, nl)
• territory (ctx/territory): ISO 3166-1 code (e.g., NL, US)
• category: event (point-in-time) or persistent (ongoing)
• context: start_time (ctx/time) and setting (e.g., primary medical care, secondary medical care)
• id_namespace (ctx/id_namespace): Optional, for identification context
• id_scheme (ctx/id_scheme): Optional, for identification scheme

Step 5: RM Data Types

Use type_specification_get for detailed type structure when needed.

Step 6: Validation

Before finalizing a composition, verify:

• [ ] All required fields are present (check template constraints)
• [ ] Cardinality constraints are met (min/max occurrences)
• [ ] _type annotations are correct (CANONICAL format)
• [ ] Terminology codes are valid (use terminology_resolve if needed)
• [ ] Date/time values are valid ISO 8601
• [ ] Quantity units match archetype constraints
• [ ] Composition metadata is complete (composer, language, territory, category)