On this page:

4.1FHIR Basics

 

This page discusses the basics when interacting with a FHIR server such as Smile CDR. Let's begin by talking about the data model in FHIR.

4.1.1Resources

 

FHIR defines a number of data models covering the many types of things that are generally modelled in healthcare applications. Each data model is called a resource model.

Each FHIR resource model is a data type for something you could model in healthcare. For example, FHIR defines a Patient resource model, which has all of the standard attributes you would expect to see modelled on a healthcare patient.

FHIR resource models look like the following (reference):

FHIR Resource Model

Resource data models are defined in a tree structure. FHIR structures are typically not very deep, with important fields generally being found either at the root of the tree or not nested very deeply. Each field in the tree will have:

  • A cardinality: What is the minimum and maximum number of values this field may have. Most fields in FHIR will either have a cardinality of 0..1 (optional field) or 0..* (optional field which may repeat), although there are a few exceptions.
  • Flags: Flags in the FHIR specification include the following (reference)
    • Σ means that the element will be included in a Summary View
    • ?! means that the element is a modifier element

4.1.2Datatypes

 

FHIR resource models use a set of data types for holding their values. Data types can be primitive, meaning that they hold a simple value (typically a string, a number, etc.). Other data types are composite, meaning they are a structure containing several elements.

A few of the commonly used primitive data types are shown in the table below. You can see the complete list of available data types on the FHIR data types page (reference).

Primitive Datatype Example
String A string of text. Smile at me
Decimal A number with arbitrary precision (FHIR allows as much precision as you need). 3.1415
DateTime A human created or observed time, such as a request that something happen at a specific time. DateTime can have variable precision, but must have a timezone offset if the DateTime has a time component 2011-01-03T09:40-04:00
Instant A system time, such as a system recording that something was stored at a given time. Instants must have millisecond precision, and must have a timezone offset 2011-01-03T09:40:22.002-04:00

Composite data types are composed of several elements. For example:

Composite Datatype Example
HumanName A person's complete name, broken into individual parts
{
   "family": "Smith",
   "given": [ "John", "Frank" ],
   "suffix": [ "Jr" ]
}
ContactPoint Details about a method for contacting someone, such as a phone number or an email address. It has fields for the actual value, as well as fields for codifying what type of address it is (phone, email, etc.) and how the value is used (home, work, etc.).
{
   "system": "phone",
   "value": "1 (416) 555 1234",
   "use": "work"
}

4.1.3Parts of a Resource

 

Resources instances will generally have a few key parts:

Resource ID Every resource that has been saved in the CDR has a unique identifier. Identifiers in FHIR are up to 64 characters long, and may contains letters, numbers, dashes and dots (reference). Resource identity is often expressed in the form [resource type]/[id], for example: Patient/123.
Metadata Resources will have several important pieces of metadata associated with them:
  • A version: This is an identifier which refers to this specific version of the resource. Smile CDR uses sequentially generated numeric version identifiers (starting at 1), so if you see a resource with version 3, you know that it has been created, and then updated exactly twice.
  • A last updated time: This is the timestamp recorded by the server when the resource was saved. This field is automatically set by the server and cannot be set or changed by the client.
  • Tags: Resources can have tags associated with them for various reasons. The FHIR specification defines a small ValueSet of commong tags (reference) but you can define your own tags as well.
  • Security Labels: Resources can also have special tags which indicate security considerations for resources. The FHIR specification defines a ValueSet with common security labels (reference) but you can also define your own.
  • Profiles: Profiles are special labels which indicate that a given resource is declaring that it conforms to a given FHIR Profile. Profiles in FHIR are defined in a special set of resources, primarily the StructureDefinition resource (reference)
Narrative / Text Most resource types have a special field called `text` which holds the "narrative" for the resource. The narrative is an HTML representation of the content of the resource, suitable for showing to a human. Narratives are useful because in many cases even if a client has no ability to process the structured body of a resource, you can still achieve basic interoperability by displaying the narrative. (reference)
Body / Structured Content Most of the contents of a typical resource are in the body, which is the section containing the structured contents.

4.1.4Encodings (MIME Types, Wire Formats)

 

FHIR defines several ways of encoding instances of the data model. Users of previous HL7 standards might call these instances "messages" but messaging is only one way of using FHIR; we will call them "payloads" in order to be more accurate.

Each format is given a MIME type, which is the value used in the Content-Type and Accept headers to represent that type.

Format Name MIME Type
JSON (reference) application/json+fhir
XML (reference) application/xml+fhir

The JSON Format

FHIR defines a JSON encoding, which is documented in the FHIR specification on the JSON page. This format looks as follows:

JSON Resource
Resource ID
Metadata
Narrative
Body
{ "resourceType": "Patient",
"id": "example01",
"meta": { "versionId": "1", "lastUpdated": "2017-07-01T02:22:06.586-04:00", "tag": [ { "system": "http://projectcrucible.org", "code": "testdata" } ] },
"text": { "status": "generated", "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Peter James CHALMERS (MRN 12345)</div>" },
"identifier": [ { "system": "urn:oid:1.2.36.146.595.217.0.1", "value": "12345" } ], "active": true, "name": [ { "family": "Chalmers", "given": [ "Peter", "James" ] } ], "gender": "male", "birthDate": "1974-12-25", "address": [ { "line": [ "534 Erewhon St" ], "city": "PleasantVille", "state": "Vic", "postalCode": "3999" } ] }

The XML Format

FHIR defines an XML encoding, which is documented in the FHIR specification on the XML page. This format looks as follows:

XML Resource
Resource ID
Metadata
Narrative
Body
<Patient xmlns="http://hl7.org/fhir">
<id value="example01"/>
<meta> <versionId value="1"/> <lastUpdated value="2017-07-01T02:22:06.586-04:00"/> <tag> <system value="http://projectcrucible.org"/> <code value="testdata"/> </tag> </meta>
<text> <status value="generated"/> <div xmlns="http://www.w3.org/1999/xhtml"> Peter James CHALMERS </div> </text>
<identifier> <system value="urn:oid:1.2.36.146.595.217.0.1"/> <value value="12345"/> </identifier> <name> <family value="Chalmers"/> <given value="Peter"/> <given value="James"/> </name> <gender value="male"/> <birthDate value="1974-12-25"> </birthDate> <address> <line value="534 Erewhon St"/> <city value="PleasantVille"/> <state value="Vic"/> <postalCode value="3999"/> </address>
</Patient>