Stream: terminology
Topic: TerminologyCapabilities
Yunwei Wang (May 02 2018 at 20:47):
When responding metadata request, should a terminology server returns CapabilityStatement or TerminologyCapabilities or both?
Peter Jordan (May 02 2018 at 20:53):
The CapabilityStatement.
Yunwei Wang (May 02 2018 at 20:54):
Then what is the usage of TerminologyCapabilities resource?
I though that is a replacement of CapabilityStatement.
Robert McClure (May 02 2018 at 21:02):
I thought the idea was both
Peter Jordan (May 02 2018 at 21:09):
Every FHIR server is required to provide a CapabilityStatement in response to a metadata request. The TerminologyCapabilities resource is intended to provide additional information specific to Terminology Servers - e.g. which properties are supported for individual Code Systems. Support for the TerminologyCapabilities resource, where applicable, is declared in the Capability Statement. Expecting a Terminology Server to include a TerminologyCapabilities resource in its response to the a metadata request would require a breaking change in the specification.
Robert McClure (May 02 2018 at 21:10):
So you are saying it is an additional request to get the TerminologyCapabilities? What would the request be?
Rob Hausam (May 02 2018 at 21:10):
We've been discussing having an additional metadata endpoint specifically for the terminology service, but haven't made a decision on how to do that yet.
Peter Jordan (May 02 2018 at 21:16):
Same as other resources - GET with optional search parameters. The following request will return the (trial) TerminologyCapabilities resource from my server...
GET http://its.patientsfirst.org.nz/RestService.svc/Terminz/TerminologyCapabilities
Rob Hausam (May 02 2018 at 21:27):
Yes, you can do that with CapabilityStatement (and, as you said, any other resource), too. But 'metadata' is a designated endpoint for retrieving the single instance (in case there is more than one instance on the server) of the CapabilityStatement which declares the capabilities for this server (at that particular base endpoint). I think we likely want a similar "terminology metadata" endpoint for the terminology service (particularly because some servers may provide both general server capabilities and also specific terminology services).
Rob Hausam (May 02 2018 at 21:32):
here is a link to the prior discussion https://chat.fhir.org/#narrow/stream/48-terminology/subject/Accessing.20the.20server.20terminology.20capability.20statement, and to further work to be done for GF#14539
Peter Jordan (May 02 2018 at 21:35):
I guess there's a case for returning all the capabilities of a Terminology Server in a single request - and that would also need include all the OperationDefinition resources where a server doesn't support all the in/out parameters in the specification for a particular operation. On the other hand, given the large and unwieldy nature of what might be returned (particularly from an all-purpose server) there is also merit in continuing the approach where the ConformanceStatement provides references to additional capability and conformance related resources.
Grahame Grieve (May 05 2018 at 04:39):
It has to be possible to ask a server what it's own terminology capabilities are. It must also be possible for a server to host a list of terminology capability statements
Grahame Grieve (May 05 2018 at 04:39):
I lean towards adding an element or extension to the capability statement to refer to the the terminology capabilities rather than adding to the API
Michael Lawley (May 05 2018 at 04:55):
@Peter Jordan wouldn't [base]/TerminologyCapabilities return a Bundle containing all the TerminologyCapabilities stored on the server?
Michael Lawley (May 05 2018 at 05:04):
@Grahame Grieve I agree with @Rob Hausam - it would be very preferable to be able to get to a server's own terminology capabilities statement in a single request rather than having to first get the /metadata (this is already very slow on some systems).
Grahame Grieve (May 05 2018 at 05:11):
well, we won't solve the slowness problem by making it bigger
Peter Jordan (May 05 2018 at 05:29):
@Michael Lawley You're right. Mine currently just sends a single resource, but I'll correct that to place it in a bundle in the next release of my server.
Michael Lawley (May 05 2018 at 05:42):
No, I'd rather have a well-known endpoint like /terminologymetadata or /metadata/terminology or similar.
The alternative (which would make it bigger and which I also dislike) would be to have the terminology capabilities be returned from /metadata as a contained resource
Rob Hausam (May 05 2018 at 12:32):
I think it probably would be best to include a reference (not a contained resource) to the additional terminology (and any other applicable service) capabilities within CapabilityStatement and also provide known endpoint(s) where they are returned directly.
Yunwei Wang (May 06 2018 at 20:13):
why are there more than one TerminologyCapabilities instance on a server? Is that one for each coding system?
Peter Jordan (May 06 2018 at 21:21):
Not sure, but TerminologyCapabilities.codeSystem is 0...* and (interestingly) each codeSystem has a canonical uri element.
David Hay (May 07 2018 at 02:53):
Can you assume that GET [server]/TerminologyCapabilities actually refers to the terminology capabilities of THAT server? It's not the case for CapabilityStatement...
Rob Hausam (May 07 2018 at 03:00):
No, I don't think you can necessarily assume that. If the server supports general REST interactions then the presence of a TerminologyCapabilities resource instance may not indicate that the server supports those capabilities (just as with CapabilityStatement). So, as we've mentioned, I think an explicit endpoint is needed - via a specific dedicated endpoint for terminology capabilities or a reference from 'metadata' or both.
Grahame Grieve (May 07 2018 at 03:49):
a server that is a terminology server would generally only carry a single TerminologyCapabilities resource. But a server that has other purposes - a repository of systems, for instance, or a conformance server - might carry multiple terminology capabilities statements that describe other systems
Lloyd McKenzie (May 07 2018 at 10:26):
I don't think you can rely on that. If you want to know for sure what terminology capabilities a system supports, there needs to be an extension that points from CapabilityStatement to the TerminlogyCapabilities. (And I'm very much not sold on TerminologyCapabilities being a separate resource.)
Yunwei Wang (May 07 2018 at 16:12):
I agree with an extension for TerminologyCapabilities instance either as a reference or as an embedded resource.
Peter Jordan (May 07 2018 at 21:29):
@Lloyd McKenzie Support for the TerminologyCapabilities resource can already be declared in a CapabilityStatement. I don't believe that requiring clients to examine extensions in order to determine what a server can do is a particularly good strategy. Whether, not, the TerminologyCapabilities resource should be merged with CapabilityStatement is a moot point - but probably doesn't satisfy the use case whereby a server may contain multiple instances of the later. However, I believe there is a good argument for adding an operation that returns a bundle containing everything a particular terminology server supports, which would include OperationDefinitions for server-specific implementations of operations such as $expand.
Lloyd McKenzie (May 07 2018 at 21:36):
There are absolutely going to be situations where you'll need to look at extensions in CapabilityStatement - not everything a system can do can be part of core. (We already have extensions on CapabilityStatement for somethings)
Lloyd McKenzie (May 07 2018 at 21:36):
A server can have lots of instances of CapabilityStatement - but it only exposes one at the metadata endpoint, which is what matters here.
Peter Jordan (May 07 2018 at 21:57):
My remarks related to the single CapabilityStatement exposed by the metadata endpoint. IMHO, the TerminologyCapabilities resource is definitely an improvement on the previous use of extensions in the CapabilityStatement to declare support for external Code Systems. We need to make it as clear and simple as possible for clients to determine what a Terminology Server can do: I'm usually asked that question at least several times at each Connectathon and my reply in Cologne will be that 3 separate queries are required.
Lloyd McKenzie (May 07 2018 at 22:12):
I understand the desire to make things simple, but creating a new resource every time a new service comes along can't scale.
Michael Lawley (May 07 2018 at 22:13):
@Peter Jordan what are your three requests?
1. CapabilityStatement - /metadata
2. TerminologyCapabilities - /???
3. OperationDefinition???
Michael Lawley (May 07 2018 at 22:27):
well @Lloyd McKenzie, a "new service that comes along" wouldn't meet the 80% rule, right? How many service types are currently needing something like TerminologyCapabilities? I could posit something for workflow, and something for events/CDS maybe, but otherwise?
Lloyd McKenzie (May 07 2018 at 22:33):
CapabilityStatement is at /metadata. The CapabilityStatement points to relevant OperationDefinitions, StructureDefinitions, SearchParameters, etc. It would need to point to TerminologyCapability too - presumably via an extension. Merely hosting a TerminologyCapability says nothing about what the system can do. (And the TerminologyCapability for a system might not even be hosted by that same system - just as the OperationDefinitions, StructureDefinitions and other resources pointed to by the "metadata" CapabilityStatement of a server don't have to be hosted by that server.
Peter Jordan (May 08 2018 at 13:19):
@Michael Lawley
2. GET [base]/TerminologyCapabilities/Terminz-Example (will also work without the resource id)
3 GET [base]/OperationDefinition will return all the operation definitions on my Server, otherwise they can be requested individually using the URLs in the CapabilityStatement.
Can confirm that the Tsunami of FHIR Services hasn't reached NZ either. Flippancy aside, I do think that terminology services probably form a very distinct module within the FHIR spec, as evidenced by highly specific, product-based implementations.
Grahame Grieve (Oct 31 2018 at 21:07):
The vocab WG needs to make a formal proposal for TerminologyCapabilities resource
Grahame Grieve (Oct 31 2018 at 21:07):
note that the build depends on this resource now - I need to get information about the code systems from the tx.fhir.org
Grahame Grieve (Oct 31 2018 at 21:08):
as does the IG publisher
Rob Hausam (Oct 31 2018 at 21:11):
You mean retroactively submit the resource proposal? Do you recall what the deadline would be for that?
Grahame Grieve (Oct 31 2018 at 21:12):
it hasn't been proposed, and needs to be. we probably have 2 weeks or so
Rob Hausam (Oct 31 2018 at 21:13):
Right. So we can approve it on the call next week, then?
Grahame Grieve (Oct 31 2018 at 21:13):
yes
Rob Hausam (Oct 31 2018 at 21:13):
ok
Last updated: Apr 12 2022 at 19:14 UTC
