fhirconnect 0.3.0

The FHIRconnect mapping language for Rust: the mapping file model and its validation, context resolution into an immutable program, and the bidirectional interpreter between openEHR compositions and FHIR resources
Documentation

fhirconnect

The FHIRconnect mapping language for Rust: the mapping file model and its validation, context resolution into an immutable program, and the bidirectional interpreter between openEHR compositions and FHIR resources.

Part of FerroBRIDGE, a pure-Rust bridge between openEHR and two interoperability targets: HL7 FHIR through the FHIRconnect specification, and the OMOP Common Data Model through the OMOCL specification.

The crate is on FerroBRIDGE's crate line, the version line fhir-types carries, and builds on the openehr-* 0.0.86 crates. Take the same openehr-* release in your own manifest: Cargo treats every 0.0.x release as incompatible with the next, so a different one gives you a second copy of the openEHR types this crate takes and returns. The design is recorded in the repository's architecture document.

Features

mapping, on by default, is the language: the model, resolve, engine and operations modules and their openEHR dependencies. With default-features = false the crate is the tree module alone, the FHIR path model over fhir-types, which a FHIR writer can take with no openEHR crate.

Requiring the crate

The crate follows Cargo's SemVer rules: a compatible change moves the patch, and a breaking change moves the minor while the crate is 0.x. Require it with a caret range on its line, so one release serves every crate in your build that uses it:

[dependencies]
fhirconnect = "0.3"

Name a patch ("0.3.N") when you need the first release that carries what you use; the range is the same caret range.

The model module

fhirconnect::model is the mapping file model and the three layers that validate it. ast carries one positioned Rust type per construct a model, extension or context file may hold; parse lowers the positioned YAML tree the shared loader in openehr-mapping-core produces, refusing an unknown key, a node of the wrong kind and a keyword value outside its documented set (keyword values compare case-insensitively, YAML keys are exact); schema validates the same document against the two schemas FHIRconnect publishes and against the stricter pair this crate ships under schemas/; semantic checks what a schema cannot express, such as a targetRoot that is not a child of its with path or a cross-file reference that names no loaded mapping; load runs all of it over one file or a whole set and returns every diagnostic rather than the first. The vendored mapping library is exercised by tests that pin the exact set the published schemas refuse, so an upstream schema fix fails a test here.

The tree module

fhirconnect::tree is the bidirectional path model behind with.fhir. A mapping runs both ways through one expression, and two of the forms FHIRconnect writes are not FHIRPath at all ($fhirRoot and the ^ parent operator), so the module parses the expression itself, resolves it against the element table fhir-types emits per FHIR version, and evaluates it over that crate's lexical Value tree.

  • The element table is the authority. Navigation is by element name, a choice element resolves through ofType(), as() or the suffixed name, a repeating element is an array indexed by a structured occurrence, and a primitive's extension lives in the sibling member named with a leading underscore (FHIR R4 JSON).
  • Every expression is classified when it is parsed. where(), first(), last(), an index filter and resolve() select among the values a document already holds, so an expression carrying one is read-only and a write through it is refused with the offending step named.
  • resolve() fetches nothing. It returns a deferred outcome carrying the reference and the steps still to apply, which the engine finishes.
  • A write is all or nothing. It applies to a copy and replaces the document only when every step succeeded.

The resolve module

fhirconnect::resolve compiles one context mapping into one immutable program, once, at load. It picks the start model mapping, applies the extensions the context declares, checks the four version selectors, and pre-resolves every path on both sides: the FHIR side against the element table with its writability, the openEHR side to a node of the Web Template with the repeating nodes above it as structured occurrence axes. The interpreter runs that program per request and parses no path.

  • The program never changes after it is built. Its fields are private, no method takes &mut self, and it travels behind an Arc.
  • The rules the specification leaves open are refusals, not guesses. Extensions apply in declaration order and, within one file, in file order; an add whose name collides, an append carrying mapping logic, an overwrite of a missing method and two extensions overwriting one name each refuse with both mappings named.
  • A version disagreement is a refusal and a missing selector is recorded. metadata.version, openEhrConfig.revision, profile.version and template.sem_ver are each checked against what the files and the template carry, and an optional selector nothing pins reads as unpinned.
  • A program is selected by identity. The FHIR side matches the profile set an instance claims in meta.profile, the openEHR side the template a composition names, and an ambiguous selection with nothing pinning it refuses by naming the candidates.

The engine module

fhirconnect::engine interprets a compiled program, and there is one traversal for both directions. The direction enters it in three places only: a condition is evaluated on the input side, a mapping whose unidirectional names the other direction is skipped, and the composition defaults apply going into openEHR.

  • A data-type cell is written once as a lens. get reads an openEHR reference-model value into its FHIR element and put writes it back with the openEHR value the target already holds, and the pair is tested against the GetPut and PutGet laws as properties. The cells the FHIR round trip needs are in: DV_CODED_TEXT against CodeableConcept and against Coding, CODE_PHRASE against Coding, TERM_MAPPING against Coding, DV_TEXT against string, Coding and CodeableConcept, DV_DATE_TIME against dateTime and the one-way collapse of a Period, DV_INTERVAL<DV_DATE_TIME> against Period, PARTY_IDENTIFIED against Reference with DV_IDENTIFIER against Identifier beside it, DV_PROPORTION against Quantity for a percentage, DV_QUANTITY against Quantity, decimal and integer, DV_COUNT against integer, Quantity and Count, DV_TIME against time, DV_DURATION against Duration through the UCUM to ISO 8601 bridge, DV_URI against url, DV_MULTIMEDIA and DV_PARSABLE against Attachment, an openEHR String attribute against Coding, Identifier and Reference, a scalar Integer or Real attribute against integer and decimal, DV_INTERVAL<DV_QUANTITY> against Range, and ELEMENT.null_flavour against the code of the data-absent-reason extension.
  • A date and time value keeps the text it came with. Both sides hold a lexical string, so Z, +00:00, +01:00 and fractional seconds survive; the engine parses no timestamp and adds no offset.
  • An attribute with no counterpart is carried, a falsified value refuses. put restores the attributes the data-type table marks - from the openEHR value the target holds. A TERM_MAPPING whose match is not = would assert an equivalence the data denies, so it writes no Coding: the run declares it as a skipped loss naming the match code and the target term, and the rest of the value converts.
  • A DV_PROPORTION that is not a percentage refuses. FHIR Quantity carries no denominator, and the engine writes no extension URL of its own for one.
  • A loss is a typed outcome, never a log line. The declared set is a unidirectional skip, a defaulted composition field, the occurrences a 0..n into a 0..1 dropped, a one-way data-type row, and a reference left for the facade to resolve. Anything else refuses the unit. Each Warning pairs its Loss with a Location: the FHIRPath of the FHIR element, in the simple subset OperationOutcome.issue.expression admits, and the archetype path of the openEHR node, never a value. run::to_fhir_with_warnings and run::to_openehr_with_warnings answer the typed losses beside the operation's answer, and each OperationOutcome issue carries the FHIRPath as its expression and the openEHR path as a details.coding.
  • An occurrence is a structured index. One entry per repeating element on the way to the target, so a 0..1 output is overwritten, a 0..n output is appended to, and a child mapping writes under the occurrence its parent is bound to.
  • One walk runs the program, from either side. to_openehr reads a FHIR resource and builds a composition through the Simplified Formats seam; to_fhir reads a composition and writes the resource the context names. Both run the same mapping list top-down: the input-side conditions, the input occurrences, the data-type cell, the write, then the followedBy children once per occurrence the parent bound. A manual entry merges every path it names into one element, a slotArchetype recurses with the whole chain checked for a cycle, a slotContext enters a sub-context and maps from its start with that context's own extensions into the parent composition, and type: NONE writes nothing and only anchors what follows. A resource a slotContext pulls in through a reference is named in Outcome::consumed, so a caller splitting a Bundle does not process it again as a root.
  • A mapping with no type key converts through a derived pair. The compiler derives it from the element's FHIR type and the node's openEHR class, the pairs of the data-type chapter the engine's cells carry. An untyped mapping onto a structural node anchors its children as type: NONE does, and a choice element is read as the alternative the document carries and written as the first pair of the node's class.
  • A missing required child refuses. A followedBy child whose openEHR node the template constrains to 1..1 and whose input carries nothing is EngineError::MissingRequired, naming the node. A structural node counts as provided once a value below it is written, and a child its own condition closed is skipped.
  • The composition defaults apply going into openEHR only. The composer, the context start time and the context setting carry the values the specification's own defaults chapter suggests, and the language and territory are the caller's, because the chapter assigns them to the project. Each one the engine fills is a recorded loss.

The operations module

operations is the two FHIRconnect operations, $tofhir and $toopenehr, over the generated FHIR model. The governing text is the REST API chapter of the FHIRconnect specification (engine/rest-api.adoc and the FSH operation definitions under rest/), vendored at the pinned specification commit, read together with the FHIR R4 operations framework.

  • The contracts follow the framework. contract carries ToFhirRequest/ToFhirResponse and ToOpenehrRequest/ToOpenehrResponse with from_parameters and to_parameters, and the chapter's own worked examples round trip through them. Reading is strict: a parameter the operation does not declare, one given twice, one carrying the wrong value type and a FLAT composition with no templateId are each a typed refusal with the R4 issue code it renders as.
  • A composition travels in either serialization. CompositionPayload reads canonical or FLAT, takes the template from archetype_details.template_id where the payload carries one, and refuses a disagreement between the payload and the templateId a caller pinned.
  • Strictness is the default. A run that cannot be performed answers an OperationOutcome and no Bundle and no composition; a run that succeeded reports the engine's declared losses as information and warning issues beside the result.
  • Every $tofhir Bundle carries one Provenance. target covers every mapped resource, recorded is the run time the caller passed, agent.who is context.who or the caller's own Device reference, and one entity with role = derivation names the composition.
  • context.patient is a fallback, never a requirement. When it is supplied, it overwrites the subject the mapping resolved, at the element the FHIR element table names. A Bundle that references more than one subject is refused naming them, because one Bundle maps to one composition.
  • The crate reads no clock and opens no socket. The run timestamp and the Device reference arrive in run::Settings.

Licence

Business Source License 1.1 (LICENSE): free for every non-production use and for non-commercial production use; a commercial licence for other production use; Apache License 2.0 four years after each version.