FHIR Mapping Bidirectional conversion between clinical shorthand and FHIR R4 Timing / Dosage structures.

Frequency → FHIR Timing

How each frequency code maps to Timing.repeat and Timing.code fields.

FHIR EventTiming Codes

How Timing.repeat.when values map to open-pharma-dosing codes.

Worked Example: BD → FHIR Timing

Converting “BD” (twice daily) to a FHIR R4 Timing resource:

timingJSON, _ := dosing.ToFhirTiming("BD")

{
  "repeat": {
    "frequency": 2,
    "period": 1,
    "periodUnit": "d",
    "timeOfDay": ["08:00", "20:00"]
  },
  "code": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-GTSAbbreviation",
        "code": "BID"
      }
    ]
  }
}

The reverse conversion recovers the original code:

fc, _ := dosing.FromFhirTiming(timingJSON)
fmt.Println(fc.Code) // "BD"

FromFhirTiming uses three strategies in order:

1. FHIR code match — if Timing.code.coding contains a recognised GTS code (e.g. BID), return the corresponding frequency immediately.
2. When-based match — if repeat.when is set (e.g. NIGHT, AC), map to the appropriate code.
3. Structure match — match by frequency/period/periodUnit/count/asNeeded combination.

Worked Example: DosingInstruction → FHIR Dosage

Converting a complete dosing instruction to a FHIR R4 Dosage resource:

fc, _ := dosing.Parse("BD")
instruction := &dosing.DosingInstruction{
    Frequency: fc,
    Dose:      &dosing.Dose{Value: 500, Unit: "mg"},
    Route:     "PO",
}
dosageJSON, _ := dosing.ToFhirDosage(instruction)

{
  "timing": {
    "repeat": {
      "frequency": 2,
      "period": 1,
      "periodUnit": "d",
      "timeOfDay": ["08:00", "20:00"]
    },
    "code": {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v3-GTSAbbreviation",
          "code": "BID"
        }
      ]
    }
  },
  "route": {
    "text": "PO"
  },
  "doseAndRate": [
    {
      "doseQuantity": {
        "value": 500,
        "unit": "mg"
      }
    }
  ]
}

The reverse conversion recovers the instruction:

result, _ := dosing.FromFhirDosage(dosageJSON)
fmt.Println(result.Frequency.Code) // "BD"
fmt.Println(result.Dose.Value)     // 500
fmt.Println(result.Dose.Unit)      // "mg"
fmt.Println(result.Route)          // "PO"

Roundtrip Invariant

Three codes have documented structural ambiguities where the roundtrip resolves to an equivalent code. These are structurally indistinguishable in FHIR and resolve to the more common code:

HL7 v3-GTSAbbreviation Coverage

The library supports all medication-relevant codes from the HL7 v3-GTSAbbreviation CodeSystem: