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_621D88E6["Service: Terminology Service"]
  nValidateValueSetCode_2E2BA8B0["Command: ValidateValueSetCode"] -->|handled by| nTerminologyService_621D88E6
  nValidateCodeSystemCode_15D077E8["Command: ValidateCodeSystemCode"] -->|handled by| nTerminologyService_621D88E6
  subgraph nCompliance_DBAE25D_domain["Domain: Compliance"]
    nValidateCodeSystemCode_15D077E8
    nValidateValueSetCode_2E2BA8B0
  end
  subgraph nKnowledgeArtifactManagement_308AC1BE_domain["Domain: Knowledge Artifact Management"]
    nTerminologyService_621D88E6
  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/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.

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_621D88E6["Service: Terminology Service"]
  nValidateValueSetCode_2E2BA8B0["Command: ValidateValueSetCode"] -->|handled by| nTerminologyService_621D88E6
  nValidateCodeSystemCode_15D077E8["Command: ValidateCodeSystemCode"] -->|handled by| nTerminologyService_621D88E6
  subgraph nCompliance_DBAE25D_domain["Domain: Compliance"]
    nValidateCodeSystemCode_15D077E8
    nValidateValueSetCode_2E2BA8B0
  end
  subgraph nKnowledgeArtifactManagement_308AC1BE_domain["Domain: Knowledge Artifact Management"]
    nTerminologyService_621D88E6
  end