Skip to main content

​
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/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

ParameterTypeRequiredDescription
urluriNoImplicit ValueSet URL to check support for. Omit to request an empty Bundle (OMOPHub does not enumerate every possible implicit ValueSet).

​
Supported URL patterns

PatternMeaning
{system}?fhir_vsAll 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.
HTTPIssue CodeCause
401loginMissing or invalid API key

​
See Also