Paths and conditions cheat sheet

A one-page reminder of how FHIR Connect paths and conditions are spelled in Atlas. The guides Write FHIR and openEHR paths and Map only when… (conditions) explain them step by step; the full language is the FHIR Connect specification, and FHIR Connect lists what the engine does beyond it.

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).

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 (FHIR Connect, “Casts in with.fhir”).

Badges on FHIR suggestions: MS (must support), ext (an extension), slice: <name>, binding: required / binding: extensible, <min>..<max> profile (the profile changed the base cardinality). Picking a slice or extension also writes the condition that selects it (see slices).

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 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.

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

<root>.where(<field> = 'a'), or where(<field> in ('a' | 'b')) for several

is none of

not of

one or more values

where((<field> = '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(<field>.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 Map only when… (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

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').

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 <canonical>. Atlas then treats the path as …extension.where(url = '<canonical>'), so the suggestions continue inside that extension.

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.

Direction

unidirectional (under Advanced) takes one of two values: openehr->fhir or fhir->openehr. A mapping without it runs both ways.