FHIR glossary

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.

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.

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.

A bundle type designates how the bundle was packaged and should be processed (see definition of 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.

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.

Ultimately, a code value can be anything within FHIR®’s predefined, standard code system.

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

  Copy

  1
  {
  2
    "codeableConcept": {
  3
      "text": "CBC WO DIFFERENTIAL"
  4
    }
  5
  }
• a code, system, and free-text field

  Codeable concept 2

  json

  Copy

  1
  {
  2
    "codeableConcept": {
  3
       "coding": [
  4
         {
  5
           “code”: “43789009”,
  6
           “system”: “http://snomed.info/sct”,
  7
           “text”: "CBC WO DIFFERENTIAL" 
  8
         }
  9
       ]
  10
    }
  11
  }

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.

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.

1
"coding": {
2
  "code": "2670",
3
  "system": "http://www.nlm.nih.gov/research/umls/rxnorm"
4
}

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
• resource

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)
   • references (see definition of references)

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.

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.

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).

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.

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.

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.

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.

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.

There are two different subtypes of literal references:

• Relative 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 resource is a single, structured data object that conforms to a specific resource type. Learn about 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.

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.