> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FHIR CodeSystem/$diff for vocabulary version changes

> Compare OMOP concepts between vocabulary releases with FHIR $diff - detect added, removed, and changed codes across Athena version upgrades.

## Overview

Compares concepts between two OMOP vocabulary releases. Returns counts and details of added and deprecated concepts. This is an OMOPHub-exclusive operation with no FHIR standard equivalent.

## Request

```bash theme={null}
curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$diff?\
from=2025.2&to=2026.1&count=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### With vocabulary filter

```bash theme={null}
curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$diff?\
from=2025.2&to=2026.1&system=http://snomed.info/sct&count=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Parameters

| Parameter | Type    | Required | Description                                                                              |
| --------- | ------- | -------- | ---------------------------------------------------------------------------------------- |
| `from`    | string  | Yes      | Old vocabulary version. Accepts OMOPHub version (`2025.2`) or FHIR ID (`omop-v20250827`) |
| `to`      | string  | Yes      | New vocabulary version. Same formats as `from`                                           |
| `system`  | uri     | No       | Filter to a specific vocabulary                                                          |
| `count`   | integer | No       | Max detail entries per category (default: 100, max: 1000)                                |

## Response

```json theme={null}
{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "from", "valueString": "2025.2" },
    { "name": "to", "valueString": "2026.1" },
    { "name": "total-added", "valueInteger": 1247 },
    { "name": "total-deprecated", "valueInteger": 83 },
    {
      "name": "added",
      "part": [
        { "name": "code", "valueCode": "1234567" },
        { "name": "display", "valueString": "New concept name" },
        {
          "name": "property",
          "part": [
            { "name": "code", "valueCode": "vocabulary-id" },
            { "name": "value", "valueCode": "SNOMED" }
          ]
        }
      ]
    },
    {
      "name": "deprecated",
      "part": [
        { "name": "code", "valueCode": "7654321" },
        { "name": "display", "valueString": "Deprecated concept" },
        {
          "name": "property",
          "part": [
            { "name": "code", "valueCode": "invalid-reason" },
            { "name": "value", "valueCode": "U" }
          ]
        }
      ]
    }
  ]
}
```

## Errors

| HTTP | Issue Code  | Cause                                                   |
| ---- | ----------- | ------------------------------------------------------- |
| 400  | `invalid`   | Missing `from` or `to` parameter, or unknown system URI |
| 404  | `not-found` | Version not found in vocabulary releases                |