Inera Core Implementation Guide - Local Development build (v0.2.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Mapping Strategy

Mapping Strategy: TKB to FHIR

Overview

This page describes the overall strategy for mapping Swedish RIVTA/TKB (Tjänstekontrakt) services to FHIR REST APIs. The mapping addresses both structural transformation (document-oriented to resource-oriented) and semantic alignment (Swedish healthcare concepts to FHIR information model).

Architectural Context

TKB services use a header/body pattern with SOAP/XML, while FHIR uses RESTful resources with distributed metadata. For architectural transition strategies and coexistence patterns, see the Migration Guide.

This page focuses on technical mapping details for transforming TKB data structures to FHIR resources.

Mapping Layers

The transformation occurs across four distinct layers:

1. Protocol Layer

Example Transformation:

<!-- TKB Request -->
<GetDiagnosisRequest>
  <patientId>191212121212</patientId>
  <timePeriod>
    <start>2024-01-01</start>
    <end>2024-12-31</end>
  </timePeriod>
</GetDiagnosisRequest>

// FHIR Request
GET /Condition?patient.identifier=https://terminology.hl7.se/sid/se-personnummer|191212121212
    &onset-date=ge2024-01-01
    &onset-date=le2024-12-31
    &_revinclude=Provenance:target

2. Information Structure Layer

TKB uses a header/body pattern with centralized metadata. FHIR distributes metadata across resources.

ConceptMap Approach:

Each TKB service is documented with a detailed ConceptMap:

Instance: ConceptMapGetDiagnosisTKBToCondition
InstanceOf: ConceptMap
* group[0].element[0].code = #GetDiagnosisResponse.patientId
* group[0].element[0].target[0].code = #subject
* group[0].element[0].target[0].equivalence = #equivalent
* group[0].element[0].target[0].comment = "Reference to Patient resource"

3. Semantic Layer

Swedish healthcare concepts are mapped to FHIR terminology bindings:

OID to URI Transformation:

Many TKB services use OID-based code system identifiers. These must be converted to URIs:

OID_TO_URI_MAP = {
    "1.2.752.116.1.1.1": "http://terminology.hl7.se/CodeSystem/icd-10-se",
    "2.16.840.1.113883.6.1": "http://loinc.org",
    "2.16.840.1.113883.6.96": "http://snomed.info/sct",
    "1.2.752.129.2.2.3.1.1": "http://www.whocc.no/atc",
}

4. Business Logic Layer

TKB service behaviors map to FHIR interaction patterns:

Example: GetDiagnosis → Condition Search

TKB: GetDiagnosis(patientId, timePeriod, careUnitHSAId)
       ↓
FHIR: GET /Condition?patient={ref}
                    &onset-date=ge{start}
                    &onset-date=le{end}
                    &recorder.identifier={hsaid}
                    &_revinclude=Provenance:target

Metadata Separation Strategy

A key design decision is how to handle TKB header metadata. We use a dual-track approach:

Track 1: Resource Metadata (Minimal)

For basic use cases, essential metadata is embedded in the resource:

{
  "resourceType": "Condition",
  "meta": {
    "lastUpdated": "2025-11-24T10:00:00+01:00",
    "source": "https://hsaid.se/SE2321000016-SYS001",
    "profile": ["https://inera.se/fhir/core/StructureDefinition/ConditionDiagnosisInera"]
  },
  "recorder": {
    "identifier": {
      "system": "https://hsaid.se",
      "value": "SE2321000016-123456"
    }
  }
}

Track 2: Provenance (Complete)

For full TKB header fidelity, create a linked Provenance resource:

{
  "resourceType": "Provenance",
  "target": [{"reference": "Condition/123"}],
  "recorded": "2025-11-24T10:00:00+01:00",
  "agent": [{
    "type": {"coding": [{"code": "author"}]},
    "who": {"identifier": {"value": "SE2321000016-123456"}},
    "onBehalfOf": {"identifier": {"value": "SE2321000016-A001"}}
  }],
  "entity": [{
    "role": "source",
    "what": {"identifier": {"value": "SE2321000016-0000"}}
  }]
}

When to use each track:

See TKB Header Mapping for detailed guidance.

Search Parameter Mapping

TKB service inputs (request parameters) map to FHIR search parameters:

Example: GetMedicationHistory

Composite Search:

GET /MedicationStatement?patient.identifier=https://terminology.hl7.se/sid/se-personnummer|191212121212
                        &effective-date=ge2024-01-01
                        &effective-date=le2024-12-31
                        &status=active
                        &_include=MedicationStatement:medication
                        &_revinclude=Provenance:target

Temporal Mapping Patterns

TKB uses various temporal concepts that map to different FHIR elements:

Example Transformation:

<!-- TKB -->
<diagnosis>
  <diagnosisTime>2024-11-15</diagnosisTime>
  <registeredTime>2024-11-15T14:30:00</registeredTime>
</diagnosis>

// FHIR
{
  "resourceType": "Condition",
  "onsetDateTime": "2024-11-15",
  "recordedDate": "2024-11-15",
  "meta": {
    "lastUpdated": "2024-11-15T14:30:00+01:00"
  }
}

Status Mapping Patterns

Many TKB services include status fields that map to FHIR status elements:

Condition.clinicalStatus

Observation.status

Reference Patterns

TKB uses identifiers (HSA-ID, care contact ID, etc.) that become FHIR references:

Internal References (within system)

{
  "subject": {
    "reference": "Patient/191212121212",
    "type": "Patient"
  }
}

External References (cross-system)

{
  "recorder": {
    "identifier": {
      "system": "https://hsaid.se",
      "value": "SE2321000016-123456"
    },
    "display": "Dr. Anna Andersson"
  }
}

Contained Resources (for tight coupling)

{
  "resourceType": "MedicationStatement",
  "contained": [{
    "resourceType": "Medication",
    "id": "med1",
    "code": {
      "coding": [{
        "system": "https://inera.se/fhir/core/CodeSystem/npl",
        "code": "123456"
      }]
    }
  }],
  "medicationReference": {
    "reference": "#med1"
  }
}

Validation and Conformance

Must Support Elements

Elements marked as mustSupport in profiles must be:

• Populated by servers if data exists
• Handled by clients if present

Terminology Validation

All coded elements should validate against specified ValueSets:

* code from ICD10SEDiagnosisCodes (preferred)
* severity from ConditionSeverity (required)

Search Capability

Servers should declare support via CapabilityStatement:

{
  "resourceType": "CapabilityStatement",
  "rest": [{
    "mode": "server",
    "resource": [{
      "type": "Condition",
      "profile": "https://inera.se/fhir/core/StructureDefinition/ConditionDiagnosisInera",
      "searchParam": [
        {"name": "patient", "type": "reference"},
        {"name": "onset-date", "type": "date"},
        {"name": "code", "type": "token"}
      ]
    }]
  }]
}

Migration Strategies

For architectural transition patterns (Façade, Dual-Native, Mirror, FHIR-Native) and system-specific recommendations, see the Migration Guide.

Summary

The TKB to FHIR mapping strategy emphasizes:

1. Preservation of Semantics: ConceptMaps document exact mappings
2. Distributed Metadata: Header data spreads across Resource + Provenance
3. Swedish Context: Terminology, identifiers, and organizational patterns
4. Incremental Adoption: Progressive conformance levels
5. Interoperability: Standards-based REST APIs

For specific service mappings, see the ConceptMaps section.