# FHIR Basics
Canonical page: https://docs.ovok.com/fhir-basics
Source Markdown: https://docs.ovok.com/llms/fhir-basics.md
Learn the FHIR concepts used to represent and connect healthcare data in Ovok.
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](https://hl7.org/fhir/R4/).
## Storing data: resources
A core data object in FHIR is called a [**Resource**](/fhir-elements/foundation/resource). You can think of a resource as a typed object in an application. FHIR defines resources for healthcare concepts such as [`Patient`](/api/fhir/r4/patient), [`Medication`](/api/fhir/r4/medication), [`Device`](/api/fhir/r4/device), [`Observation`](/api/fhir/r4/observation), [`Procedure`](/api/fhir/r4/procedure), [`CarePlan`](/api/fhir/r4/care-plan), and [`Encounter`](/api/fhir/r4/encounter).
Each field in a resource is an [**Element**](/fhir-elements/complex/element). Elements use primitive types such as [`string`](/fhir-elements/primitive/string), [`decimal`](/fhir-elements/primitive/decimal), and [`date`](/fhir-elements/primitive/date), or complex types such as [`HumanName`](/fhir-elements/complex/human-name) and [`Address`](/fhir-elements/complex/address). Most resources also have an [`id`](/fhir-elements/foundation/resource#element-id): a server-assigned identifier that is unique within that server. Browse all types in [FHIR Elements](/fhir-elements) or all resources in [FHIR resources](/api/fhir/r4).
### Example [Patient](/api/fhir/r4/patient)
The example below shows a fictional Patient resource with [`name`](/api/fhir/r4/patient#element-name), [`telecom`](/api/fhir/r4/patient#element-telecom), and [`address`](/api/fhir/r4/patient#element-address) elements. It contains no real patient information.
Show the Patient resource
```json
{
"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`](/api/fhir/r4/medication-request), for example, refers to the [`Patient`](/api/fhir/r4/patient) it is for, and a [`DiagnosticReport`](/api/fhir/r4/diagnostic-report) can refer to several [`Observation`](/api/fhir/r4/observation) resources.
A FHIR [**Reference**](/fhir-elements/complex/reference) links one resource to another, much like a foreign key in a relational database. A reference can include:
- [`reference`](/fhir-elements/complex/reference#element-reference) — the resource type and id, such as `Patient/patient-berlin-001`;
- [`display`](/fhir-elements/complex/reference#element-display) — a human-readable label for the referenced item;
- [`type`](/fhir-elements/complex/reference#element-type) — the resource type, commonly used with logical references;
- [`identifier`](/fhir-elements/complex/reference#element-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](/api/fhir/r4/medication-request) to a [Patient](/api/fhir/r4/patient) and [Practitioner](/api/fhir/r4/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
```json
{
"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](/api) for the available operations and search parameters.
## Describing coded values: [CodeableConcept](/fhir-elements/complex/codeable-concept)
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](/fhir-elements/complex/codeable-concept) can carry human-readable [`text`](/fhir-elements/complex/codeable-concept#element-text) and one or more [`coding`](/fhir-elements/complex/codeable-concept#element-coding) entries. Each [`Coding`](/fhir-elements/complex/coding) identifies its [`system`](/fhir-elements/complex/coding#element-system) and [`code`](/fhir-elements/complex/coding#element-code). A single concept can therefore be represented in more than one system when a workflow requires it.
### Example [CodeableConcept](/fhir-elements/complex/codeable-concept)
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`](/api/fhir/r4/medication) for the resource structure that can carry coded medication information.
Show the CodeableConcept
```json
{
"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](/fhir-elements/complex/identifier)
The same person or organisation can have identifiers in several systems. A [`Patient`](/api/fhir/r4/patient) may have an organisation-local patient id, a hospital case number for an [`Encounter`](/api/fhir/r4/encounter), and—when required for the workflow—a German health insurance identifier.
FHIR represents an identifier with the [`Identifier`](/fhir-elements/complex/identifier) type. Its [`system`](/fhir-elements/complex/identifier#element-system) and [`value`](/fhir-elements/complex/identifier#element-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](/api/fhir/r4/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
```json
{
"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](https://ig.fhir.de/basisprofile-de/stable/ig-markdown-LebenslangeKrankenversichertennummer10-stelligeKVID-Identifier.html) and [medication code systems](https://ig.fhir.de/basisprofile-de/stable/ig-markdown-Medication-CodeSystem.html). Check the applicable profile before exchanging these identifiers with a partner.
## Restricting codes: [ValueSets](/api/fhir/r4/value-set)
A [**ValueSet**](/api/fhir/r4/value-set) defines which codes are allowed for a particular use. Its [`compose`](/api/fhir/r4/value-set#element-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.
```json
{
"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](/api/fhir/r4/subscription)
FHIR's [`Subscription`](/api/fhir/r4/subscription) resource describes how an application can be notified when matching data changes. Its [`criteria`](/api/fhir/r4/subscription#element-criteria) selects resources using a FHIR search expression; its [`channel`](/api/fhir/r4/subscription#element-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](/api) for the supported subscription and bot operations.
## Further reading
- [Official FHIR R4 documentation](https://hl7.org/fhir/R4/)
- [HL7 Deutschland FHIR Base Profiles](https://ig.fhir.de/basisprofile-de/stable/)
- [Ovok API references](/api)