References and bundles

Resources link up. Bundles carry them together.

One resource rarely tells the whole story. Resources link to each other through references, and they travel together in bundles.

Resources point to each other

Many elements in a resource are references to other resources. Using these references, resources combine to build a web of information about healthcare. For example, a procedure can refer to a patient as its subject, and to a condition as its reason.

• Procedure · subject · link · Patient · person · procedure
• Procedure · reason · link · Condition · warning · procedure
• Source resource
• Element
• Target resource

A reference holds a URL

A literal reference holds a URL. It can be an absolute URL. It can be a relative URL, relative to the service base address or, inside a bundle, to the entry's full URL. Or it can be an internal fragment that points to a contained resource.

• Absolute URL · The full address · globe
• Relative URL · Relative to a base address · share
• Internal fragment · Points to a contained resource · lock

References go one way

References are written in one direction, from the source resource to the target. The reverse relationship exists logically, but it is not usually written in the target. To follow it you need infrastructure, such as the reverse search in the REST API. And relationships are not transitive: the patient of a condition is not inferred from a procedure that refers to it.

A purpose, and its bundle type

A bundle gathers a collection of resources into a single instance. Its type states what it is for. To return search results, use a search set. To return a resource's versions, history. To send a message, message. To exchange a clinical document, document. To create, update or delete several resources in one operation, transaction or batch. And to simply collect and store resources, collection.

• Return search results · searchset · search · navy
• Return a resource's history · history · clock · navy
• Send a message · message · share · amber
• Exchange a clinical document · document · file · slate
• Change many resources at once · transaction or batch · gear · slate
• Just collect and store · collection · box · slate

Contained or bundled?

There are two ways to collect resources together: contained resources, and bundles. Contained resources are inside their container, and can only be interpreted or changed in its context. A bundle is a collection of resources that can have an independent existence; for example, they might also be accessed directly through the REST API. A bundle itself is merely a container, used for transfer and storage.

A reference, as data

Here is a procedure form that points to other folders. The subject is patient folder one two three. The encounter is a folder in another cabinet. Turn it over. Each link is an element holding a reference. The element says what the link means. The reference is a relative URL: the resource type, a slash, then the id.

Check yourself

Pause and think. Which is true of a contained resource? The answer: it can only be interpreted in the context of its container.

• It can only be interpreted in the context of its container
• It always has its own independent address
• It appears only in search results
• It must be a clinical resource

Keep these in mind

References link resources, in one direction. Relationships are not assumed to carry over. A bundle collects resources into one instance. And its type states the purpose.

• References link resources, in one direction
• Relationships are not assumed to carry over
• A bundle collects resources into one instance
• Its type states the purpose