ResMed Core Implementation Guide
0.37.0 - ci-build
ResMed Core Implementation Guide
0.37.0 - ci-build
ResMed Core Implementation Guide - Local Development build (v0.37.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Resources can be identified in several manners depending on the resource type, independence, and lifecycle phase. Resource identity is used when retrieving resources, and for resources to reference other resources. Although in common language “id” and “identifier” are synonyms, they have distinct meanings in FHIR.
Except for a few special cases, resources stored on a FHIR server have a logical id assigned by the server. This id is unique within the resource type on that server and, once assigned by the server, never changes over the life of the resource. The id combined with the server’s base URL and the resource type form the RESTful identity of that resource. Copying the resource from one server to another typically means assigning it a new id (and definitely would mean a new full RESTful identity).
A new resource created by a client does not need to have an id; the id will be assigned by the server when it is stored. In fact, if an id is provided, it may be ignored. The assigned id is returned in the Location header (in the form of a full URL consisting of server base url, resource type, id, and potentially version information).
An update to an existing resource must preserve the id. In part, that is what distinguishes the action as an update instead of a request to create a new resource.
A resource may be retrieved directly from {server base URL}/{resource type}/{id}, or by search via {server base URL}/{resource type}?_id={id} (which returns a Bundle containing the resource).
A resource usually references other resources on the same server with a relative URL of the form {resource type}/{id}. A reference to a resources on another server is by full URL {server base URL}/{resource type}/{id}. To refer to a specific version of a resource, append the relative or absolute URL with /_history/{versionId}.
Most resources have one or more Identifier elements. This datatype is used to record “business” identifiers: Patient medical record numbers (MRNs), device serial numbers, practitioner license number, and so on. As these values typically reflect “real-life” identifiers, they do not change when a copy of a resource is made (even onto a different server).
The Identifier datatype supports recording the value of the identifier, as well as the system. An Identifier.system is the scope in which that value is unique. For example, there may be more than one clinician with a license number of 82464; that number may be from a physician licensure organization in one state, or from such an organization in another state, or from a nursing college. The system element is a URL (which may or may not resolve) that provides the context for the value.
Identifiers may also have a type (identified by code value and system) to classify the identifier. Patient MRNs, practitioner license number, and drivers’ licenses are all identifier types. Use of type is helpful to support cases where the specific identifier system is not known in advance. Identifier.assigner is used to record who or where gave that identifier to the subject. For example, on a Patient record, there may be an Identifier of type driver’s license; a system that provides the scope of the number as unique to a particular state; and an assigner of a particular Department of Motor Vehicles office within that state.
Although we tend to think of identifiers as unique, there is nothing in FHIR that requires that, as there may be reasonable use cases for duplication. A Patient and Practitioner record that both represent the same person may have the same Social Insurance Number identifier; an insurance policy identifier may cover all members of the family; even in cases of a patient providing a fraudulent insurance number, common healthcare practice would be to accept the number even if it is a duplicate, provide treatment, and deal with the fraud after.
FHIR defines additional requirements around some specific identifiers specified by RFC 3986. These identifiers include GUIDs, OIDs, URLs, document DOIs, and other URIs. Except in narrow cases, these identifiers use the system urn:ietf:rfc:3986, and the value is formatted according to the RFC. That means, GUIDs/UUIDs and OIDs values are prefixed with urn:uuid: and urn:oid:, respectively.
Resources cannot be directly accessed by identifier. However resource types with identifier elements allow searching by identifier.
Several resources, including ValueSet, CodeSystem, and StructureDefinition (which represents profiles and extensions) have a special identifier recorded in the url element of the resource. This “canonical URL” is the official “name” of the resource; that is, this is how it is referenced by other resources. Canonical resources tend to be duplicated on multiple systems so having a single “name” simplifies management. All systems can use the same “name” for the heart rate profile (http://hl7.org/fhir/StructureDefinition/heartrate); all systems use the same “name” for the LOINC code system (http://loinc.org).1
Canonical URLs often resolve to a webpage that describes the resource. For example, the “Patient birth place” extension has a canonical URL of http://hl7.org/fhir/StructureDefinition/patient-birthPlace which also resolves to a description of that extension. This behavior makes finding documentation on the resource easier, but is not required.
Resources cannot be directly accessed by canonical URL. However resource types with url elements support searching by url.
Canonical resources usually have a version element to record the business version of the resource. This is independent of the resource history versionId element. It is common for resources with the same canonical url but different version values to exist on the same server; for example a newer and old version of a ValueSet. Rules are defined for specifying a reference to, or searching for, a particular (business) version of a canonical resource.
Usually, resources are independent and relations to other resources are maintained through references. However,resources may exist within another resource. The outer resource is the containing resource; the inner resource is a contained resource. This is typically used when the contained resource is lacking enough information to exist independently.
Resource containment is distinct from resources within a Bundle.
For example, the performer element within Procedure is intended to refer to the Practitioner who performed the procedure; if, while giving their history, the patient can only provide that the procedure was done by a Dr. Versteegh, then a contained Practitioner within the Procedure resource is a reasonable choice. On the other hand, if the patient asserts that the procedure was done by Dr. Versteegh who works in this clinic, then there is likely an existing separate Practitioner resource the performer element can reference.
A portion of an independent Practitioner resource:
{
"resourceType": "Practitioner",
"id": "0e29a4ce-e69b-41ea-ba4d-4c0959c0f3b5",
"identifier": [
{
"use": "official",
"system": "urn:oid:2.16.528.1.1007.3.1",
"value": "846100293"
}
],
"name": [
{
"use": "official",
"family": "Versteegh",
"given": [
"Marc"
],
"suffix": [
"MD"
]
}
],
"telecom": [
{
"system": "phone",
"value": "0205562431",
"use": "work"
}
],
"gender": "male"
}
and portions of an independent Procedure resource which references the Practitioner:
{
"resourceType": "Procedure",
"id": "c4fb8ecb-6c1d-47ae-9225-d577699a6b51",
"status": "completed",
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "359615001",
"display": "Partial lobectomy of lung"
}
]
},
"subject": {
"reference": "Patient/b98ab63b-49e9-4dd2-b9d6-a6b9350090f8",
},
"performer": [
{
"actor": {
"reference": "Practitioner/0e29a4ce-e69b-41ea-ba4d-4c0959c0f3b5",
}
}
]
}
On the other hand, a Procedure resource with a contained Practitioner:
{
"resourceType": "Procedure",
"id": "c4fb8ecb-6c1d-47ae-9225-d577699a6b51",
"contained": [
{
"resourceType": "Practitioner",
"id": "aaaa",
"name": [
{
"family": "Versteegh"
}
]
}
],
"status": "completed",
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "359615001",
"display": "Partial lobectomy of lung"
}
]
},
"subject": {
"reference": "Patient/b98ab63b-49e9-4dd2-b9d6-a6b9350090f8",
},
"performer": [
{
"actor": {
"reference": "#aaaa"
}
}
]
}
The id of the contained resource is unique within (and determined by) the containing resource. The contained resource is referenced from the containing resource as a URL “fragment”. (In the limited number of cases when a contained resource is referenced from outside the containing resource, the containing resource’s id is prepended to the fragment.)
Contained resources cannot be modified or accessed independent of the containing resource. By default, contained resources are not included in evaluating searches (with a limited exception) or search results; this can be controlled with the _contained search parameter.
The Bundle resource is used for a number of purposes within FHIR that involve putting an envelope around multiple resources.
Patient resource can be written to the /Patient endpoint and stored, a Bundle can be written to the /Bundle endpoint and stored; this is most often used for Bundle.type of document.type = search-set).type = transaction), and batch operations (type = batch), or custom messaging behavior.In a transaction, all operations must succeed or the transaction fails and the changes are rolled back. In a batch, individual operations may fail without impacting the success of the Bundle processing. Bundles have a number of other uses as well.
When created independently, references in a new resource are to resources already existing on the server. However, because a transaction can create multiple resources at once, an opportunity arises where the referenced resource doesn’t yet have a server-assigned id. To address this, resources in a transaction Bundle can have a temporary, client-assigned id for new resources. Usually this temporary id is a GUID of the form urn:uuid:.... When the Bundle is processed and the resource assigned a permanent id, the temporary id is replaced with the permanent id in all references from other resources in the Bundle.
In a Bundle entry, the fullUrl element is required and must be consistent with the id element of the entry’s resource, unless the resource has not yet been created on the server. The fullUrl is an absolute address made up of the server’s base URL, the resource type and the resource id. It does not include resource version information.
“Name” here is used in a colloquial sense, and is not to be confused with the separate name element in many resources which is a hint to code generators for what to call a class that represents that resource. ↩