| name | composition-builder |
| description | This skill should be used when the user asks to "build a composition", "create a composition", "validate a composition", "convert a composition", or "generate FLAT/STRUCTURED/CANONICAL format". Covers building openEHR compositions in all simplified formats and guiding their validation and format conversion (against a target template; there is no automated validator/converter tool). Also handles quick format explanations and single-payload sketches directly.
|
| argument-hint | <template-id> [format: flat|structured|canonical] |
| allowed-tools | ["Read","Glob","Grep","Write","mcp__openehr-assistant__ckm_template_get","mcp__openehr-assistant__guide_get","mcp__openehr-assistant__type_specification_get","mcp__openehr-assistant__terminology_resolve","mcp__openehr-assistant__examples_search","mcp__openehr-assistant__examples_get"] |
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.
| RM Type | Example Use | Key Fields |
|---|
| DV_TEXT | Free text | value |
| DV_CODED_TEXT | Coded values | value, defining_code (terminology_id + code_string) |
| DV_QUANTITY | Measurements | magnitude, units, optionally precision |
| DV_DATE_TIME | Timestamps | ISO 8601 value |
| DV_ORDINAL | Ordered scales (integer steps) | value (integer), symbol (DV_CODED_TEXT) |
| DV_SCALE | Rating scales with non-integer steps (RM ≥ 1.1.0) | value (real), symbol (DV_CODED_TEXT) |
| DV_BOOLEAN | True/false | value |
| DV_COUNT | Counts | magnitude |
| DV_PROPORTION | Ratios/percentages | numerator, denominator, type |
| DV_DURATION | Time periods | ISO 8601 duration (e.g., P2D, PT4H) |
| DV_IDENTIFIER | External IDs | id, type, issuer, assigner |
| DV_URI | URIs/URLs | value |
| DV_PARSABLE | Structured text | value, formalism |
Step 6: Validation
Before finalizing a composition, verify:
