Clarotech.OpenEHR.RM.Flat 1.0.0

Clarotech.OpenEHR.RM.Flat

openEHR "FLAT" (web template) JSON encoding and decoding for the openEHR Reference Model, built on System.Text.Json.

FLAT JSON is the flattened path/value format popularised by Marand/Better and reimplemented by EHRbase's openEHR_SDK — the de facto interop target most openEHR tooling expects. Instead of nested canonical JSON, a composition is represented as a flat map of "path|suffix": value pairs, e.g.:

{
  "vaccination_management/vaccine_code|code": "38598009",
  "vaccination_management/vaccine_code|terminology": "SNOMED-CT",
  "vaccination_management/vaccine_code|value": "Diphtheria vaccine",
  "vaccination_management/medication_details/expiration_date": "2026-01-01T00:00:00Z"
}

This package does not parse OPT templates or generate flat paths from an archetype — it provides the low-level building blocks (FlatPath, FlatValueCodec, FlatJsonSerializer) that a code generator or hand-written mapping layer uses to read and write these paths against openEHR RM data values.

Contents

• Installation
• API overview
• FlatPath — id and path construction
• FlatValueCodec — per-type suffix keys
• FlatJsonSerializer
• Worked example
• Supported RM types
• Dependencies
• License

Installation

dotnet add package Clarotech.OpenEHR.RM.Flat

Targets net8.0 and net10.0.

API overview

using Clarotech.OpenEHR.RM.Flat;

FlatPath — id and path construction

FlatPath.BuildId("Serum sodium");        // "serum_sodium"
FlatPath.BuildId("2nd vaccination");      // "a2nd_vaccination"  (digit-prefixed ids get an 'a' prefix)

FlatPath.Segment("participation");        // "participation"       (no index)
FlatPath.Segment("participation", 0);     // "participation:0"

FlatPath.Join("vaccination_management", "vaccine_code"); // "vaccination_management/vaccine_code"
FlatPath.Join("", "vaccine_code");                        // "vaccine_code"  (empty segments are skipped)

BuildId follows the same id-derivation algorithm as EHRbase's OPTParser.buildId: strip non-alphanumeric characters to spaces, collapse whitespace to _, lowercase, and prefix with a if the result starts with a digit. Sibling disambiguation (appending 2, 3, ... to a repeated base id) is the caller's responsibility, since it depends on the caller's own notion of "siblings" (e.g. a code generator's property list for one class) — this package only slugifies a single term at a time.

FlatValueCodec — per-type suffix keys

Each RM leaf data type has a fixed, hardcoded set of flat-key suffixes, matching the suffix rules found in EHRbase's openEHR_SDK (serialisation/flatencoding/std/marshal/config/*.java):

Write is a no-op when passed a null value. Read* returns null when none of a type's relevant keys are present under the given path; otherwise it returns a partially-populated instance using whichever subset of keys exist (missing individual keys are simply left unset — never an error).

var map = new Dictionary<string, object?>();
FlatValueCodec.Write(map, "vaccine_code", new DvCodedText(
    "Diphtheria vaccine",
    new CodePhrase(new TerminologyId("SNOMED-CT"), "38598009")));
// map["vaccine_code|code"]        == "38598009"
// map["vaccine_code|terminology"] == "SNOMED-CT"
// map["vaccine_code|value"]       == "Diphtheria vaccine"

DvCodedText? restored = FlatValueCodec.ReadDvCodedText(map, "vaccine_code");

FlatJsonSerializer

string json = FlatJsonSerializer.Serialize(map, indented: true);
Dictionary<string, object?> restored = FlatJsonSerializer.Deserialize(json);

Backed by System.Text.Json. Deserialize uses an inferred-type object converter so values come back as real bool/double/long/string, not raw JsonElement.

Worked example

using Clarotech.OpenEHR.RM.Flat;
using OpenEHR.RM.DataTypes.Text;
using OpenEHR.RM.DataTypes.DateTime;

var map = new Dictionary<string, object?>();

FlatValueCodec.Write(map, FlatPath.Join("vaccination_management", "vaccine_code"),
    new DvCodedText("Diphtheria vaccine", new CodePhrase(new TerminologyId("SNOMED-CT"), "38598009")));

FlatValueCodec.Write(map, FlatPath.Join("vaccination_management", "medication_details", "expiration_date"),
    new DvDateTime("2026-01-01T00:00:00Z"));

string json = FlatJsonSerializer.Serialize(map, indented: true);

Supported RM types

DvText, DvCodedText, DvOrdinal, DvQuantity, DvCount, DvBoolean, DvProportion, DvIdentifier, DvDateTime, DvDate, DvTime, DvDuration, DvUri, DvEhrUri, DvParsable, DvMultimedia.

Dependencies

• Clarotech.OpenEHR.RM — openEHR Reference Model classes

License

Apache-2.0 — see LICENSE.txt