Terminology Service

Produces: None

Consumes: Validate ValueSet Code [command], Validate CodeSystem Code [command]

Overview

The Terminology Service provides a focused subset of FHIR Terminology capabilities to other Link Cloud services (primarily the Validation Service):

Hosts read and operation endpoints for ValueSet and CodeSystem resources
Supports $validate-code on both ValueSet and CodeSystem
Supports $expand for ValueSets, with limited support for query parameters. filter, include, exclude, and inactive are not supported.
Publishes a CapabilityStatement at /api/terminology/fhir/metadata

On startup, the service loads configured ValueSets and CodeSystems from the local file system into an in-memory cache; runtime requests operate exclusively against this cache for predictable, fast responses and no external dependencies.

flowchart LR
nTerminologyService_2123EB9E["Service: Terminology Service"]
  nValidateValueSetCode_5A22B5A3["Command: ValidateValueSetCode"] -->|handled by| nTerminologyService_2123EB9E
  nValidateCodeSystemCode_20E1E2AA["Command: ValidateCodeSystemCode"] -->|handled by| nTerminologyService_2123EB9E
  subgraph nCompliance_11EAF98F_domain["Domain: Compliance"]
    nValidateCodeSystemCode_20E1E2AA
    nValidateValueSetCode_5A22B5A3
  end
  subgraph nKnowledgeArtifactManagement_6717624D_domain["Domain: Knowledge Artifact Management"]
    nTerminologyService_2123EB9E
  end

Common Configurations

Custom Configurations

Property Name	Description	Secret?
terminology.path	The path on the local file system where terminology folders and artifacts are located that are loaded into memory when the service starts	No

Notes:

The path should contain one folder per artifact. Each folder must include a JSON file for the FHIR artifact (ValueSet or CodeSystem) and a CSV with codes to load. See repository samples for expected formats.
In a deployed environment, the path should be configured as an Azure App Configuration setting that is mounted as a volume to an Azure Storage Account File Share.
Updates on disk are not auto-watched; call POST /api/terminology/config/$reload-cache (or restart the service) to pick up changes.

Example folder structure:

  /data/terminology/
    /ValueSet-us-core-race/
      ValueSet-us-core-race.json
      ValueSet-us-core-race.csv
    /CodeSystem-iso-3166/
      CodeSystem-iso-3166.json
      CodeSystem-iso-3166.csv

Features and Functionality

In-memory caching: all artifacts and their codes are kept in memory for fast lookups.
ValueSet expansion: expansions are constructed from the cached codes; no external terminology server is contacted.
Code validation: validates membership within CodeSystems/ValueSets loaded into the cache, including optional display matching.

Display Matching

Case Sensitivity: The comparison is case-sensitive

Example: "Test Code" ≠ "test code"

Culture/Locale: Comparison is culture-invariant

No special handling of accents or other cultural variations
Example: "café" ≠ "cafe"

Whitespace Handling: No trimming is performed

Leading and trailing spaces are significant
Example: " Test" ≠ "Test"

Exact Matching: Only exact matches are accepted

No partial or substring matches
Example: "Test Code" ≠ "Test Code (Legacy)"

OpenAPI Operations

POST /api/terminology/config/$reload-cache

Reloads the cache by clearing the existing data and repopulating it using the configured terminology path.

Route Parameters

None

Query Parameters

None

GET /api/terminology/config/code-systems/{id}/codes/{code}

Test/diagnostic endpoint that returns a single code from the cached CodeSystem identified by its resource id (e.g. "v3-ActCode").

Route Parameters

Name	Type	Required?	Description
id		Yes	The CodeSystem resource id.
code		Yes	The code value to look up within the CodeSystem.

Query Parameters

Name	Type	Required?	Description
version		No	Optional CodeSystem version; when omitted the latest cached version is used.

GET /api/terminology/config/value-sets/{id}/codes/{code}

Test/diagnostic endpoint that returns a single member of the cached ValueSet identified by its resource id (e.g. "address-type"), reporting both the status the value set declares for it and the status that will actually be applied.

Route Parameters

Name	Type	Required?	Description
id		Yes	The ValueSet resource id.
code		Yes	The code value to look up within the ValueSet.

Query Parameters

Name	Type	Required?	Description
system		No	Optional code system URI. A value set groups its members by system and may list the same code under more than one; supplying this restricts the search to that system, and omitting it takes the first system that lists the code — the same selection `$validate-code` makes. Supplying a value that sanitizes away to nothing is rejected rather than treated as omitted, since widening the search is not what the caller asked for.
version		No	Optional ValueSet version; when omitted the latest cached version is used.

PUT /api/terminology/config/value-sets/{id}/codes

Replaces the codes of a cached ValueSet with the contents of an uploaded CSV.

Route Parameters

Name	Type	Required?	Description
id		Yes	The ValueSet resource id, e.g. "v3-ActEncounterCode".

Query Parameters

Name	Type	Required?	Description
version		No	The version to replace. Omit for the latest cached version.

PUT /api/terminology/config/code-systems/{id}/codes

Replaces the codes of a cached CodeSystem with the contents of an uploaded CSV.

Route Parameters

Name	Type	Required?	Description
id		Yes	The CodeSystem resource id, e.g. "v3-ActCode".

Query Parameters

Name	Type	Required?	Description
version		No	The version to replace. Omit for the latest cached version.

GET /api/terminology/fhir/ValueSet/{id}

Retrieves a ValueSet resource by its unique identifier.

Route Parameters

Name	Type	Required?	Description
id		Yes	The unique identifier for the ValueSet resource to retrieve.

Query Parameters

None

GET /api/terminology/fhir/ValueSet

Retrieves a collection of ValueSet resources based on the specified query parameters.

Route Parameters

None

Query Parameters

Name	Type	Required?	Description
url		No	The canonical URL of the ValueSet to retrieve, if specified.
_summary		No	An optional parameter indicating if a summary of the ValueSet should be included in the response.

GET /api/terminology/fhir/ValueSet/$expand

Expands a ValueSet resource by its unique identifier or URL.

Route Parameters

Name	Type	Required?	Description
id		Yes	The unique identifier of the ValueSet resource to expand. Can be null if URL is provided.

Query Parameters

Name	Type	Required?	Description
url		No	The URL of the ValueSet resource to expand. Can be null if id is provided.
date		No	The date to use when querying the ValueSet resource. Optional.

GET /api/terminology/fhir/ValueSet/{id}/$expand

Expands a ValueSet resource by its unique identifier or URL.

Route Parameters

Name	Type	Required?	Description
id		Yes	The unique identifier of the ValueSet resource to expand. Can be null if URL is provided.

Query Parameters

Name	Type	Required?	Description
url		No	The URL of the ValueSet resource to expand. Can be null if id is provided.
date		No	The date to use when querying the ValueSet resource. Optional.

GET /api/terminology/fhir/CodeSystem/{id}

Retrieves a CodeSystem resource by its unique identifier.

Route Parameters

Name	Type	Required?	Description
id		Yes	The unique identifier for the CodeSystem resource to retrieve.

Query Parameters

None

GET /api/terminology/fhir/CodeSystem

Retrieves a collection of CodeSystem resources based on the specified query parameters.

Route Parameters

None

Query Parameters

Name	Type	Required?	Description
url		No	The canonical URL of the CodeSystem to retrieve. If provided, retrieves a specific CodeSystem.
_summary		No	An optional parameter to request a summary representation of the CodeSystems. If not specified, full details will be retrieved.

POST /api/terminology/fhir/CodeSystem/$validate-code

Validates a code in a specific CodeSystem, using either the CodeSystem's unique identifier or its URL. Optionally validates its display value as well.

Route Parameters

Name	Type	Required?	Description
id		Yes	The unique identifier of the CodeSystem. Optional if the URL is provided.

Query Parameters

Name	Required?	Description
url	No	The URL of the CodeSystem in which the code should be validated. Optional if the id is provided.
code	No	The code to validate. This parameter is required.
display	No	An optional display value to validate against the code.

POST /api/terminology/fhir/CodeSystem/{id}/$validate-code

Validates a code in a specific CodeSystem, using either the CodeSystem's unique identifier or its URL. Optionally validates its display value as well.

Route Parameters

Name	Type	Required?	Description
id		Yes	The unique identifier of the CodeSystem. Optional if the URL is provided.

Query Parameters

Name	Required?	Description
url	No	The URL of the CodeSystem in which the code should be validated. Optional if the id is provided.
code	No	The code to validate. This parameter is required.
display	No	An optional display value to validate against the code.

GET /api/terminology/fhir/CodeSystem/$lookup

Looks up details for a code in a specific CodeSystem using query parameters.

Route Parameters

Name	Type	Required?	Description
id		Yes

Query Parameters

Name	Type	Required?	Description
system		No
code		No
version		No

POST /api/terminology/fhir/CodeSystem/$lookup

Looks up details for a code in a specific CodeSystem using query/body parameters.

Route Parameters

Name	Type	Required?	Description
id		Yes

Query Parameters

Name	Type	Required?	Description
system		No
code		No
version		No

GET /api/terminology/fhir/CodeSystem/{id}/$lookup

Looks up details for a code in a specific CodeSystem using query parameters.

Route Parameters

Name	Type	Required?	Description
id		Yes

Query Parameters

Name	Type	Required?	Description
system		No
code		No
version		No

POST /api/terminology/fhir/CodeSystem/{id}/$lookup

Looks up details for a code in a specific CodeSystem using query/body parameters.

Route Parameters

Name	Type	Required?	Description
id		Yes

Query Parameters

Name	Type	Required?	Description
system		No
code		No
version		No

POST /api/terminology/fhir/ValueSet/$validate-code

Validates a given code, optionally with its system and display, against a specified ValueSet.

Route Parameters

Name	Type	Required?	Description
id		Yes	The unique identifier of the ValueSet to validate against. This parameter is optional if the URL is provided.

Query Parameters

Name	Required?	Description
url	No	The canonical URL of the ValueSet to validate against. This parameter is optional if the id is provided.
system	No	The system of the code to validate. This parameter is optional.
code	No	The code to validate. This parameter is required.
display	No	The display text associated with the code to validate. This parameter is optional.

POST /api/terminology/fhir/ValueSet/{id}/$validate-code

Validates a given code, optionally with its system and display, against a specified ValueSet.

Route Parameters

Name	Type	Required?	Description
id		Yes	The unique identifier of the ValueSet to validate against. This parameter is optional if the URL is provided.

Query Parameters

Name	Required?	Description
url	No	The canonical URL of the ValueSet to validate against. This parameter is optional if the id is provided.
system	No	The system of the code to validate. This parameter is optional.
code	No	The code to validate. This parameter is required.
display	No	The display text associated with the code to validate. This parameter is optional.

GET /api/terminology/fhir/metadata

Returns the CapabilityStatement describing the functionalities and conformance requirements of the FHIR Terminology server.

Route Parameters

None

Query Parameters

None

GET /api/terminology/info

Route Parameters

None

Query Parameters

None

Relationships

flowchart LR
nTerminologyService_2123EB9E["Service: Terminology Service"]
  nValidateValueSetCode_5A22B5A3["Command: ValidateValueSetCode"] -->|handled by| nTerminologyService_2123EB9E
  nValidateCodeSystemCode_20E1E2AA["Command: ValidateCodeSystemCode"] -->|handled by| nTerminologyService_2123EB9E
  subgraph nCompliance_11EAF98F_domain["Domain: Compliance"]
    nValidateCodeSystemCode_20E1E2AA
    nValidateValueSetCode_5A22B5A3
  end
  subgraph nKnowledgeArtifactManagement_6717624D_domain["Domain: Knowledge Artifact Management"]
    nTerminologyService_2123EB9E
  end