# Test CodeSystem subsumption

Canonical page: https://docs.ovok.com/primitives/subsumes-codesystem

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

| Method | Path |
| --- | --- |
| `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 [#get-request]

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

```bash
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 [#post-request]

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

```bash
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`:

```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 [#successful-response]

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

| Response path | Example | Meaning |
| --- | --- | --- |
| `resourceType` | `Parameters` | FHIR wrapper for the operation output. |
| `parameter[name=outcome].valueCode` | `subsumed-by` | Directional 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`](https://hl7.org/fhir/R4/codesystem-operation-subsumes.html).
