Terminologies-binding-examples

Release 5

This page is part of the FHIR Specification (v5.0.0: R5 - STU). This is the current published version. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4

4.2 Terminology Binding Examples

Terminology Infrastructure icon

Work Group

Maturity Level: 0

Standards Status: Trial Use

4.2.1 Examples for Required bindings

4.2.1.1 On an element of type code

Most elements of type code have a required binding e.g. status elements.

{
  "path" : "CodeSystem.status",
  "definition" : "The status of this code system. Enables tracking the life-cycle of the content.",
  "binding" : {
    "strength" : "required",
    "description" : "The lifecycle status of an artifact.",
    "valueSet" : "http://hl7.org/fhir/ValueSet/publication-status|5.0.0"
  }
}

These bindings generally have a version specific finding (a 'static' binding). The code must come from the indicated value set:

{
  "resourceType" : "CodeSystem",
  "id" : "example",
  "url" : "http://hl7.org/fhir/CodeSystem/example",
  "status" : "draft"
}

4.2.1.2 On an element of type CodeableConcept

Required bindings are generally not used on elements of type CodeableConcept in the base FHIR specification, but such bindings are commonly found in profiles - indeed, narrowing the binding to a specific required value set is one of the basic things profiles exist for.

For example, we have a Condition.code and the applicable profile binds the code to the value set http://acme.com/fhir/ValueSet/problem-codes with an Extensible binding:

{
    "path": "Condition.code",
    "definition" : "Identification of the condition, problem or diagnosis."
    "binding": {
      "strength": "required",
      "valueSetCanonical": "http://acme.com/fhir/ValueSet/problem-codes"
    }
  }

This value set includes the SNOMED CT concepts 282542002 (Unable to stop running), 282548003 (Unable to avoid obstacles when running), and 219389008 (War injury due to fragments from rocket).

4.2.2 Condition example instance

  {
    "resourceType": "Condition",
    "code": {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "282548003",
          "display": "Unable to avoid obstacles when running"
        }
      ],
      "text": "Doomed to run into things always"
    },
    "subject": {
      "reference": "Patient/coyote"
    }
  }

This concept (code = 282548003) is included in the value set so the instance is valid, but if the code 21902005 (Struck by falling rock or stone) was present, it would not be valid. It's also not valid to provide just a text when there's a required binding.

4.2.3 Examples for Extensible bindings

4.2.3.1 Condition.code with Extensible binding

For example, we have a Condition.code and the applicable profile binds the code to the value set http://hl7.org/fhir/ValueSet/condition-code with an Extensible binding:

{
  "path": "Condition.code",
  "definition" : "Identification of the condition, problem or diagnosis."
  "binding": {
    "strength": "extensible",
    "valueSetCanonical": "http://hl7.org/fhir/ValueSet/condition-code"
  }
}

This value set includes all SNOMED CT concepts that are clinical findings.

4.2.4 Condition instance #1

{
  "resourceType": "Condition",
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "39065001",
        "display": "Burn of ear"
      }
    ],
    "text": "Burnt Ear"
  },
  "subject": {
    "reference": "Patient/example"
  }
}

This concept (code = 39065001) is included in the value set so the instance is valid.

4.2.4.1 Condition instance #2

{
  "resourceType": "Condition",
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "312824007",
        "display": "Family history of cancer of colon"
      }
    ]
  },
  "subject": {
    "reference": "Patient/example"
  }
}

This SNOMED CT concept is not a clinical finding. So is it valid? With the extensible binding 2 questions must be answered:

Is there an applicable code in the bound value set (condition-code) for ‘family history of cancer of colon’? That doesn’t appear to be the case, so the instance is valid in that respect.
Does this code fit into the definition of the element in the profile: “Identification of the condition, problem or diagnosis.”? That also appears likely to be the case. But that isn’t entirely clear, which is the challenge of extensible bindings.

So this example is most likely valid (based on human review).

4.2.4.2 Condition instance #3

{
  "resourceType": "Condition",
  "code": {
    "coding": [
      {
        "system": "http://my-local-organization.com",
        "code": "XYZ123",
        "display": "Severe pneumococcal pneumonia"
      }
    ]
  },
  "subject": {
    "reference": "Patient/example"
  }
}

This Condition instance contains a local code. Is it a valid instance? With the extensible binding, the same questions as before have to be answered:

Is there an applicable code in the bound value set (condition-code) for ‘Severe pneumococcal pneumonia’? In this case SNOMED CT does have the code 233607000 for ‘Pneumococcal pneumonia’. Since ‘Pneumococcal pneumonia’ is a more general meaning which "covers" (i.e. includes or subsumes) ‘Severe pneumococcal pneumonia’, this Condition instance is not valid and the SNOMED CT code 233607000 for ‘Pneumococcal pneumonia’ SHALL be used instead.
Does this code fit into the definition of the element in the profile: “Identification of the condition, problem or diagnosis.”? Yes, it does. But since it was already determined that there is an applicable code in the bound value set that should be used instead, this instance is not valid.

4.2.4.3 Condition instance #4

What if we would like to send our local code for ‘Severe pneumococcal pneumonia’ in the instance along with the SNOMED CT code 233607000 for ‘Pneumococcal pneumonia’? Because the datatype for Condition.code is CodeableConcept, we can do that using an additional Coding (as a translation):

{
  "resourceType": "Condition",
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "233607000",
        "display": "Pneumococcal pneumonia"
      },
      {
        "system": "http://my-local-organization.com",
        "code": "XYZ123",
        "display": "Severe pneumococcal pneumonia"
      }
    ]
  },
  "subject": {
    "reference": "Patient/example"
  }
}

So this is a valid Condition instance which contains both the applicable SNOMED CT code from the extensibly bound condition-code value set for ‘Pneumococcal pneumonia’ as well as my organization's local code for ‘Severe pneumococcal pneumonia’.

4.2.5 Examples for Preferred bindings

The choice of code with a Preferred binding is considerably simpler than for an Extensional binding, because the Preferred binding is a suggestion from the developers of the resource or profile about which codes they believe would be best to use to represent this data. However, in a particular instance you are free to choose to follow that suggestion or not, depending on your particular desires and needs, and there are no specific conformance expectations regarding that choice.

So in this case we have a Condition.code and the applicable profile binds the code to the value set http://hl7.org/fhir/ValueSet/condition-code with a Preferred binding:

4.2.5.1 Condition.code with Preferred binding

{
  "path": "Condition.code",
  "definition" : "Identification of the condition, problem or diagnosis."
  "binding": {
    "strength": "preferred",
    "valueSetCanonical": "http://hl7.org/fhir/ValueSet/condition-code"
  }
}

With the Preferred binding all of the following instances (and many other possibilities) are valid instances of the Condition resource:

4.2.5.2 Condition instance #5

{
  "resourceType": "Condition",
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "39065001",
        "display": "Burn of ear"
      }
    ],
    "text": "Burnt Ear"
  },
  "subject": {
    "reference": "Patient/example"
  }
}

4.2.5.3 Condition instance #6

{
  "resourceType": "Condition",
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "312824007",
        "display": "Family history of cancer of colon"
      }
    ]
  },
  "subject": {
    "reference": "Patient/example"
  }
}

4.2.5.4 Condition instance #7

{
  "resourceType": "Condition",
  "code": {
    "coding": [
      {
        "system": "http://my-local-organization.com",
        "code": "XYZ123",
        "display": "Severe pneumococcal pneumonia"
      }
    ]
  },
  "subject": {
    "reference": "Patient/example"
  }
}

4.2.5.5 Condition instance #8

{
  "resourceType": "Condition",
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "233607000",
        "display": "Pneumococcal pneumonia"
      },
      {
        "system": "http://my-local-organization.com",
        "code": "XYZ123",
        "display": "Severe pneumococcal pneumonia"
      }
    ]
  },
  "subject": {
    "reference": "Patient/example"
  }
}

4.2.6 Examples for Example bindings

There are many elements defined in the FHIR specification for which there is no agreement in the HL7 community about what codes should be used. Usually, the lack of agreement is due to disagreement between jurisdictions, and lack of economic incentive to standardise the element. In these cases, the FHIR specification provides a few illustrative codes, but there is no attempt to ensure that these provide good coverage of the problem space, or that they are carefully defined, and implementers SHOULD NOT assume that the codes are production ready. Instead, implementers should look in applicable implementation guides or guidance, or use or create their own codes for us.

Some examples of example bindings in this specification: