Skip to main content

Terminology

Use these functions to expand ValueSets, check terminology membership, and translate codes and Codings.

Terminology references are always resolved inside the FHIR package context and FHIR server configuration available in the environment where FUME is running. Translation helpers can use a configured FHIR server; ValueSet helpers use the configured FHIR package context.

Identifier forms​

Terminology helpers accept three identifier forms for both ValueSet and ConceptMap lookup:

  • canonical URL
  • resource id
  • resource name

Canonical URL is the FHIR-preferred form and is usually the best choice when you want the most explicit authored expression. FUME also supports id and name because they are often shorter and easier to read in controlled package or server contexts.

Every identifier form, including canonical URL, is resolved against the configured FHIR server and package context rather than against the global internet. That means uniqueness is contextual, not guaranteed by identifier type alone. If a helper accepts packageFilter or sourcePackage, use it when you need package-scoped deterministic resolution.

The terminology examples in this section intentionally mix URL, id, and name forms so you can see all supported lookup styles in realistic expressions.

ConceptMap resolution​

$translate(), $translateCode(), and $translateCoding() resolve ConceptMap resources this way when you pass a string identifier:

  1. If a FHIR server is configured and no packageFilter is supplied, FUME tries the server first.
  2. If server resolution does not succeed, FUME falls back to FHIR packages.
  3. If packageFilter is supplied, FUME skips server resolution and uses packages only.

Within package resolution, FUME tries canonical URL first, then resource id, then resource name.

ValueSet resolution​

$expandValueSet() and $inValueSet() resolve ValueSet resources from FHIR packages.

Within package resolution, FUME tries canonical URL first, then resource id, then resource name. sourcePackage narrows package resolution; it does not redirect ValueSet lookup to the server.

Authoring guidance​

Canonical URL is preferred by the FHIR specification, but id and name are often more readable in authored expressions when you control the package or server context.

Do not add FHIR-specific system fields to proprietary payloads just to make terminology helpers work. If a primitive code lookup needs extra disambiguation, provide that context in the expression rather than mutating the input payload. When a FHIR payload already carries Coding.system, prefer reading it from the source payload instead of hard-coding it again.

When these docs use HL7 core terminology assets, the example note links to the verified FHIR R4 presentation page for that asset rather than to the canonical URL. That keeps the linked documentation on the same FHIR version used by the examples.

Functions

5 primary matchs in this category.

Primary matches

Start here when this is the main kind of work you need to do.