Vocabulary Releases

The OMOPHub API supports multiple vocabulary release versions through a sophisticated schema-based versioning system. Each release contains the complete OHDSI vocabulary data for that time period, ensuring data consistency and enabling time-based analysis.

Current Available Releases

The following vocabulary releases are currently available in the system:

Version	Release Date	FHIR CodeSystem ID	Status	Default	Release Notes
2026.1	2026-02-27	`omop-v20260227`	Active	Yes	Link
2025.2	2025-08-27	`omop-v20250827`	Active	No	Link
2025.1	2025-02-27	`omop-v20250227`	Active	No	Link
2024.2	2024-08-30	`omop-v20240830`	Active	No	Link

The FHIR CodeSystem ID column is what you pass to the FHIR Terminology Service for release-pinned instance reads and operations - e.g. GET /fhir/r4/CodeSystem/omop-v20250827 or CodeSystem/omop-v20250827/$lookup?.... FHIR handlers accept both formats interchangeably: the OMOPHub version (2025.2) and the FHIR ID (omop-v20250827). The FHIR ID is computed deterministically from the release date (omop-v + YYYYMMDD).

FHIR Code System URIs

Each vocabulary release is served through both the REST API (by OMOP vocabulary_id) and the FHIR Terminology Service at https://fhir.omophub.com/fhir/{r4,r4b,r5,r6}/ (by canonical FHIR system URI). The mapping below is stable across releases - only the underlying concepts change between versions.

FHIR System URI	OMOP `vocabulary_id`
`http://snomed.info/sct`	`SNOMED`
`http://loinc.org`	`LOINC`
`http://www.nlm.nih.gov/research/umls/rxnorm`	`RxNorm`
`http://hl7.org/fhir/sid/icd-10`	`ICD10`
`http://hl7.org/fhir/sid/icd-10-cm`	`ICD10CM`
`http://hl7.org/fhir/sid/icd-10-pcs`	`ICD10PCS`
`http://hl7.org/fhir/sid/icd-10-cn`	`ICD10CN`
`http://hl7.org/fhir/sid/icd-10-gm`	`ICD10GM`
`http://hl7.org/fhir/sid/icd-9-cm`	`ICD9CM`
`http://hl7.org/fhir/sid/icd-9`	`ICD9Proc`
`http://hl7.org/fhir/sid/icd-9-cn`	`ICD9ProcCN`
`http://hl7.org/fhir/sid/icd-o-3`	`ICDO3`
`http://hl7.org/fhir/sid/cvx`	`CVX`
`http://hl7.org/fhir/sid/ndc`	`NDC`
`http://www.nlm.nih.gov/research/umls/hcpcs`	`HCPCS`
`http://www.whocc.no/atc`	`ATC`
`http://unitsofmeasure.org`	`UCUM`
`urn:iso:std:iso:11073:10101`	`MDC`
`http://fdasis.nlm.nih.gov`	`UNII`
`http://va.gov/terminology/medrt`	`MED-RT`
`https://fhir-terminology.ohdsi.org`	OMOP unified omnibus

Source of truth is apps/api/src/config/fhir-vocabularies.ts. To get the live list from the running service, call GET /fhir/r4/metadata?mode=terminology - the TerminologyCapabilities resource enumerates every supported codeSystem.uri.

Version Abbreviations

For convenience, the API supports several abbreviations for version specification:

Abbreviation	Maps To	Description
`latest`	`2026.1`	Always points to the most recent release
`default`	`2026.1`	Same as latest - the system default
`current`	`2026.1`	Alias for the default version
`2026v1`	`2026.1`	Half-based abbreviation
`2025v2`	`2025.2`	Half-based abbreviation
`2025v1`	`2025.1`	Half-based abbreviation
`2024v2`	`2024.2`	Half-based abbreviation

How to Select Vocabulary Versions

You can specify which vocabulary version to use in your API requests using any of these methods:

Method 1: Query Parameter (Recommended)

Add the vocab_release parameter to any API endpoint:

# Using specific version
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024.1" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Using abbreviation
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024v1" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Using latest (default behavior)
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=latest" \
  -H "Authorization: Bearer YOUR_API_KEY"

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();

// Using specific version
const { data: specific } = await client.search.basic('diabetes', { vocabRelease: '2024.1' });

// Using abbreviation
const { data: abbrev } = await client.search.basic('diabetes', { vocabRelease: '2024v1' });

// Using latest (default — omit vocabRelease)
const { data: latest } = await client.search.basic('diabetes');

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Using specific version
response = requests.get(
    'https://api.omophub.com/v1/concepts/search',
    headers=headers,
    params={
        'query': 'diabetes',
        'vocab_release': '2024.2'
    }
)

# Using abbreviation
response_abbrev = requests.get(
    'https://api.omophub.com/v1/concepts/search',
    headers=headers,
    params={
        'query': 'diabetes',
        'vocab_release': '2024v2'
    }
)

# Using latest (default)
response_latest = requests.get(
    'https://api.omophub.com/v1/concepts/search',
    headers=headers,
    params={
        'query': 'diabetes',
        'vocab_release': 'latest'
    }
)

library(httr)

# Using specific version
response <- GET(
  "https://api.omophub.com/v1/concepts/search",
  add_headers(Authorization = "Bearer YOUR_API_KEY"),
  query = list(
    query = "diabetes",
    vocab_release = "2024.2"
  )
)

# Using abbreviation
response_abbrev <- GET(
  "https://api.omophub.com/v1/concepts/search",
  add_headers(Authorization = "Bearer YOUR_API_KEY"),
  query = list(
    query = "diabetes",
    vocab_release = "2024v2"
  )
)

# Using latest (default)
response_latest <- GET(
  "https://api.omophub.com/v1/concepts/search",
  add_headers(Authorization = "Bearer YOUR_API_KEY"),
  query = list(
    query = "diabetes",
    vocab_release = "latest"
  )
)

Method 2: HTTP Header

Use the X-Vocab-Release header:

curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Vocab-Release: 2024.2"

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();
// Either pass `vocabRelease` per-call (preferred) or set
// `vocabVersion` on the client to inject the `X-Vocab-Version` header.
const { data } = await client.search.basic('diabetes', { vocabRelease: '2024.2' });

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'X-Vocab-Release': '2024.2'
}

response = requests.get(
    'https://api.omophub.com/v1/concepts/search',
    headers=headers,
    params={'query': 'diabetes'}
)

Default Version Behavior

When no version is specified:

Default Version: 2025.2
Fallback: If the default version is unavailable, the system uses the latest available active version
Caching: Responses are cached with version-specific keys to ensure consistency

Version Comparison Example

Here’s how to compare concept availability across versions:

import requests

def compare_concept_across_versions(concept_code, vocabulary_id):
    """Compare a concept across different vocabulary versions."""
    headers = {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
    
    versions = ['2025.2', '2025.1', '2024.2']
    results = {}
    
    for version in versions:
        response = requests.get(
            'https://api.omophub.com/v1/concepts/search',
            headers=headers,
            params={
                'query': concept_code,
                'vocabulary_ids': vocabulary_id,
                'vocab_release': version,
                'page_size': 1
            }
        )
        
        data = response.json()
        if data.get('data'):
            concept = data['data'][0]
            results[version] = {
                'found': True,
                'concept_name': concept['concept_name'],
                'standard_concept': concept.get('standard_concept'),
                'valid_start_date': concept.get('valid_start_date'),
                'valid_end_date': concept.get('valid_end_date')
            }
        else:
            results[version] = {'found': False}
    
    return results

# Example usage
concept_comparison = compare_concept_across_versions('E11.9', 'ICD10CM')
for version, info in concept_comparison.items():
    if info['found']:
        print(f"Version {version}: {info['concept_name']}")
    else:
        print(f"Version {version}: Not found")

import { OMOPHub } from '@omophub/omophub-node';

const client = new OMOPHub();

interface VersionInfo {
  found: boolean;
  conceptName?: string;
  standardConcept?: string | null;
  validStartDate?: string;
  validEndDate?: string;
  error?: string;
}

async function compareConcept(conceptCode: string, vocabularyId: string) {
  const versions = ['2026.1', '2025.2', '2025.1', '2024.2'];
  const results: Record<string, VersionInfo> = {};

  for (const version of versions) {
    const { data, error } = await client.search.basic(conceptCode, {
      vocabularyIds: [vocabularyId],
      vocabRelease: version,
      pageSize: 1,
    });

    if (error) {
      results[version] = { found: false, error: error.message };
    } else if (data && data.length > 0) {
      const concept = data[0];
      results[version] = {
        found: true,
        conceptName: concept.concept_name,
        standardConcept: concept.standard_concept,
        validStartDate: concept.valid_start_date,
        validEndDate: concept.valid_end_date,
      };
    } else {
      results[version] = { found: false };
    }
  }

  return results;
}

// Example usage
const results = await compareConcept('E11.9', 'ICD10CM');
for (const [version, info] of Object.entries(results)) {
  console.log(`Version ${version}: ${info.found ? info.conceptName : 'Not found'}`);
}

Version-Specific Features

Temporal Queries

Query concepts as they existed at specific points in time:

# Get diabetes concepts as they existed in 2024v2
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024.2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Historical Analysis

Compare vocabulary evolution over time:

# Compare concept relationships across versions
curl -X GET "https://api.omophub.com/v1/concepts/123456/relationships?vocab_release=2024.2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Migration Support

Validate concept mappings when upgrading between versions:

# Validate proposed mappings against OMOP standards
curl -X POST "https://api.omophub.com/v1/mappings/validate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mappings":[{"source_concept_id":201826,"target_concept_id":1569178005,"mapping_type":"Maps to"}]}'

Version Support Policy

Active Versions

Current + 2 previous releases are actively supported

Deprecated Versions

Removal notice provided 90 days before discontinuation

Troubleshooting

Common Issues

Version Not Found

{
  "error": "VOCABULARY_VERSION_NOT_FOUND",
  "message": "Vocabulary version '2023.1' is not available",
  "available_versions": ["2026.1", "2025.2", "2025.1", "2024.2"]
}

Solution: Use the /v1/vocabularies/releases endpoint to check available versions.

Version Mismatch in Results

If you receive unexpected results, verify the version is being applied correctly:

# Check which version was actually used
curl -X GET "https://api.omophub.com/v1/concepts/search?query=diabetes&vocab_release=2024.2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -v  # Verbose mode shows response headers

Look for the X-Vocab-Release-Used header in the response to confirm the version.

FAQ

What happens if I don't specify a version?

The system automatically uses the default version (2026.1). This provides the most recent vocabulary data and optimal performance through caching.

Can I use multiple versions in the same request?

No, each API request operates against a single vocabulary version. To compare across versions, make separate requests for each version.

How often are new versions released?

Major vocabulary updates typically occur twice a year (February and August), following the OHDSI vocabulary release cycles.

Getting Started

Integrations

Workflows

Production

Current Available Releases

FHIR Code System URIs

Version Abbreviations

How to Select Vocabulary Versions

Method 1: Query Parameter (Recommended)

Method 2: HTTP Header

Default Version Behavior

Version Comparison Example

Version-Specific Features

Temporal Queries

Historical Analysis

Migration Support

Version Support Policy

Active Versions

Deprecated Versions

Troubleshooting

Common Issues

Version Not Found

Version Mismatch in Results

FAQ

​Current Available Releases

​FHIR Code System URIs

​Version Abbreviations

​How to Select Vocabulary Versions

​Method 1: Query Parameter (Recommended)

​Method 2: HTTP Header

​Default Version Behavior

​Version Comparison Example

​Version-Specific Features

​Temporal Queries

​Historical Analysis

​Migration Support

​Version Support Policy

​Active Versions

​Deprecated Versions

​Troubleshooting

​Common Issues

​Version Not Found

​Version Mismatch in Results

​FAQ

Current Available Releases

FHIR Code System URIs

Version Abbreviations

How to Select Vocabulary Versions

Method 1: Query Parameter (Recommended)

Method 2: HTTP Header

Default Version Behavior

Version Comparison Example

Version-Specific Features

Temporal Queries

Historical Analysis

Migration Support

Version Support Policy

Active Versions

Deprecated Versions

Troubleshooting

Common Issues

Version Not Found

Version Mismatch in Results

FAQ