A number of HL7 affiliates or associates would like to make terminology content that they own and manage available to the FHIR validation and IG publication system. Such requests might come from:
- HL7 affiliates
- national services such as VSAC or Australia's NCTS
- other SDOs such as DICOM, IHE
- design services such as simplifier
- business such as IMO
In principle, terminology content (CodeSystems, ValueSets, and ConceptMaps) can be made available to the FHIR ecosystem in the following ways:
- publish the terminology through HL7 - this means, make a change request through the UTG system to get the content published on http://terminology.hl7.org. Content published through terminology.hl7.org is available across the entire ecosystem automatically - users don't need to do anything for that
- publish a package containing the value set and code system definitions into the FHIR NPM package system. Users reference the package, and all the content is automatically available when they do. To publish a package to the FHIR ecosystem, either:
- register the package in an RSS feed listed in https://github.com/FHIR/ig-registry/blob/master/package-feeds.json
- author a project on simplifier and publish it
- Provide a terminology server, and declare it's availability to the FHIR tools. Content hosted on these terminology servers will automatically be available to all users in the FHIR eco-system. Note that these servers can require user tokens to protect their content (see below)
- Ask one of the maintainers of tx.fhir.org to make your content available directly by some other means (currently: grahame@hl7.org)
The rest of this page documents the third option: providing a terminology server for the wider use of the FHIR community.
Providing a terminology server for the FHIR ecosystem
Services made available to the FHIR community in this way are only intended to be used for design time tooling, not operational health services. Whatever SLA they are made available under can and should exclude use for supportin operational health services.
Requirements for the service
The service must host a FHIR terminology service. At least R4 or R5 must be supported. It's server discretion whether to support R3, or R5. The validator and IG publisher will happily interoperate with either an R4 or R5 server irrespective of the version it's working with. Choose R5 if the new features on ConceptMap are compelling.
The service must support:
- metadata?mode=terminology
- read on CodeSystem, ValueSet, and ConceptMap
- search on CodeSystem, ValueSet, and ConceptMap by canonical URL
- $expand, $validate-code, $lookup (if code systems are hosted), and $translate (if ConceptMaps are hosted). $subsumes is highly recommended but not required
- support for $validate-code in a batch (potentially very large number)
Services may provide operation support for implicit value sets and code systems that are not available through read/search
Content rules:
- All CodeSystems, ValueSets, and ConceptMaps must be have an associated URL at which a user with a browser can read the definition of the artifact. This should be a human readable web page that describes the artifact of the type that FHIR implementation guides provide (note that the specific presentation used by the IG guides is not required). The page must include a link/method for the user to download the raw definition of the resource. This URL must known for each resource. If it is not algorithmically determined (see below), then it must be specifically identified in the Resource when the resource is accessed (see below).
- The service is assumed to be the source of truth and trusted expansions for terminology artifacts as defined by the registry (todo: provide link), but it can use the trusted-expansion-source to indicate another service that is the trusted-expansion-source but this will be ignored by FHIR tools unless it's also a registered server
Operation Rules:
| Operation | Requirements |
|---|---|
metadata?mode=terminology |
|
| $expand | see https://github.com/FHIR/fhir-test-cases/blob/master/tx/requirements.md for details |
| $validate-code | |
| $translate | to be determined at this point |
Authentication:
The service may require users to authenticate. If the service requires authentication, it must be in the form of basic authentication (username/password) or an authentication header - usually a bearer token - that the user can determine in advance, and then provide to their FHIR tooling in their FHIR Tool Settings File. It is assumed that the service will have some mechanism to provide these tokens to appropriate authorised users (which might be anyone who accepts the required license, or any users with appropriate citizenship or business relationship with the entity that provides the service).
Note that there must be an arrangement for FHIR tool smiths to get a token that grants access to the service without cost in order to test their support of the these services.
Registering the service
Such services are registered following discussion with the FHIR Product Director (grahame@hl7.org) which will also include discussion on the tooling channel on chat.fhir.org.
This is to be described... (a registry of registries)
27 Comments
Josh Mandel
Resource.meta.source doesn't seem like the clearest element for identifying the web page associated with a terminology artifact. It's also a single cardinality element that is overloaded to meet different requirements and different use cases, including things like data import, leading to conflicts -- and here in particular, The narrative of page where somebody can view a terminology does not seem to be in any obvious way the "source" of the fhir resource. I might suggest a dedicated extension for "see it on the web at".
Grahame Grieve
I agree but that already is being used for this purpose in the system (simplifier packages). So changing it isn't easy
Rob McClure
I think we need an extension that is clearly used for "here is the FHIR content" and one that is "here is the browsable view." I'm not sure that trusted source (and we need to make this a single consistent extension for both code system and value sets, perhaps more?) is the right element for "here is the resource" but a server should have an element it can populate for "here is the browsable view on my server."
Josh Mandel
Has there been discussion about supporting the bulk export of terminology resources as a server requirement or a nice to have? I think it would be extremely useful.
Grahame Grieve
Probably useful, but not required for this particular usage
Josh Mandel
It would be very helpful if tools offered a way for local users to override or augment the set of configured servers, just like they can override the default server. That would allow authors to point to a local server or an internal organization server for certain canonical URL patterns, which is a very powerful kind of flexibility that takes advantage of all this infrastructure without the centralized control.
Grahame Grieve
well, tools can already do that now, but it would be intelligent for them to follow this same pattern when doing so
Michael Lawley
Regarding:
> A parameter 'cause' must be returned with the value 'unknown' if validation failed because a value set / code system could not be found
We return a 404 if any of the resources required to complete validation can not be found. Is this a viable (better) alternative?
Peter Jordan
Why not an Operation Outcome Resource with issue.code = "not-found", which is a friendlier equivalent of a 404 response?
Grahame Grieve
that would be a discussion for the terminology stream. My take is 404 = the operation wasn't found. 200 ok with result = false is success for the operation
Michael Lawley
But result=false says that the code is invalid; we don't know that.
404 says that we cannot find the answer (which is actually the case) - State is unknown and thus cannot return a Representation.
If a 200 is the desired response, then I'd suggest that result be 0..1 (or not be boolean).
Pieter Edelman
It might be useful to add that the server should be able to handle all operations in batch mode as well.
tx.fhir.org supports the valueSet parameter on ValueSet/$validate-code, which the FHIR Validator seems to use (correct me if I'm wrong). Shouldn't support for this parameter be required as well?
Grahame Grieve
yes, I'll add that - it does use it. That part is incomplete
Peter Jordan
Content Rules...
a. I would suggest that the mandate for human-readable, IG-like web pages might be better handled by a dedicated FHIR IG for the Terminology Service or a National Base IG. That might also be preferable to requiring that R4 Servers implement metadata?mode=terminology which boils down to support for a resource that's at Maturity Level 0.
b. "The service is assumed to be the source of truth and trusted expansions for terminology artifacts"... that may not always be feasible if Terminology Servers used by EHR/EMR/PHR systems are out of scope. Perhaps it might be better to say a "source of truth and trusted expansions?
Grahame Grieve
I don't understand either of these.
a. I would of course recommend that there be a FHIR IG, but there doesn't have to be - just some way to get a human readable page. It's not related to the mode=terminology, which is the only way to find out what code systems a server actually supports
b. operational tx servers aren't going to be in this picture. And it's not that there's no other servers can be trusted, just in the absence of any statement to the contrary, the servers are assumed to be trusted
Peter Jordan
a. Well, on Terminz, at least, [base]/CodeSystem is the best way to find out which code systems are supported. Also, much depends on the degree of human readability that you require.
b. I'm not sure that a mere assumption is helpful.
Grahame Grieve
it's not a mere assumption, it's stated here as an agreement in advance. And not all the code systems that a server supports are declared through the CodeSystem end-point.
Peter Jordan
It would be a surprise to me to see code systems that are not declared via the CodeSystem end-point to be declared in TerminologyCapabilities...although, as they say, life can be full of surprises, and I'd be interested to know a use case for that.
Grahame Grieve
This is the use case for it - knowing that they're supported even if they're not explicit. SNOMED, RxNorm, UCUM, all the little internet terminologies... tx.fhir.org supports them all, but doesn't have code system resources for them
Peter Jordan
OK - looking at https://tx.fhir.org/r4/metadata?mode=terminology I see a large collection of codeSystem uris. What's the expected mechanism for ensuring that they are all represented by a human-readable page for those that aren't also represented by CodeSystem resources?
Grahame Grieve
I don't know.
Pieter Edelman
I've noticed different responses from different terminology servers regarding display checks. tx.fhir.org seems to return result=true with an additional warning if the display string doesn't match, while the Dutch Nationale Terminologieserver (Ontoserver) returns result=false. Is this behavior something that you want to define here as well?
Peter Jordan
Discussion of this topic, with regard to SNOMED CT here.
Michael Lawley
Our reasoning for Ontoserver's behaviour was as follows:
Hence, we took the position that a client who supplies a value for display in the $validate-code call cares whether it's valid or not, and thus we need to report that in an unambiguous way → result=false
Grahame Grieve
we might want to define that somewhere, but not here
Bryn Rhodes
What is "default-to-latest-version", I don't see it as a parameter in the R4 spec or the current build?
Grahame Grieve
not yet documented - nwly emergent issue based on recent implementation work - see https://chat.fhir.org/#narrow/stream/179202-terminology/topic/Parameters.20to.20.24validate-code