FHIR CodeSystem search and URI resolution

Overview

Search-type query on CodeSystem. This is the discovery call every FHIR client makes before invoking operations against a specific code system. HAPI FHIR’s RemoteTerminologyServiceValidationSupport.fetchCodeSystem() runs GET /CodeSystem?url=http://loinc.org to decide whether to route code validation through OMOPHub - if the response Bundle is non-empty, HAPI proceeds; if it’s empty, HAPI skips OMOPHub for that system. OMOPHub exposes per-vocabulary CodeSystem stubs with content: "not-present". The stubs are metadata-only; concept data is served via the $lookup, $validate-code, $expand, and $translate operations.

Modes

1. Search by canonical system URI

curl "https://fhir.omophub.com/fhir/r4/CodeSystem?url=http://loinc.org" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns a searchset Bundle with one entry - the LOINC stub.

2. Search by the unified OMOP URL

curl "https://fhir.omophub.com/fhir/r4/CodeSystem?\
url=https://fhir-terminology.ohdsi.org" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns a searchset Bundle with one entry - the full OMOP omnibus CodeSystem (with all property definitions and the current vocabulary release metadata).

3. List all supported CodeSystems

curl "https://fhir.omophub.com/fhir/r4/CodeSystem" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns a searchset Bundle with 21 entries - 20 per-vocabulary stubs plus the unified OMOP CodeSystem. Useful for building UI pickers and for one-shot capability discovery.

4. Search by unknown URI

curl "https://fhir.omophub.com/fhir/r4/CodeSystem?url=http://example.com/unknown" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns an empty Bundle (total: 0), not a 404. This is the FHIR search convention - “no matches found”, not “endpoint not found”.

Parameters

Parameter	Type	Required	Description
`url`	uri	No	Canonical system URI to resolve. Omit to list all supported CodeSystems.

Response (per-vocabulary stub)

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://fhir.omophub.com/fhir/r4/CodeSystem/loinc",
      "resource": {
        "resourceType": "CodeSystem",
        "id": "loinc",
        "url": "http://loinc.org",
        "name": "LOINC",
        "title": "Logical Observation Identifiers Names and Codes",
        "status": "active",
        "experimental": false,
        "publisher": "Regenstrief Institute",
        "description": "Logical Observation Identifiers Names and Codes - served by OMOPHub. Use $lookup and $validate-code operations to query concepts; the full concept list is not served inline (content: not-present).",
        "content": "not-present"
      }
    }
  ]
}

The stub carries metadata only. content: "not-present" is the standard FHIR value for terminology servers that expose concepts via operations rather than inline enumeration. Clients should follow up with

lookup](/api-reference/fhir-terminology/lookup), [

validate-code, or $subsumes using the same canonical URI (http://loinc.org) - the operation handlers dispatch on the FHIR system URI and route to the underlying OMOP vocabulary.

Response (list-all mode)

Same Bundle shape as above, with 21 entries. Each stub has a distinct id (the short slug - loinc, snomed, rxnorm, etc.) and url (the canonical FHIR system URI). The final entry is the unified OMOP CodeSystem (https://fhir-terminology.ohdsi.org) with the release-specific id (e.g. omop-v20250827) and full property definitions.

Stub-to-URI map

See the Supported Vocabularies table in the overview for the authoritative list of id ↔ url pairs.

Errors

HTTP	Issue Code	Cause
401	`login`	Missing or invalid API key

Unknown URIs return an empty Bundle, not an error.

FHIR Terminology Service

FHIR CodeSystem search and URI resolution

Overview

Modes

1. Search by canonical system URI

2. Search by the unified OMOP URL

3. List all supported CodeSystems

4. Search by unknown URI

Parameters

Response (per-vocabulary stub)

Response (list-all mode)

Stub-to-URI map

Errors

See Also

​Overview

​Modes

​1. Search by canonical system URI

​2. Search by the unified OMOP URL

​3. List all supported CodeSystems

​4. Search by unknown URI

​Parameters

​Response (per-vocabulary stub)

​Response (list-all mode)

​Stub-to-URI map

​Errors

​See Also

Overview

Modes

1. Search by canonical system URI

2. Search by the unified OMOP URL

3. List all supported CodeSystems

4. Search by unknown URI

Parameters

Response (per-vocabulary stub)

Response (list-all mode)

Stub-to-URI map

Errors

See Also