# Paths and conditions cheat sheet A one-page reminder of how FHIR Connect paths and conditions are spelled in Atlas. The guides {doc}`/map/paths` and {doc}`/map/conditions` explain them step by step; the full language is the [FHIR Connect specification](https://sevkohler.github.io/FHIRconnect-spec), and {external+openfhir:doc}`fhirconnect` lists what the engine does beyond it. (cheat-tokens)= ## Path tokens A path starts with a token or, inside a parent mapping (**Followed by**, **Reference**), with a plain relative path that continues from the parent. The suggestions offer the tokens first; the hint is the text Atlas shows next to each one. | Token | Field | Hint in the suggestions | Use it for | |---|---|---|---| | `$resource` | FHIR path | "The resource this model maps" | The resource of the model, e.g. `$resource.component`. | | `$fhirRoot` | FHIR path | "The parent mapping's element" | The element the parent mapping points at. Offered only when there is a parent. | | *(no token)* | FHIR path | | A path relative to the parent mapping's element, e.g. `code.coding.code`. | | `$archetype` | openEHR path | "This model's archetype root" | The root of the model's archetype, e.g. `$archetype/data[at0001]/events[at0006]`. | | `$openehrRoot` | openEHR path | "The parent mapping's node" | The node the parent mapping points at. `$openEHRRoot` is read the same way. | | `$composition` | openEHR path | "The composition root" | Paths from the composition, e.g. `$composition/content[openEHR-EHR-OBSERVATION.height.v2]`. Suggestions below it cover the whole template. | | `$reference` | openEHR path | "Delegate to the referenced resource mapping" | A mapping with a **Reference**: the openEHR side is handled by the referenced resource's mappings, e.g. `openehr: "$reference"` next to `reference: {resourceType: "Observation", …}`. | | *(no token)* | openEHR path | | A path relative to the parent mapping's node. | **Manual** openEHR paths are written under the mapping's own node, so the only token offered there is `$openehrRoot`; FHIR manual paths are relative to the mapping's FHIR element (`code.coding.code`). (cheat-fhir-functions)= ## FHIR path functions and casts | You type | Offered when | What it does | |---|---|---| | `as(Type)` | the element is a choice (`value[x]`, `onset[x]` …) | Narrows the choice to one type ("Narrow the choice element to this type"), e.g. `$resource.abatement.as(DateTime)`. | | `resolve()` | the element is a `Reference` | Follows the reference; the hint lists the target types. | | `where(…)` | after the first segment | Filters, e.g. `where(system = …)`. The cursor lands between the parentheses. | :::{tip} Atlas suggests casts capitalised (`as(String)`, `as(DateTime)`). The engine also accepts the FHIR spelling and other forms ({external+openfhir:doc}`fhirconnect`, "Casts in with.fhir"). ::: Badges on FHIR suggestions: `MS` (must support), `ext` (an extension), `slice: `, `binding: required` / `binding: extensible`, `.. profile` (the profile changed the base cardinality). Picking a slice or extension also writes the condition that selects it (see [slices](#cheat-slices)). (cheat-leaf-attributes)= ## Leaf attribute spelling (openEHR) Below an ELEMENT, the parts of its data value aren't template nodes. The engine reads every spelling of an attribute the same way in every field (the openEHR path, a manual entry, a condition's field), so any of these works: - strict AQL through the element's `value`: `…/value/magnitude`, `…/value/defining_code/code_string` - the same without `value/`: `…/magnitude`, `…/defining_code/code_string`. A bare `value` is the element's whole data value; the attribute `value` is written `value/value` - an alias (the "Also" column) - the flat pipe: `…/|unit` or `…/items[at0004]|unit` - on a node that is a data value itself, the attribute directly: `…/null_flavour/value`, `ism_transition/current_state/defining_code/code_string` Atlas suggests one spelling per field: strict AQL (`value/magnitude`) in the openEHR path, the RM name (`magnitude`, `value/value` for a `value`) in manual entries and condition fields. The "flat" column is what the engine turns the attribute into in the flat format. | Data value | Attribute | Also | Flat | Meaning | |---|---|---|---|---| | DV_CODED_TEXT | `defining_code/code_string` | `defining_code`, `code_string` | `\|code` | code | | | `defining_code/terminology_id` | `terminology_id` | `\|terminology` | terminology | | | `value` | | `\|value` | display text | | | `formatting` | | `\|formatting` | formatting | | DV_TEXT | `value` | | *(the element)* | text | | | `formatting` | | `\|formatting` | formatting | | | the DV_CODED_TEXT attributes | | | a text element may hold a coded text | | DV_QUANTITY | `magnitude` | | `\|magnitude` | magnitude | | | `units` | | `\|unit` | units | | | `precision`, `units_system`, `units_display_name` | | `\|precision`, `\|units_system`, `\|units_display_name` | | | DV_COUNT | `magnitude` | | *(the element)* | count | | DV_PROPORTION | `numerator`, `denominator`, `type`, `precision` | | `\|numerator`, `\|denominator`, `\|type`, `\|precision` | numerator, denominator, proportion kind, precision | | DV_ORDINAL | `value` | `ordinal` | `\|ordinal` | ordinal value | | | `symbol/value` | | `\|value` | symbol text | | | `symbol/defining_code/code_string` | | `\|code` | symbol code | | DV_IDENTIFIER | `id`, `type`, `issuer`, `assigner` | | `\|id`, `\|type`, `\|issuer`, `\|assigner` | id, identifier type, issuer, assigner | | DV_PARSABLE | `value`, `formalism` | | `\|value`, `\|formalism` | value, formalism | | DV_MULTIMEDIA | `uri/value` | `uri` | `\|url` | URI | | | `media_type/code_string` | `media_type` | `\|mediatype` | media type | | | `size` | | `\|size` | size | | | `alternate_text` | | `\|alternatetext` | alternate text | | DV_BOOLEAN, DV_DATE_TIME, DV_DATE, DV_TIME, DV_DURATION, DV_URI, DV_EHR_URI | `value` | | *(the element)* | the value | An attribute through the element's `value` that none of the element's types has (`…/value/magnitude` on a coded text) is a path that doesn't exist: the engine skips the mapping and Atlas reports {ref}`openehr-not-in-template `. :::{note} An element that may hold several data value types (a choice element) shows each attribute once, with "also : set with.type to pick" in its hint. The engine takes the first type that has the attribute unless the mapping's `with.type` names another. ::: (cheat-operators)= ## Condition operators A condition (**FHIR condition** / **openEHR condition** under **Only when**) has a **Where** (`targetRoot`), a field (`targetAttributes`), an operator and criteria (`criterias`). | In Atlas | In the YAML | Criteria | Equivalent FHIRPath shown under the condition | |---|---|---|---| | is one of | `one of` | one or more values | `.where( = 'a')`, or `where( in ('a' \| 'b'))` for several | | is none of | `not of` | one or more values | `where(( = 'a').not())` | | is of type | `type` | one or more type names (suggested from what the field can hold, e.g. `Observation`, `DV_CODED_TEXT`) | `where(.toString().contains('Observation'))` | | is empty | `empty` | none | "mapping only applies when is empty" | | has a value | `not empty` | none | "mapping only applies when has a value" | How to read them: - **Comma means "any may match".** Several fields or several criteria are OR-ed: the condition holds when any field equals any criterion. **is none of** negates the whole match. - **Filter or gate.** **is one of**, **is none of** and **is of type** pick elements: the `.where(…)` sits where the **Where** path leaves the mapping's own path. **is empty** and **has a value** never pick; they decide whether the whole mapping applies. - **"keeps k of n … in the example"** under a FHIR condition counts the elements it keeps in the current example; "— check the criteria" appears when it keeps none. - **"The target root isn't on this mapping's path, so the condition tests the whole resource rather than picking elements."** The **Where** doesn't share a start with the mapping's FHIR path; see {doc}`/map/conditions`. - Changing the operator to **is empty** or **has a value** removes the criteria. Example from the Blood Pressure demo: the mapping `diastolic` maps `$resource.component` with ```yaml fhirCondition: targetRoot: "$resource.component" targetAttributes: ["code.coding.code"] operator: "one of" criterias: ["8462-4"] ``` which Atlas shows as `…component.where(code.coding.code = '8462-4')`. (cheat-slices)= ## Slices and extensions FHIR Connect addresses a slice or an extension as the element plus an **is one of** condition on `url`, `system` or `code` with a single value. Picking a `slice:` or `ext` suggestion writes it for you, for example `extension` with `url one of `. Atlas then treats the path as `…extension.where(url = '')`, so the suggestions continue inside that extension. (cheat-legacy)= ## Legacy singular forms Older model files spell the lists in the singular. Both are read; Atlas writes the plural. | Legacy (singular) | Current (plural) | Note | |---|---|---| | `targetAttribute: "code.coding.code"` | `targetAttributes: ["code.coding.code"]` | Used only when the plural is absent. | | `criteria: "8462-4"` | `criterias: ["8462-4"]` | Used only when the plural is absent. The engine doesn't split a singular `criteria` on commas: `"a, b"` is one criterion. | | `criteria: "[$loinc.8462-4, …]"` | `criterias: ["8462-4"]` | A bracketed legacy list counts as its first code, without the `$loinc.` / `$snomed.` prefix. | As soon as you edit the field or criteria of a condition in Atlas, it writes the plural key and drops the singular one. (cheat-direction)= ## Direction `unidirectional` (under **Advanced**) takes one of two values: `openehr->fhir` or `fhir->openehr`. A mapping without it runs both ways. ## Related - {doc}`/map/paths` - {doc}`/map/conditions` - {doc}`/map/fixed-values` - {doc}`/reference/glossary`