FHIR Basics
To follow along, use a sample FHIR bundle in an Ovok project. For import instructions, refer to the Import Sample Data guide.
Why FHIR?
Ovok stores healthcare data using FHIR, a standard for representing and exchanging clinical information. Using FHIR can help your team:
- Interoperate with partners. Hospitals, practices, laboratories, and other healthcare partners increasingly expose FHIR APIs. Using shared resource formats makes it easier to connect systems.
- Adapt as your product grows. Healthcare workflows and partner requirements vary. FHIR models common clinical concepts so teams can extend integrations without replacing a proprietary data model each time.
FHIR is powerful and can take time to learn. This page introduces the concepts you will encounter when working with FHIR data in Ovok. For the complete specification, see the official FHIR R4 documentation.
Storing data: resources
A core data object in FHIR is called a Resource. You can think of a resource as a typed object in an application. FHIR defines resources for healthcare concepts such as Patient, Medication, Device, Observation, Procedure, CarePlan, and Encounter.
Each field in a resource is an Element. Elements use primitive types such as string, decimal, and date, or complex types such as HumanName and Address. Most resources also have an id: a server-assigned identifier that is unique within that server. Browse all types in FHIR Elements or all resources in FHIR resources.
Example Patient
The example below shows a fictional Patient resource with name, telecom, and address elements. It contains no real patient information.
Show the Patient resource
{
"resourceType": "Patient",
"id": "patient-berlin-001",
"name": [
{
"use": "official",
"family": "Mustermann",
"given": ["Johann"]
}
],
"telecom": [
{
"system": "phone",
"value": "+49 30 0000 0000",
"use": "mobile"
}
],
"address": [
{
"use": "home",
"line": ["Musterstraße 1"],
"city": "Berlin",
"postalCode": "10115",
"country": "DE"
}
]
}
Linking data: references
Clinical data is often split across multiple resources. A MedicationRequest, for example, refers to the Patient it is for, and a DiagnosticReport can refer to several Observation resources.
A FHIR Reference links one resource to another, much like a foreign key in a relational database. A reference can include:
reference— the resource type and id, such asPatient/patient-berlin-001;display— a human-readable label for the referenced item;type— the resource type, commonly used with logical references;identifier— an identifier for the target when a direct resource reference is not available.
In Ovok, you will usually use reference and may include display for readability.
Example: link a MedicationRequest to a Patient and Practitioner
This fictional prescription request refers to a patient and the practitioner who requested it. The medication and dosage are illustrative only; they are not treatment instructions.
Show the linked resources
{
"resourceType": "MedicationRequest",
"id": "medication-request-001",
"status": "active",
"intent": "order",
"medicationCodeableConcept": {
"text": "Paracetamol",
"coding": [
{
"system": "http://fhir.de/CodeSystem/bfarm/atc",
"code": "N02BE01",
"display": "Paracetamol"
}
]
},
"subject": {
"reference": "Patient/patient-berlin-001",
"display": "Johann Mustermann"
},
"dosageInstruction": [
{
"text": "Example only — follow the approved medication plan."
}
],
"requester": {
"reference": "Practitioner/practitioner-001",
"display": "Dr. Erika Beispiel"
}
}
Ovok exposes REST and GraphQL interfaces for querying FHIR data. Search is based on supported parameters for each resource rather than arbitrary fields. See the Ovok API references for the available operations and search parameters.
Describing coded values: CodeableConcept
Healthcare systems use codes to represent diagnoses, procedures, observations, medications, and other clinical concepts consistently. In Germany, common terminology systems include ICD-10-GM for diagnoses, OPS for procedures, ATC for medication classification, and PZN for pharmaceutical products. Many clinical measurements also use international code systems such as LOINC.
FHIR's CodeableConcept can carry human-readable text and one or more coding entries. Each Coding identifies its system and code. A single concept can therefore be represented in more than one system when a workflow requires it.
Example CodeableConcept
This example represents paracetamol using its ATC code. Add a PZN coding when your workflow needs to identify a specific pharmaceutical product or pack; use the value supplied by your trusted product catalogue. See Medication for the resource structure that can carry coded medication information.
Show the CodeableConcept
{
"text": "Paracetamol",
"coding": [
{
"system": "http://fhir.de/CodeSystem/bfarm/atc",
"code": "N02BE01",
"display": "Paracetamol"
}
]
}
The system is an absolute URI that identifies the code system. For example, the German FHIR base profiles use http://fhir.de/CodeSystem/bfarm/atc for ATC and http://fhir.de/CodeSystem/ifa/pzn for PZN. The codes themselves are maintained by their respective publishers and should come from an appropriate terminology service or catalogue.
Naming data: Identifier
The same person or organisation can have identifiers in several systems. A Patient may have an organisation-local patient id, a hospital case number for an Encounter, and—when required for the workflow—a German health insurance identifier.
FHIR represents an identifier with the Identifier type. Its system and value identify the authority or namespace that issued it and the value assigned there. Use a stable URI for systems you own, and follow the relevant German FHIR profiles for nationally defined identifiers.
Prefer the Ovok resource id for references inside Ovok. Store external identifiers only when the workflow needs them, and handle personal identifiers such as a health insurance number with appropriate access controls.
Example: Patient with identifiers from different systems
This example uses clearly fictional values. The KVID value is a placeholder, not a valid insurance number.
Show the Patient identifiers
{
"resourceType": "Patient",
"id": "patient-berlin-001",
"name": [
{
"use": "official",
"family": "Mustermann",
"given": ["Johann"]
}
],
"identifier": [
{
"system": "https://clinic.example.de/identifiers/patient-id",
"value": "PAT-EXAMPLE-001"
},
{
"system": "http://fhir.de/sid/gkv/kvid-10",
"value": "EXAMPLE-KVID"
}
]
}
HL7 Deutschland documents the German FHIR conventions for health insurance identifiers and medication code systems. Check the applicable profile before exchanging these identifiers with a partner.
Restricting codes: ValueSets
A ValueSet defines which codes are allowed for a particular use. Its compose element can select a subset from a larger code system—for example, the observation codes an application accepts for a vital-sign workflow. German projects may draw on systems such as ICD-10-GM, OPS, ATC, and PZN, alongside international systems such as LOINC.
This example shows a small set of LOINC codes for common vital signs. The URI is illustrative; define and publish the canonical URL for your own ValueSet.
{
"resourceType": "ValueSet",
"url": "https://example.org/fhir/ValueSet/vital-signs",
"name": "VitalSigns",
"title": "Vital signs",
"status": "active",
"compose": {
"include": [
{
"system": "http://loinc.org",
"concept": [
{ "code": "8310-5", "display": "Body temperature" },
{ "code": "8462-4", "display": "Diastolic blood pressure" },
{ "code": "8480-6", "display": "Systolic blood pressure" },
{ "code": "8867-4", "display": "Heart rate" },
{ "code": "9279-1", "display": "Respiratory rate" }
]
}
]
}
}
Listening for changes: Subscriptions
FHIR's Subscription resource describes how an application can be notified when matching data changes. Its criteria selects resources using a FHIR search expression; its channel describes how notifications are delivered. Available channels and behavior depend on the FHIR version and the Ovok project configuration.
An Ovok Bot can be used in a configured workflow to respond to data changes. See the Ovok API references for the supported subscription and bot operations.