FHIR ValueSet search for OMOP concept sets

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.

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)

{
  "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

​Request

​Parameters

​Supported URL patterns

​Response (supported)

​Response (unknown URL)

​Double percent-encoding tolerance

​Errors

​See Also