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:
[]
= "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'sextensionlives 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 andresolve()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 anArc. - The rules the specification leaves open are refusals, not guesses.
Extensions apply in declaration order and, within one file, in file order; an
addwhose name collides, anappendcarrying mapping logic, anoverwriteof 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.versionandtemplate.sem_verare 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.
getreads an openEHR reference-model value into its FHIR element andputwrites 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_TEXTagainstCodeableConceptand againstCoding,CODE_PHRASEagainstCoding,TERM_MAPPINGagainstCoding,DV_TEXTagainststring,CodingandCodeableConcept,DV_DATE_TIMEagainstdateTimeand the one-way collapse of aPeriod,DV_INTERVAL<DV_DATE_TIME>againstPeriod,PARTY_IDENTIFIEDagainstReferencewithDV_IDENTIFIERagainstIdentifierbeside it,DV_PROPORTIONagainstQuantityfor a percentage,DV_QUANTITYagainstQuantity,decimalandinteger,DV_COUNTagainstinteger,QuantityandCount,DV_TIMEagainsttime,DV_DURATIONagainstDurationthrough the UCUM to ISO 8601 bridge,DV_URIagainsturl,DV_MULTIMEDIAandDV_PARSABLEagainstAttachment, an openEHRStringattribute againstCoding,IdentifierandReference, a scalarIntegerorRealattribute againstintegeranddecimal,DV_INTERVAL<DV_QUANTITY>againstRange, andELEMENT.null_flavouragainst the code of thedata-absent-reasonextension. - A date and time value keeps the text it came with. Both sides hold a
lexical string, so
Z,+00:00,+01:00and fractional seconds survive; the engine parses no timestamp and adds no offset. - An attribute with no counterpart is carried, a falsified value refuses.
putrestores the attributes the data-type table marks-from the openEHR value the target holds. ATERM_MAPPINGwhosematchis not=would assert an equivalence the data denies, so it writes noCoding: 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_PROPORTIONthat is not a percentage refuses. FHIRQuantitycarries 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
unidirectionalskip, a defaulted composition field, the occurrences a0..ninto a0..1dropped, a one-way data-type row, and a reference left for the facade to resolve. Anything else refuses the unit. EachWarningpairs itsLosswith aLocation: the FHIRPath of the FHIR element, in the simple subsetOperationOutcome.issue.expressionadmits, and the archetype path of the openEHR node, never a value.run::to_fhir_with_warningsandrun::to_openehr_with_warningsanswer the typed losses beside the operation's answer, and eachOperationOutcomeissue carries the FHIRPath as itsexpressionand the openEHR path as adetails.coding. - An occurrence is a structured index. One entry per repeating element on
the way to the target, so a
0..1output is overwritten, a0..noutput 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_openehrreads a FHIR resource and builds a composition through the Simplified Formats seam;to_fhirreads 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 thefollowedBychildren once per occurrence the parent bound. Amanualentry merges every path it names into one element, aslotArchetyperecurses with the whole chain checked for a cycle, aslotContextenters a sub-context and maps from itsstartwith that context's own extensions into the parent composition, andtype: NONEwrites nothing and only anchors what follows. A resource aslotContextpulls in through areferenceis named inOutcome::consumed, so a caller splitting a Bundle does not process it again as a root. - A mapping with no
typekey 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 astype: NONEdoes, 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
followedBychild whose openEHR node the template constrains to1..1and whose input carries nothing isEngineError::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.
contractcarriesToFhirRequest/ToFhirResponseandToOpenehrRequest/ToOpenehrResponsewithfrom_parametersandto_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 notemplateIdare each a typed refusal with the R4 issue code it renders as. - A composition travels in either serialization.
CompositionPayloadreads canonical or FLAT, takes the template fromarchetype_details.template_idwhere the payload carries one, and refuses a disagreement between the payload and thetemplateIda caller pinned. - Strictness is the default. A run that cannot be performed answers an
OperationOutcomeand no Bundle and no composition; a run that succeeded reports the engine's declared losses asinformationandwarningissues beside the result. - Every
$tofhirBundle carries oneProvenance.targetcovers every mapped resource,recordedis the run time the caller passed,agent.whoiscontext.whoor the caller's ownDevicereference, and oneentitywithrole = derivationnames the composition. context.patientis 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
Devicereference arrive inrun::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.