Replies: 3 comments 2 replies
-
|
@smunini, Beautifully designed and constructed, and a much-awaited feature. As far as I understand, postcoordinated expressions are user-created and require a separate expression repository to store them. I think the correct way to create them would be to use some NLP tool to extract these expressions from medical text, validate them, and then store them. For V1, I think it should be deferred. Pre-expansion target of 10,000 is very generous. I think we can consider even lesser because most of the value sets are usually finite and small, or extremely big (SNOMED CT, LOINC etc). Some of the big value sets in FHIR actually reference SNOMED or LOINC, Jurisdiction ValueSet when expanded is around 3500. A controlled import pipeline is always better than giving write API (problems with versioning etc.), custom ValueSets should also follow import path. Most of the major terminologies are shared like SNOMED CT, LOINC, ICD-10, CVX, and RX-NORM, So there is a strong point for having a shared terminology server. However, we must also note that in any implementation for an organization, there would be a huge number of custom ValueSets, because there are a large number of ValueSets which are “example” in the FHIR specification. And these custom ValueSets would be specific to a tenant, so some tenant isolation should be there. |
Beta Was this translation helpful? Give feedback.
-
|
@sandhums - always super thoughtful comments. Thank you! We have started some initial work on HTS in this branch - still very much a work in progress.
This is a big tradeoff in the terminology space - One that is called the TermInfo problem. What are Postcoordinated Expressions?In SNOMED CT, every concept has a precoordinated code - a single atomic concept like The example from Open Question #1 above: This means: Cellulitis ( These are valid FHIR
This is a significant and complex feature - it's essentially a mini-reasoner on top of the ontology. Totally agree this is something we should work in the future.
Good point. We will make this a configuration option, and take your 3500 suggestion as the default.
Agreed. Custom CodeSystems and ValueSets belong in source-controlled distribution files that flow through the same import path as SNOMED CT and LOINC, that way version history, re-import, and dependency tracking all work uniformly. I do wonder if anyone has encountered a use case where one would need to dynamically write to a FHIR server - only when authoring CodeSystems and ValueSets perhaps, but we are not creating an authoring tool for now. Would be interested to hear if anyone else has other ideas on this.
Good point. The question is really about which resources get routed through the tenant-isolated path vs. the shared path, and how the resolution order works when a tenant's query hits a code system that isn't in their tenant space but is in shared storage. I need to think about this a bit more. The architecture supports can support it, but I'm wondering when an installation might use tenants heavily that way. Really appreciate the engagement. Thanks! |
Beta Was this translation helpful? Give feedback.
-
Beta Was this translation helpful? Give feedback.
-
|
@smunini I have been working on validation - Bindings, Invariants and Profile Validation |
Beta Was this translation helpful? Give feedback.
-
|
@sandhums :-) I'd love to have a look. Validation is next up on our roadmap. If you fork this project, make your changes in a branch then issue a PR to this project, we can see your code. Relative to validation design, I have a specific approach in mind which I need to publish to a separate discussion document, but would love to see what you have so far - it will definitely inform where we go next! |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
Summary
This document proposes the design for the Helios Terminology Service (HTS) - a new standalone binary and crate in the HFS workspace that implements the FHIR Terminology Service specification. HTS provides operations for code lookup, value set expansion, code validation, subsumption testing, and concept map translation - the core services that allow healthcare applications to work with coded data without becoming experts in the underlying terminological principles.
HTS is designed as a pluggable, backend-agnostic system. The initial implementation provides two backend families: relational databases (SQLite and PostgreSQL) using recursive CTEs for hierarchy traversal, and an RDF triplestore backend (Oxigraph) for standards-based semantic reasoning over OWL ontologies like SNOMED CT. SQLite provides zero-config local development, PostgreSQL targets production deployments, and Oxigraph enables SPARQL-based terminology operations for organizations working with ontology-native terminologies.
The crate also provides import tooling for loading terminologies from their native distribution formats - starting with the FHIR-bundled terminology that ships with every FHIR specification release, and extending to external code systems like SNOMED CT, LOINC, RxNorm, and ICD-10.
We are seeking community feedback on the trait design, backend strategy, import architecture, and prioritization before implementation begins.
Table of Contents
Motivation
Every FHIR server needs access to terminology services. When a clinician records a diagnosis using SNOMED CT, when a lab system reports results with LOINC codes, when a pharmacy system translates between RxNorm and NDC - all of these depend on a terminology service that can answer questions like:
http://snomed.info/sct|39065001and needs to confirm it exists and retrieve its display name ("Burn of ear").ActStatuscodes needs the equivalent FHIRcomposition-statusvalues.Terminology is foundational to healthcare interoperability. Without a shared, precise vocabulary, clinical data cannot move safely between systems. Every diagnosis, every lab result, every medication order is anchored to coded concepts drawn from terminologies like SNOMED CT, LOINC, and RxNorm. When those codes are ambiguous, invalid, or untranslatable, patient safety is at risk. A terminology service is not an optional add-on - it is core infrastructure for any healthcare data platform.
Beyond resource validation and search, terminology services are required by the FHIRPath expression language itself. Several FHIRPath functions -
memberOf(),subsumes(),subsumedBy(), andexpand()- are defined to call out to a terminology service at evaluation time. This means that FHIRPath expressions used in StructureDefinition constraints, SearchParameter definitions, and clinical decision support rules cannot be fully evaluated without access to a live terminology service. HFS's existing FHIRPath engine (helios-fhirpath) needs a terminology backend to support these functions.HTS is designed as a standalone service that can run alongside HFS, or independently as a shared terminology server for an entire organization - serving multiple FHIR servers, validators, and clinical applications from a single, authoritative source of terminology data.
Standards Background
The FHIR terminology framework rests on a small number of foundational concepts. Understanding these is essential to understanding the HTS design - and to understanding why terminology data is graph-shaped at its core.
Code Systems
A code system defines a set of concepts, assigns codes to them, and provides formal definitions. Each code system is identified by a URI (e.g.,
http://snomed.info/sctfor SNOMED CT,http://loinc.orgfor LOINC). The combination of system URI + code uniquely identifies a concept across all of healthcare IT.Code systems range from the trivially small (FHIR's
publication-statuswith three codes:draft,active,retired) to the enormously complex (SNOMED CT with over 350,000 active concepts arranged in a polyhierarchical directed acyclic graph).Many code systems define properties on their concepts - metadata like "is this concept abstract?", "what is its parent?", "what component does this lab test measure?". These properties are what make code systems more than flat lookup tables: they encode the relationships between concepts, and those relationships are what powers subsumption testing, hierarchy traversal, and intelligent value set expansion.
Value Sets
A value set specifies a set of codes drawn from one or more code systems that are appropriate for a particular use. Value sets do not define new codes - they select existing codes from code systems.
A value set has two representations:
Definition (compose) - A set of rules describing which codes are included. These rules can be simple ("include these five specific codes") or complex ("include all SNOMED CT concepts that are descendants of 'Clinical finding'").
Expansion - The concrete list of codes that result from evaluating the definition against the current state of the referenced code systems. Expansion is one of the core terminology operations.
The distinction matters because the same value set definition can produce different expansions over time as code systems are updated, and because some value set definitions describe infinite sets that can only be meaningfully evaluated with a filter.
Concept Maps
A concept map defines mappings between concepts in different code systems (or between different versions of the same code system). For example, a concept map might define that FHIR
composition-statuscodepreliminarymaps to HL7 v3ActStatuscodeactive.Each mapping carries a relationship type (equivalent, broader, narrower, related, not-related) that tells the consumer how much confidence to place in the translation.
Why This Is Graph Data
The relationships between concepts - parent/child hierarchies, subsumption, cross-system mappings, property links - form a graph. SNOMED CT is explicitly modeled as a description logic ontology. Even simpler code systems define tree-structured hierarchies.
HTS provides two backend families for working with this graph data. The relational backend uses recursive CTEs to traverse hierarchies - both SQLite and PostgreSQL support
WITH RECURSIVEand handle the scale of SNOMED CT's hierarchy. The Oxigraph triplestore backend represents terminology as RDF triples, enabling SPARQL queries and OWL reasoning - the natural representation for SNOMED CT and other ontology-based terminologies. The trait design also allows future backends (e.g., graph databases with precomputed transitive closures) to be added without changing the operation layer.Design Principles
Standalone binary. HTS ships as a standalone
htsbinary with its own HTTP server, configuration, and storage. This follows the standard FHIR ecosystem pattern where terminology servers are independent services - shareable across multiple FHIR servers, validators, and clinical applications. HFS integrates with HTS over HTTP using standard FHIR terminology operations, the same way FHIRPath terminology functions likememberOf()andsubsumes()are specified to call out to an external terminology service.Use the FHIR model directly.
CodeSystem,ValueSet, andConceptMapresources fromhelios_fhirare the data model. No custom intermediate representation. Import tools parse external formats into FHIR resources; backends store and query FHIR resources; the API serves FHIR resources. This eliminates mapping bugs and ensures any valid FHIR terminology resource can be loaded and served.Backend-agnostic operations. The six mandatory terminology operations (
$lookup,$validate-code,$subsumes,$expand,$validate-codeon ValueSet,$translate) are defined as trait methods. Each backend implements them using its native query capabilities. The caller doesn't know or care whether a subsumption test is running a recursive CTE, a graph traversal, or a SPARQL query.Import as a first-class concern. Terminology data comes from many sources in many formats - FHIR bundles, SNOMED CT RF2 files, LOINC CSV distributions, RxNorm RRF files. HTS provides a pluggable import pipeline that normalizes these into FHIR resources and loads them into the active backend.
Correctness over performance, then optimize. Terminology operations have well-defined semantics in the FHIR specification. The initial implementation prioritizes correctness - passing the HL7 terminology service test suite - over raw performance. Performance optimization (caching expansions, precomputing transitive closures, indexing strategies) follows once correctness is established.
Multi-version code system support. A single HTS instance can host multiple versions of the same code system simultaneously. Version resolution follows FHIR rules: if a request specifies a version, use it; otherwise, use the most recent.
Architecture Overview
Data Model: Core Resources
HTS works with three FHIR resource types, used directly from
helios_fhir:For internal storage and efficient querying, backends decompose these resources into normalized structures.
Relational Schema
The schema has four layers: code system tables (concepts, hierarchies, properties, designations), value set tables (definitions and pre-expanded concepts), concept map tables (normalized mapping groups and targets), and full-text search support.
Code System Tables
conceptstores individual codes. Each concept belongs to one code system version.displayholds the primary display text.sequencepreserves the ordering defined in the code system.concept_linkis a dedicated table for parent-child hierarchy relationships. Unlike storing hierarchies as generic concept properties, a dedicated link table avoids a three-way join throughconcept_property+code_system_propertyon every hierarchy traversal. Therel_typecolumn supportsis-a(and potentiallypart-of,classified-within the future). This pattern has proven itself at scale with SNOMED CT's 350,000+ concept hierarchy.concept_propertystores non-hierarchical properties (status, abstract flag, component, scale type, etc.). Properties that reference other concepts usetarget_id. Properties with values longer than thevaluecolumn limit are stored invalue_bin. Thecode_systemanddisplaycolumns support CODING-typed properties.concept_designationstores alternate display names, translations, and use-context-specific labels. This is essential for multi-language support and for the$lookupoperation'sdesignationreturn parameter. SNOMED CT has fully specified names, preferred terms, and synonyms per language. LOINC has long common names, short names, and consumer names. Without a dedicated designations table,$lookupand$expandwithincludeDesignations=truecannot return complete results.CodeSystem Supplements
FHIR supports CodeSystem supplements - a way to add properties or designations to an existing code system without modifying it. A supplement is a CodeSystem resource with
content: supplementand asupplementscanonical URL pointing to the base code system.HTS stores supplement data in the same
concept_propertyandconcept_designationtables as the base code system, with asupplement_idforeign key that identifies which supplement contributed each row. When$lookupreturns properties and designations, it merges results from the base code system and all active supplements. This means loading a Spanish language supplement for SNOMED CT adds rows toconcept_designationwithlanguage: "es"andsupplement_idpointing to the supplement'scode_systemrow - the base SNOMED CT concepts are not modified.Value Set Tables
The key insight here is pre-expansion. Value set definitions (
contentas JSONB) describe rules for which codes are included. Evaluating those rules on every$validate-codecall - potentially traversing SNOMED CT hierarchies in real time - is prohibitively expensive. Instead, a background scheduler materializes the expansion intovs_conceptrows.expansion_statustracks the lifecycle:not_expanded->expansion_in_progress->expanded(orfailedortoo_costly). A background task picks up value sets innot_expandedstate, evaluates their compose rules against loaded code systems, and inserts the resulting concepts intovs_concept. Once expanded,$validate-codeis a simple indexed lookup rather than a recursive hierarchy traversal.Too-costly threshold. Some value sets expand to enormous sizes - "all SNOMED CT clinical findings" is 100,000+ concepts, and "all of SNOMED CT" is 350,000+. Pre-expanding these is not viable. HTS uses a configurable threshold (
HTS_MAX_EXPANSION_SIZE, default 10,000). During pre-expansion, if the concept count exceeds this threshold, the value set is markedtoo_costlyand is not materialized. At query time,$expandon atoo_costlyvalue set requires afilterparameter (text search) to constrain results to a manageable size, or returns anOperationOutcomewith thetoo-costlyerror code.$validate-codeon atoo_costlyvalue set falls back to evaluating compose rules in real time against theconceptandconcept_linktables.Dependency tracking. When a code system is updated (new version loaded), value sets that reference it must be re-expanded. HTS maintains a dependency graph - each
vs_conceptrow is linked to the code system version it was expanded from. When a code system version changes, all dependent value sets are marked back tonot_expandedfor re-expansion by the background task.Concept Map Tables
The
$translateoperation needs to efficiently answer: "given source system X, code Y, and target system Z, find all mappings." Storing ConceptMaps only as JSONB blobs would require deserializing and scanning the full resource on every translate call. The normalized structure enables indexed lookups: queryconcept_map_elementbysource_code, join throughconcept_map_groupto filter by source/target system, and return matchingconcept_map_targetrows with theirrelationshiptype (equivalent, broader, narrower, related, not-related).All data is stored in normalized tables. Resource READ interactions (
GET /ConceptMap/[id]) reconstruct the FHIR resource from the normalized tables rather than storing a redundant JSONB copy. This eliminates double-storage and consistency concerns.Full-Text Search
The
$expandoperation'sfilterparameter requires full-text search over concept display names (e.g., a user types "diab" and gets back "Diabetes mellitus", "Diabetic retinopathy", etc.). HTS supports three full-text search strategies, mirroring HFS's composite storage pattern:to_tsvector('english', display)with GIN index; queried viato_tsqueryconcept_ftstable backed by FTS5; queried viaMATCHdisplayas an analyzed text field; queried via ES match/prefix queriesThe Elasticsearch option follows the same composite pattern used in HFS - the relational database remains the source of truth for CRUD, while Elasticsearch handles text search. This is particularly valuable for large terminologies like SNOMED CT where full-text search over 350,000+ display strings benefits from a dedicated search engine with relevance scoring, synonym support, and language-specific analyzers.
Unique Constraints and Indexes
Unique constraints:
code_system: unique on(url, version)concept: unique on(system_id, code)code_system_property: unique on(system_id, code)value_set: unique on(url, version)concept_map: unique on(url, version)vs_concept: unique on(valueset_id, system_url, code)Key indexes:
concept_link: indexes onparent_idandchild_idfor bidirectional traversalconcept_map_element: index onsource_codefor$translatelookupsconcept_map_target: index ontarget_codefor reverse translationvs_concept: index on(system_url, code)for fast$validate-codeTrait Design: Composable Sub-Traits
Rather than a single monolithic trait, HTS defines composable sub-traits that backends can implement incrementally. This mirrors HFS's progressive trait hierarchy in
helios-persistence(ResourceStorage->VersionedStorage->SearchProvider-> ...).Resource CRUD is handled by reusing
ResourceStoragefrom thehelios-persistencecrate directly - no need to reinvent storage for CodeSystem, ValueSet, and ConceptMap resources. The terminology-specific traits layer operations on top.Design Notes
Composable sub-traits. A backend can implement
CodeSystemOperationsalone for an MVP that only supports$lookup,$validate-code, and$subsumes. ValueSet and ConceptMap operations can be added incrementally. TheTerminologyBackendsupertrait is a convenience - it's just the composition of all sub-traits.ResourceStoragereuse. Resource CRUD (storing and retrieving CodeSystem, ValueSet, ConceptMap resources) reuses theResourceStoragetrait fromhelios-persistence. This means HTS gets SQLite and PostgreSQL storage for free, including tenant isolation viaTenantContext, versioned reads, and batch operations. No need to reinvent the storage layer.Fallible operations. Unlike the audit
AuditSink(which is fire-and-forget), terminology operations must return errors to callers. A failed$expandshould produce a FHIROperationOutcomewith an appropriate error code (includingtoo-costly), not silently return empty results.$expandreturns aValueSet. Per the FHIR specification, the expansion operation returns aValueSetresource with itsexpansionelement populated. This is the FHIR model directly - no intermediate representation.Separate
validate_code_in_systemandvalidate_code_in_value_set. These are distinct FHIR operations (CodeSystem/$validate-codevsValueSet/$validate-code) with different semantics. The CodeSystem variant checks if a code exists in the system. The ValueSet variant evaluates whether a code matches the value set's compose rules, which may involve multiple code systems and complex filter logic.$closureon ConceptMapOperations. The FHIR$closureoperation maintains a client-side transitive closure table as a ConceptMap. CDS systems use this to efficiently test subsumption locally without repeated server calls. The server maintains a named closure table and incrementally adds subsumption relationships as new concepts are submitted.Backend Implementations
Relational Backend (SQLite / PostgreSQL)
The relational backend stores terminology data in the normalized table schema described above. It is the default backend - zero-config with SQLite, production-ready with PostgreSQL.
Hierarchy traversal uses recursive Common Table Expressions (CTEs) over the dedicated
concept_linktable. Because hierarchy links are stored as direct foreign keys rather than generic properties, the recursive query is a simple two-table join:The underlying SQL for ancestor checking uses
concept_linkdirectly - no intermediate property table lookup required:Value set expansion iterates over each
compose.includeentry, querying theconcepttable with any specified filters. For hierarchicalis-afilters, it uses a descendant CTE overconcept_link:Value set validation benefits from pre-expansion. Once a value set has been expanded by the background scheduler,
$validate-codeis a simple indexed lookup rather than a real-time hierarchy traversal:If the value set is not yet expanded (or expansion failed), the backend falls back to evaluating the compose rules in real time.
Triplestore Backend (Oxigraph)
Oxigraph is an embedded RDF triplestore and SPARQL engine written in Rust. It is a natural fit for terminology data that is natively defined as ontologies - FHIR now ships with an OWL representation, and SNOMED CT has a well-defined OWL distribution.
Example SPARQL queries for terminology operations:
The Oxigraph backend is particularly powerful for:
Terminologies without native OWL representations (LOINC, RxNorm, ICD-10, etc.) can either be converted to RDF during import or fall back to the relational backend. HTS can run both backends simultaneously - Oxigraph for ontology-native code systems and relational for everything else.
Future Backends
The composable trait design allows additional backends to be added without changing the operation layer. A potential future backend is an in-memory graph database with precomputed transitive closures, providing O(1) subsumption testing at the cost of higher memory usage.
Terminology Operations
The FHIR Terminology Service specification mandates six operations. Here's how they map to the
TerminologyBackendtrait and what each does:CodeSystem/$lookupGiven a code and system, returns the display name, designations, and properties.
Returns:
{ "resourceType": "Parameters", "parameter": [ { "name": "name", "valueString": "LOINC" }, { "name": "version", "valueString": "2.56" }, { "name": "display", "valueString": "Bicarbonate [Moles/volume] in Serum or Plasma" } ] }CodeSystem/$validate-codeChecks whether a code exists in a code system, and optionally validates the display text.
CodeSystem/$subsumesTests the hierarchical relationship between two codes.
Returns
"subsumes"- "Disorder of liver" subsumes "Viral hepatitis".ValueSet/$expandExpands a value set definition into its concrete list of codes. Supports text filtering for typeahead and paging for large expansions.
ValueSet/$validate-codeChecks whether a code is a member of a value set, evaluating the compose rules against loaded code systems.
ConceptMap/$translateTranslates a code from one system to another using a concept map.
ConceptMap/$closureMaintains a named closure table - a ConceptMap representing the transitive closure of subsumption relationships for a set of concepts. CDS systems use this to build a local lookup table so they can test subsumption without repeated server calls. The client submits new concepts incrementally, and the server returns the updated closure.
All seven operations also support POST with
Parametersresources for complex inputs, and batch invocation via FHIR Bundles.Import Architecture
Terminology data comes from many sources in many formats. HTS provides a pluggable import pipeline with a common trait:
Planned Importers
Loading FHIR-Bundled Terminology
Every FHIR specification release includes a downloadable package containing all the CodeSystem, ValueSet, and ConceptMap resources defined by the specification itself. This is the natural starting point for bootstrapping a terminology server - it provides the "FHIR vocabulary" that every FHIR implementation needs.
What's in the FHIR Package
The FHIR R4 specification download includes:
~300+ CodeSystem resources - These define the code systems used internally by FHIR (e.g.,
http://hl7.org/fhir/administrative-gender,http://hl7.org/fhir/observation-status,http://hl7.org/fhir/composition-status). Most are small (3–50 codes). These are the code systems behind everyrequiredbinding in the specification.~1,200+ ValueSet resources - These define the value sets bound to elements throughout the specification. They range from simple enumerations (all codes from a single CodeSystem) to complex compositions involving external systems like SNOMED CT.
~100+ ConceptMap resources - These map between FHIR code systems and their HL7 v2/v3 equivalents, and between FHIR status codes and canonical status codes.
Import Flow
The FHIR Bundle importer processes the download as follows:
After importing the FHIR package, the terminology server can immediately answer questions about FHIR's own vocabulary:
This provides the foundation for loading external terminologies. SNOMED CT, LOINC, and RxNorm code systems are referenced by many FHIR value sets - loading the FHIR vocabulary first means the value set definitions are in place, and subsequent terminology imports fill in the referenced code system content.
Re-importing and Version Updates
When a code system that already exists is imported again (same URL + version), HTS uses drop-and-reload semantics: all existing concepts, properties, designations, and hierarchy links for that code system version are deleted, and the new import replaces them entirely. This is simpler and more reliable than diffing and patching, and ensures the imported state exactly matches the source distribution.
After a drop-and-reload, all value sets that depend on the reloaded code system are automatically marked as
not_expanded, triggering re-expansion by the background scheduler.Importing a new version of an existing code system (same URL, different version) creates a new
code_systemrow. Thecurrentflag is updated to point to the most recently imported version, which becomes the default for queries that do not specify a version.RESTful API Surface
The HTS HTTP server exposes the following endpoints, as required by the FHIR Terminology Service specification:
Resource Interactions
/CodeSystem/CodeSystem/[id]/ValueSet/ValueSet/[id]/ConceptMap/ConceptMap/[id]/metadata/metadata?mode=terminology/healthTerminology Operations
/CodeSystem/$lookup/CodeSystem/$validate-code/CodeSystem/$subsumes/ValueSet/$expand/ValueSet/[id]/$expand/ValueSet/$validate-code/ValueSet/[id]/$validate-code/ConceptMap/$translate/ConceptMap/[id]/$translate/ConceptMap/$closureRequired Search Parameters
Per the specification, the following search parameters are supported for all three resource types:
url- Canonical URLversion- Business versionname- Name (computer-friendly)title- Title (human-friendly)status- Publication status (draft,active,retired)Configuration
HTS follows the same environment variable and configuration patterns as HFS:
Environment Variables
HTS_SERVER_PORTHTS_SERVER_HOSTHTS_LOG_LEVELHTS_STORAGE_BACKENDsqlite,postgres,sqlite-es,postgres-es,oxigraphHTS_DATABASE_URLHTS_DATA_DIRHTS_ELASTICSEARCH_NODESHTS_ELASTICSEARCH_INDEX_PREFIXHTS_DEFAULT_FHIR_VERSIONHTS_ENABLE_CORSHTS_CORS_ORIGINSHTS_MAX_EXPANSION_SIZECLI Commands
Integration with HFS
HFS connects to HTS via HTTP, using the standard FHIR terminology operations. This is the standard integration model in the FHIR ecosystem - terminology servers are standalone services that can be shared across multiple FHIR servers, validators, and clinical applications.
# Point HFS at a running HTS instance HFS_TERMINOLOGY_SERVER=http://hts.internal:8090When configured, HFS delegates terminology operations to HTS:
memberOf(),subsumes(),subsumedBy(), andexpand()FHIRPath functions call HTS via$validate-code,$subsumes, and$expandrespectively.ValueSet/$validate-code.If
HFS_TERMINOLOGY_SERVERis not configured, FHIRPath terminology functions return empty results and value set validation is skipped, matching HFS's current behavior.Open Questions
We welcome feedback on the following design decisions. Please comment below or open a linked discussion for deeper dives.
1. SNOMED CT Expression Support
SNOMED CT defines a grammar for post-coordinated expressions (e.g.,
128045006:{363698007=56459004}). These are valid FHIR codes but require expression parsing and evaluation. Should expression support be in scope for the initial release, or deferred?2. Pre-Expansion Scheduling Strategy
The relational schema includes a background pre-expansion model with a
too-costlythreshold. What should the scheduling strategy be? Options include: expand all value sets immediately on import, expand on first access (lazy), or run a periodic background task that picks upnot_expandedvalue sets. A hybrid approach (eager for small value sets, lazy for large ones) is also possible. What's the right default forHTS_MAX_EXPANSION_SIZE? The current proposal is 10,000 concepts.3. Bulk Import Performance Targets
SNOMED CT has ~350,000 active concepts. LOINC has ~100,000. What import time is acceptable? This drives decisions about batch insert strategies, transaction boundaries, and index management during bulk loads (e.g., dropping and rebuilding indexes).
4. Write API
The FHIR Terminology Service specification requires READ and SEARCH but does not mandate CREATE/UPDATE/DELETE for terminology resources. Should HTS expose a write API (for organizations that maintain custom code systems), or should all terminology data flow through the import pipeline?
5. Multi-Tenancy
HFS supports multi-tenancy with tenant isolation at the storage level. Since HTS reuses
ResourceStorage(which takesTenantContext), tenant isolation is architecturally possible. Should HTS support multi-tenancy (each tenant sees different code systems / value sets), or should terminology be a shared resource across all tenants? Most terminology servers treat terminology as shared, but some deployments may need tenant-specific value sets or supplements.6. Supplement Conflict Resolution
When multiple supplements add properties or designations to the same code system, what happens if they conflict? For example, two supplements both define a
displaydesignation in French for the same concept but with different values. Should last-loaded-wins, should supplements have a priority order, or should all values be returned and left to the client to resolve?7. Oxigraph and Non-OWL Terminologies
The Oxigraph backend is a natural fit for SNOMED CT (which has an official OWL distribution) and FHIR's own OWL representation. But many widely-used terminologies (LOINC, RxNorm, ICD-10, CVX, CPT) do not have native OWL representations. Should HTS provide RDF conversion during import for these terminologies, or should Oxigraph only be used for natively-OWL code systems with the relational backend as fallback for everything else? If we convert, what RDF vocabulary should we use (SKOS, custom FHIR RDF, or something else)?
References
helios_fhir::r4::CodeSystemhelios_fhir::r4::ValueSethelios_fhir::r4::ConceptMapBeta Was this translation helpful? Give feedback.
All reactions