Test CodeSystem subsumption

Determine the hierarchy relationship between two codes in a CodeSystem.

$subsumes tests whether one code is equivalent to, broader than, narrower than, or unrelated to another code using the CodeSystem's hierarchy semantics.

MethodPath
GET or POST/fhir/R4/CodeSystem/$subsumes

Provide both code A and code B. At the type-level route, also provide the code system. The result is directional: it reports the relationship of A to B.

GET request

This example asks whether the SNOMED CT concept for viral hepatitis (A) is subsumed by disorder of liver (B):

curl --get 'https://api.sandbox.ovok.com/fhir/R4/CodeSystem/$subsumes' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --data-urlencode 'system=http://snomed.info/sct' \
  --data-urlencode 'codeA=3738000' \
  --data-urlencode 'codeB=235856003'

POST request

Use codingA and codingB when each code needs to carry its own system:

curl --request POST \
  --url 'https://api.sandbox.ovok.com/fhir/R4/CodeSystem/$subsumes' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/fhir+json' \
  --data @subsumes-codesystem-parameters.json

Example subsumes-codesystem-parameters.json:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "codingA",
      "valueCoding": {
        "system": "http://snomed.info/sct",
        "code": "3738000"
      }
    },
    {
      "name": "codingB",
      "valueCoding": {
        "system": "http://snomed.info/sct",
        "code": "235856003"
      }
    }
  ]
}

Successful response

The response is a FHIR Parameters resource with an outcome parameter.

Response pathExampleMeaning
resourceTypeParametersFHIR wrapper for the operation output.
parameter[name=outcome].valueCodesubsumed-byDirectional relationship of code A to code B.

outcome has one of four values:

  • equivalent — A and B represent equivalent concepts.
  • subsumes — A is broader than B.
  • subsumed-by — A is narrower than B.
  • not-subsumed — neither concept subsumes the other.

If the server cannot determine a relationship, it returns a FHIR OperationOutcome instead.

Reference: HL7 FHIR R4 CodeSystem $subsumes.

Last updated on

On this page