# FHIR glossary
FHIR is a modern, flexible standard you can use to exchange healthcare data. [Learn more about the Redox FHIR API](/basics/redox-fhir-api).
With that flexibility, though, comes complexity. This glossary defines key FHIR concepts like **bundle**, **resource**, or **codeable concept**. Browse through the definitions below to understand the building blocks of FHIR.
bundle
A **bundle** is a group of related but independent FHIR resources. Bundles are used anytime collections of FHIR resources are sent or received as a unit. [Learn more about the `Bundle` resource](https://www.hl7.org/fhir/bundle.html).
Sending a bundle is like sending a package to someone. The package might contain one or more items (i.e., **resources**), but the package includes a packing slip to list what’s inside (i.e., **header data**). Additionally, the **bundle type** helps determine how the destination processes the package. [Learn about bundle types](https://docs.redoxengine.com/basics/redox-fhir-api/fhir-glossary/#bundle-type).
Some common use cases of bundles with Redox are:
- **FHIR translation**: Redox uses bundles for large-scale data transfers and stateful messaging workflows. When we translate older standards to FHIR, we convert the HL7v2 or CDA message to a FHIR bundle. For example, an HL7v2 message might translate into anywhere from 10 to 100 FHIR resources in a message, while a CDA may easily start at least 50.
- **FHIR query responses**: A query response typically returns a bundle to combine the resources identified by the search criteria.
- **FHIR writeback**: A writeback message (a type of FHIR messaging) relies on bundles to group related resources into a package that you push to your connection.
bundle type
A **bundle type** designates how the bundle was packaged and should be processed ([see definition of bundle](https://docs.redoxengine.com/permalink/23Q1Oku3NdxxvwYnQGJVrg/#bundle)). Redox supports these bundle types:
- **Searchset** bundles are what’s returned in response to a FHIR query (`_search` interactions). Searchset bundles can have zero entries, meaning there are no results matching the search criteria, or one or more resources that do match the search criteria.
- **Message bundles** are a more general bundle of resources with no specific instructions on how they should be processed. Redox still attaches an event type to convey some meaning, but the destination system gets to decide what to do with the bundle. This is a flexible option that most systems can support without requiring a FHIR server. Redox uses message bundles for FHIR notifications and writebacks.
code
A **code** is a common datatype in a FHIR resource that indicates the value is one of a certain fixed set of values.
You can think of it as a code value within a codeset (i.e., a set of codes explicitly mandated by the FHIR specification). In a sense, **code** is like **coding** where the system is FHIR and the values can’t be changed.
| **Example codeset** | **Values** |
| --- | --- |
| `AppointmentStatus` | `proposed` \| `pending` \| `booked` \| `arrived` \| `fulfilled` \| `cancelled` \| `noshow` \| `entered-in-error` \| `checked-in` \| `waitlist` |
| `Allergy intolerance-clinical` | `active` \| `inactive` \| `resolved` |
Ultimately, a code value can be anything within FHIR’s predefined, standard code system.
codeable concept
A **codeable concept** is a common datatype in a FHIR resource that defines an object’s code system with an associated text field.
It could contain either of these structures:
- a free-text field with a verbal description of the object’s code
**Codeable concept 1**
```json
{
"codeableConcept": {
"text": "CBC WO DIFFERENTIAL"
}
}
```
- a code, system, and free-text field
**Codeable concept 2**
```json
{
"codeableConcept": {
"coding": [
{
“code”: “43789009”,
“system”: “http://snomed.info/sct”,
“text”: "CBC WO DIFFERENTIAL"
}
]
}
}
```
Codeable concepts are helpful when organizations use different code systems to identify the same thing. For example, there may be a lab test that organizations codify differently, but the name of the test would be the same. Just remember that a codeable concept means that there’s a text field used to define the code system.
This datatype is also helpful if you need to include multiple sets of coding.
coding
A **coding** is a common datatype in a FHIR resource that defines the code value and system for the related object. Using a coding array is a simple, direct way to reference the code and system, and it’s commonly used in extensions.
**Coding example**
```json
"coding": {
"code": "2670",
"system": "http://www.nlm.nih.gov/research/umls/rxnorm"
}
```
contained resource
A **contained resource** is a related resource that’s directly included within a source resource.
Think of a contained resource like an embedded file in an API request versus a link to a file in a repository. A file link requires the destination system to have access to the file repository. If the destination system doesn’t have access to the file repository, an embedded file is a better option. It’s the same with resources. If the related resource doesn’t exist in the destination system, you might need to include a contained resource instead of only referencing a resource ID.
A temporary ID is generated for a contained resource and is included within the `contained` field of the source resource. You can identify these types of IDs because they start with a `#` symbol. For example, if you see an `Appointment` resource with a participant ID of `#123456`, then you know it’s referencing a contained resource.
Check out these related definitions for more context:
- [reference](https://docs.redoxengine.com/permalink/23Q1Oku3NdxxvwYnQGJVrg/#reference)
- [resource](https://docs.redoxengine.com/permalink/23Q1Oku3NdxxvwYnQGJVrg/#resource)
datatype
A **datatype** is a structured field, element, or array used in FHIR schemas. In concept, it’s similar to a resource type, but at a granular level for a piece of data within a resource. Datatypes are standardized across resource types.
There are four datatypes:
1. **Simple types** consist of one element with a primitive value. Some examples:
- `id`
- `code`
- `boolean`
- `uri`
- `string`
- `integer`
2. **Complex types** consist of a set of elements. Some examples:
- `attachment`
- `codeableConcept`
- `coding`
- `quantity`
- `identifier`
3. **Metadata types** consist of standards for metadata for knowledge resources. Some examples:
- `contactInformation`
- `dataRequirement`
- `parameterDefinition`
- `relatedArtifact`
4. **Special purpose** types are standards for a broader set of data for specific usages. Some examples:
- extensions ([see definition of extension](https://docs.redoxengine.com/permalink/23Q1Oku3NdxxvwYnQGJVrg/#extension))
- references ([see definition of references](https://docs.redoxengine.com/permalink/23Q1Oku3NdxxvwYnQGJVrg/#reference))
extension
An **extension** is a set of additional elements included in a standard FHIR resource to create a unique resource profile.
Since resources are intended to be a base, extensions can be useful if there’s additional information you commonly want to include when exchanging data. Extension arrays could be named `extension`, or if we’re extending a simple field within a resource, it’d be `_[element]`.
For example, the standard FHIR `DeviceRequest` status indicates whether the status is `completed` or `pending`. The Redox extension for the `DeviceRequest` resource adds color by also including the number of devices requested.
id vs. identifier
An **id** is an internal FHIR identifier for a resource. When a resource is stored in a database, it’s referenced using the resource ID. For **data on demand**, this is going to be a UUID.
An **identifier** is an external business identifier, meaning it’s created and maintained by a system outside the FHIR server. An identifier has an associated `system` and `value`. The `system` defines the format and interpretation of the `value`. The `system` identifies the external system and should be expressed in a FHIR payload as a URI. As an example, a Social Security number is a type of identifier for a patient record, and the external system defines that it should be a numeric value with nine digits, as well as assigns the specific value.
interaction vs. operation
Interactions and operations are terms with a specific meaning in the context of a FHIR RESTful API.
**Interactions** (often called CRUD requests) are RESTful, which means they allow you to read, update, or delete an existing resource, as well as create a new resource. Interactions are standardized and straightforward actions that allow you to modify the state of or read a resource stored in a FHIR server. But many interactions (especially those not mandated by USCDI, like create or patch) aren’t likely to be available for every connection.
**Operations** are used for “non-RESTful” parts of the FHIR HTTP API. Conceptually, they’re similar to RPC-style endpoints that can trigger arbitrary logic on the server beyond just transferring the state of a resource. Operations are more flexible than interactions, but that also means they’re more complicated and less standardized.
You can distinguish between an operation and an interaction by its name, since FHIR operations start with `$` (e.g., `$convert`, `$message`, `$submit`).
message
A FHIR **message** is a payload sent from one FHIR server to another. This type of data exchange follows the FHIR messaging framework. [Learn more about FHIR messaging](/basics/redox-fhir-api/exchanging-fhir-data).
All FHIR messages store their payload in a `Bundle` resource. The first resource in the bundle is a special one called a `MessageHeader`, which provides metadata about the origin and meaning of the message payload.
profile
FHIR users can take a base resource type (e.g., a `Patient` resource) and create a **profile** that extends the purpose of the resource to suit their business needs. In other words, FHIR users can build their own standard on top of the base HL7 standard to define additional rules about how a FHIR resource type should be used for a given scenario. This clarifies how end users may use that resource type.
Redox created a library of resource profiles specifically for customers like you, based on common use cases we’ve seen. With Redox profiles, we simplify and streamline the experience of real-world FHIR integrations so you can compose your own unique workflow.
reference
A **reference** indicates a one-way relationship from one resource to another.
The resource being pointed to (the metaphorical endpoint) is sometimes known as the **target resource**. The **source resource** may contain multiple references to target resources. Think of this like a bubble map with a source resource at its center with branches (i.e., references) pointing outward to related target resources. Remember, though, that the reference is a unidirectional pointer.
*A source resource with references to target resources*
There are two types of references:
- **literal reference** (_most common_)
- **logical reference**
A **literal reference** points to a given target resource using the resource ID. Redox commonly uses literal references because they’re simpler to implement. In an everyday analogy, this is like referring to a person not present in the conversation by using their given name.
*A source resource with a literal reference to a target resource*
There are two different subtypes of literal references:
- **R****elative literal reference**: Relative to a specific FHIR server. For example, a patient’s FHIR ID within a given FHIR server.
- **Fully qualified literal reference**: Typically a full URL to a reference, which isn’t specific to a FHIR server. The URL is used for queries across different FHIR servers. This occurs in a FHIR notification, in the `fullURL` field. You can download the URL value to view the full `Patient` resource.
A **logical reference** points to a target resource using identifying information other than the ID. This is helpful if you don’t know the FHIR ID. In an everyday analogy, this is like referring to a person not present in the conversation by describing their physical traits, residence, or occupation instead of their given name.
Redox uses logical references for encounters. Instead of a literal reference, the only field we want to save is a visit number. We use that logical reference (i.e., visit number) to identify the encounter, which may or may not be in our system. However, references based on business logic can get complicated, and they’re not very robust either. To use our conversation example, there may be several people with dark hair and glasses, not just one particular individual.
*A source resource with a logical reference to a target resource*
resource
A **resource** is a single, structured data object that conforms to a specific **resource type**. [Learn about resource type](https://docs.redoxengine.com/permalink/23Q1Oku3NdxxvwYnQGJVrg/#resource-type).
When querying for data, you receive a resource with the data populated in the defined schema for that resource type. For example, an individual `Patient` resource is an instance of the `Patient` resource type and contains one person’s demographic information.
resource type
A **resource type** is a standardized schema to organize data. A FHIR resource type is the core architectural building block in that it provides a consistent format for how data should be shaped. Resource types define what data to provide and what data to expect back when exchanging resources. They also contain information about the meaning and clinical interpretation of the resource’s content.