FHIR as paper: forms, cabinets and a clerk

FHIR in a room of paper

The FHIR specification offers clinicians a picture. Think of resources as paper forms. Think of a server as a room of filing cabinets. And think of the REST API as a clerk at the door. Let us walk through it.

A resource is a form; a filled one is data

Here is a patient form, filled in. This is how a person reads it. The specification defines a generic form template for each type of information: one for allergies, one for prescriptions, one for referrals. A completed form is a resource instance. Now turn it over. The same record is data a computer can use. The type of form is named. The name is a human name, with a family name and given names. The gender is a code. And the birth date is a date. One record, two views: a readable one for people, and discrete data for computers.

Cabinets, folders and pages

Now think of a server as a room full of filing cabinets. There is a cabinet for each type of form. Inside, each folder has a unique number and holds one real world thing: one patient, one encounter, one medication. In the folder, each piece of paper is one version of that record. With a read, you get a copy of the top page, the most current version. With an update, a new page is added on top. And with history, you flip through all the pages in the folder.

• Page 1
• Page 2
• Page 3
• read · A copy of the top page
• update · A new page goes on top
• history · Flip through every page

A requisition becomes a request

At the front door sits a clerk. You pass the clerk a requisition. The clerk and the requisition forms make up the RESTful API. Here the requisition asks for a copy of the top page, from the Patient cabinet, folder one two three. Turn it over, and it is a request. A read is an H T T P GET. Then the service base URL, where the cabinets are. Then the type, which is the cabinet. And then the id, which is the folder.

Stapled, clipped or sticky-noted

Sometimes you send several sheets together. A document is a set of sheets stacked with a title page on top, stapled together. The title page is a composition. A message collects sheets too, but its cover page is a message header, like a requisition, and the sheets are held with a paper clip. The receiver need not file them exactly as sent. And services are a lighter way of messaging. A small sticky note on the front of a sheet, and sometimes only fragments cut out and sent.

• Document: stapled · Cover page is a Composition · file
• Message: paper-clipped · Cover is a MessageHeader · share
• Service: sticky note · Light; may send fragments · tag

A binding is a list of allowed answers

Forms can limit the answers. Picture a tick box list on the form. The answer must be one of the boxes. Turn it over, and that is a binding. The element has a datatype, here a code. The binding has a strength. Required means the answer shall come from the list. The list itself is a value set. And the record then holds one code from that list.

Check yourself

Pause and think. In the paper picture, what is a resource instance? The answer: a completed form.

• A completed form
• A blank form template
• A filing cabinet
• The clerk

Keep these in mind

A resource is a form, and a filled form is an instance. A server is cabinets of folders, and the pages are versions. The API is a clerk taking requisitions. And documents are stapled, while messages are paper clipped.

• A resource is a form; a filled form is an instance
• A server is cabinets of folders; pages are versions
• The API is a clerk taking requisitions
• Documents are stapled; messages are paper-clipped