FHIR ValueSet search for OMOP concept sets

const options = {method: 'GET'};

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

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://fhir.omophub.com/fhir/r4/ValueSet/http---snomed-info-sct-fhir-vs-isa-73211009",
      "resource": {
        "resourceType": "ValueSet",
        "id": "http---snomed-info-sct-fhir-vs-isa-73211009",
        "url": "http://snomed.info/sct?fhir_vs=isa/73211009",
        "status": "active",
        "experimental": false,
        "name": "OMOPHub implicit ValueSet: http://snomed.info/sct?fhir_vs=isa/73211009",
        "description": "Implicit ValueSet backed by the OMOPHub FHIR Terminology Service. Call $expand on this ValueSet to enumerate its members."
      }
    }
  ]
}

const options = {method: 'GET'};

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

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://fhir.omophub.com/fhir/r4/ValueSet/http---snomed-info-sct-fhir-vs-isa-73211009",
      "resource": {
        "resourceType": "ValueSet",
        "id": "http---snomed-info-sct-fhir-vs-isa-73211009",
        "url": "http://snomed.info/sct?fhir_vs=isa/73211009",
        "status": "active",
        "experimental": false,
        "name": "OMOPHub implicit ValueSet: http://snomed.info/sct?fhir_vs=isa/73211009",
        "description": "Implicit ValueSet backed by the OMOPHub FHIR Terminology Service. Call $expand on this ValueSet to enumerate its members."
      }
    }
  ]
}

Overview

Search-type query on ValueSet. FHIR clients - notably HAPI FHIR’s RemoteTerminologyServiceValidationSupport and EHRbase’s FhirTerminologyValidation - call this endpoint as a preflight check: “does this server support the ValueSet I’m about to query?”. If the returned searchset Bundle contains a matching entry, the client proceeds to

expand](/api-reference/fhir-terminology/expand) or [ValueSet/

validate-code. If the Bundle is empty, the client skips OMOPHub entirely for that ValueSet. OMOPHub recognizes the same implicit ValueSet URL patterns that $expand handles - no stored ValueSet definitions required.

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

Implicit ValueSet URL. Omit it to return an empty search Bundle.

Request

curl "https://fhir.omophub.com/fhir/r4/ValueSet?\
url=http://snomed.info/sct?fhir_vs=isa/73211009" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters

Parameter	Type	Required	Description
`url`	uri	No	Implicit ValueSet URL to check support for. Omit to request an empty Bundle (OMOPHub does not enumerate every possible implicit ValueSet).

Supported URL patterns

Pattern	Meaning
`{system}?fhir_vs`	All concepts from a code system
`{system}?fhir_vs=isa/{code}`	Descendants of a specific concept (is-a filter)

Where {system} is any of the supported FHIR system URIs, and {code} is a code within that system.

Response (supported)

Response Fields

string

Always Bundle.

string

Always searchset.

integer

Zero or one.

array

Matching implicit ValueSet stub.

string

Absolute ValueSet URL.

object

ValueSet with resourceType, id, url, status, experimental, name, and description.

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://fhir.omophub.com/fhir/r4/ValueSet/http---snomed-info-sct-fhir-vs-isa-73211009",
      "resource": {
        "resourceType": "ValueSet",
        "id": "http---snomed-info-sct-fhir-vs-isa-73211009",
        "url": "http://snomed.info/sct?fhir_vs=isa/73211009",
        "status": "active",
        "experimental": false,
        "name": "OMOPHub implicit ValueSet: http://snomed.info/sct?fhir_vs=isa/73211009",
        "description": "Implicit ValueSet backed by the OMOPHub FHIR Terminology Service. Call $expand on this ValueSet to enumerate its members."
      }
    }
  ]
}

The returned resource is a metadata stub. It does not include the expansion - callers must invoke $expand to enumerate members.

Response (unknown URL)

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0
}

An empty Bundle (not a 404) is the FHIR convention for “no matches”.

Double percent-encoding tolerance

Spring-based clients (HAPI, EHRbase) sometimes encode the url parameter twice - once for the template or code (terminology://fhir.hl7.org/ValueSet?url=http%3A%2F%2F...) and again when building the outbound HTTP request. OMOPHub detects the second encoding layer automatically and decodes it before parsing the implicit URL. Single-encoded URLs work too.

Errors

Only malformed requests return errors - unknown URLs are handled via the empty-Bundle response.

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

​Overview

​Contract Parameters

​Request

​Parameters

​Supported URL patterns

​Response (supported)

​Response Fields

​Response (unknown URL)

​Double percent-encoding tolerance

​Errors

​See Also

Overview

Contract Parameters

Request

Parameters

Supported URL patterns

Response (supported)

Response Fields

Response (unknown URL)

Double percent-encoding tolerance

Errors

See Also