FHIR CodeSystem/$diff for vocabulary version changes

const options = {method: 'GET'};

fetch('https://fhir.omophub.com/fhir/{version}/CodeSystem/$diff', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "from", "valueString": "2025.2" },
    { "name": "to", "valueString": "2026.2" },
    { "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" }
          ]
        }
      ]
    }
  ]
}

const options = {method: 'GET'};

fetch('https://fhir.omophub.com/fhir/{version}/CodeSystem/$diff', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "from", "valueString": "2025.2" },
    { "name": "to", "valueString": "2026.2" },
    { "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" }
          ]
        }
      ]
    }
  ]
}

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.

Contract Parameters

string

default:"r4"

string

OMOP vocabulary release; defaults to the active release.

string

Header alternative to vocab_release; the header takes precedence.

FHIR wire version (r4, r4b, r5, or r6).

string

required

Older OMOPHub release or FHIR release ID.

string

required

Newer OMOPHub release or FHIR release ID.

string

Optional vocabulary system filter.

integer

default:"100"

Maximum detail entries per category.

Request

curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$diff?\
from=2025.2&to=2026.2&count=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

With vocabulary filter

curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$diff?\
from=2025.2&to=2026.2&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

Response Fields

string

Always Parameters.

array

Release identifiers, totals, and bounded change details.

string

Parameter category.

string

Compared release on the from and to parameters.

integer

Total change count on total-added and total-deprecated parameters.

array

Changed concept code, display, and property parts on added and deprecated detail parameters.

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "from", "valueString": "2025.2" },
    { "name": "to", "valueString": "2026.2" },
    { "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

​Overview

​Contract Parameters

​Request

​With vocabulary filter

​Parameters

​Response

​Response Fields

​Errors

Overview

Contract Parameters

Request

With vocabulary filter

Parameters

Response

Response Fields

Errors