Stream: terminology
Topic: tx.fhir.org New parameters for $expand & $validate-code
Grahame Grieve (Aug 13 2020 at 21:53):
@Michael Lawley and other terminology server authors
I'm just finishing adding a new feature to tx.fhir.org $expand and $validate operations. The feature is driven by errors and performance challenges producing implementation guides. I'm adding 2 new parameters to both operations:
- tx-resource: This is a parameter in a POSTed Parameters resource that carries additional resources that will be needed by the server to perform the expansion or code validation. A typical use of this is when the client has a value set that it is passing by value (e.g. the whole value set) and that value set imports another valueset that the client has (and it is not confident that the server, or has the correct version). The server needs to include these resources in it's resolution space for the passed value set. tx resources can also include code systems that are known to the client. (Note that the server can choose to ignore these and return errors anyway)
The upshot of adding this is to fix various corner case problems to IG publisher expansion and code validation. But also, to increase the size of the calls to the terminology server. In one case I found, the call to the $validate-code operation was passing about 5MB of value set resources (long enumerations) and making about 1000 calls of the duration of the IG publication, and getting about 800b back each time. And it was about 60b that was different in each call
So this leads to the second parameter:
- cache-id: the client passes this parameter with a unique value (I'm using a UUID) for the run. The client only needs to pass resources in tx-resource, a value set inline by value, once during a session for the cache-id. The server remembers previously passed resources, and automatically brings them into scope when new calls are made for the same cache-id. Clients keep track of what they have sent to server previously, and only refer to the content by canonical URL (either {url}. {url} and {version} or {url|version}. The server retains the cache for x mins after last use (30 mins on tx.fhir.org ). Once they are out of scope, clients will start getting errors as if they hadn't passed the content.
The FHIR validator and the IG publisher both now use this technique, but only if they find the cache-id parameter declared in TerminologyCapabilities.expansion.parameter.name (or for R2|3, an "expansion.parameter' parameter in the parameters resource returned from the terminology metadata query response from the server)
Rob Hausam (Aug 13 2020 at 22:01):
Yes, this sounds good to me. It may be pretty specific to the IG publication process and other servers may not need it (unless they are functioning as alternate build servers)? Not sure what your thought is on that.
Grahame Grieve (Aug 13 2020 at 22:02):
I think that both issues are not specific to IGs, they are generic to using a terminology server, though they may not arise in many contexts
Rob Hausam (Aug 13 2020 at 22:02):
Yes, I would agree with that.
Rob Hausam (Aug 13 2020 at 22:03):
We need to update the spec for this?
Grahame Grieve (Aug 13 2020 at 22:03):
I think in time, yes
Rob Hausam (Aug 13 2020 at 22:03):
in time = R5, presumably?
Grahame Grieve (Aug 13 2020 at 22:04):
yes in that time, but I think we want to get experience with this before updating the spec
Grahame Grieve (Aug 13 2020 at 22:08):
btw, the other change I've made is that the IG publisher is making heavy use of batch validation now - using the batch API).
Michael Lawley (Aug 13 2020 at 22:50):
It's going to take me some time to digest the above proposal. But, it has always struck me as unusual that $validate-code does not support taking multiple Codings / CodeableConcepts as input.
Grahame Grieve (Aug 13 2020 at 22:51):
I'm amenable to thinking about that. Would reduce the importance of these other changes but not remove the need for them
Grahame Grieve (Aug 13 2020 at 23:10):
btw, tx.fhir.org is averaging 5 requests/sec at the moment
Michael Lawley (Aug 13 2020 at 23:45):
Doesn't sound too bad?
Grahame Grieve (Aug 13 2020 at 23:47):
no. it's creeping up. And there's bursts of 10-15/sec when multiple test runs are happening during the validator build process
Grahame Grieve (Aug 13 2020 at 23:48):
I may have to upgrade the server soon
Michael Lawley (Aug 13 2020 at 23:52):
Are these mostly $validate-code calls?
Grahame Grieve (Aug 14 2020 at 00:00):
yes.
Grahame Grieve (Aug 14 2020 at 00:01):
though the unit testing / ig publish has focus on expand so that might be higher than normal usage
Michael Lawley (Aug 14 2020 at 00:10):
Our r4 server was seeing 300-700 calls / minute overnight (which would be ~5-10/sec).
Sadly most were fails -- $validate-code without a system parameter (which I understand to be an issue with HAPI)
Peter Jordan (Aug 14 2020 at 00:49):
If the FHIR Validator and the IG Publisher now use the TerminologyCapabilities Resource, shouldn't the FMM Level of that Resource be raised from 0 to at least 1?
Grahame Grieve (Aug 14 2020 at 00:50):
yes it should be.
Grahame Grieve (Aug 14 2020 at 00:50):
but it's not new; I've been using it since it was first defined
Grahame Grieve (Aug 14 2020 at 00:51):
though my use is pretty selective in terms of elements right now
Peter Jordan (Aug 14 2020 at 00:54):
I've also implemented it since it was first defined and I believe that Michael also has a test implementation.
Michael Lawley (Aug 14 2020 at 03:52):
Based on my implementation & Grahame's, I'm not sure the breadth of our use is very significant.
Also, I would suggest that merely publishing instances of a Resource doesn't really constitute "use" -- you need clients to be consuming the Resource, and the only one I know of is the IG Publisher
Grahame Grieve (Aug 14 2020 at 04:06):
and the validator. And that's enough evidence to go from 0 to 1
Grahame Grieve (Aug 14 2020 at 04:06):
though no further
Rob Hausam (Aug 14 2020 at 12:27):
I can update it along with some of the other changes that need to be applied.
Michael Lawley (Aug 25 2020 at 21:09):
Been giving this a little thought. Is there a reason why you couldn't batch up all the calls into a single request. Then you could POST a Bundle with the requisite tx-resources as simple contained resources, and all of the $expand / $validate operations go in the batch Bundle which itself encapsulates the "lifespan" of the tx resources.
Grahame Grieve (Aug 25 2020 at 21:24):
yes lots of reasons
Grahame Grieve (Aug 25 2020 at 21:27):
- I'm validating multiple different resources - sometimes hundreds / thousands, which may contain that amount of codes (or more). I don't want to validate all that in a single hit (especially since the conditions of validation differ between resources e.g. language)
- Enough of the validation logic depends on the outcome of code validation (particularly slices) that I can't defer the validation logic into a batch. It's on my todo list to lazy validate anything that can deferred until I hit something I need to wait for but that's a signficant step up in complexity right now, so it hasn't happened yet (particularly because it actually makes the validator slower for any of the validation handled by the internal mini-terminology server)
- I am already batching what I can
Michael Lawley (Aug 25 2020 at 22:35):
I wondered about the validation logic...that did seem to be a possible key issue.
Another alternative is to just PUT/POST the resources to the server at the beginning and then clean them up at the end.
Grahame Grieve (Aug 26 2020 at 00:16):
I might be building different versions simultaineously
Michael Lawley (Aug 26 2020 at 01:24):
So you need some kind of scoping mechanism... (if the Tx resources have business versions, then that could help).
Or...generalise to the idea of creating a (transient) Scope that can be explicitly disposed or garbage collected. [thinking aloud here]
Grahame Grieve (Aug 26 2020 at 03:32):
that's what this is - a transient scope
Carmela Couderc (Aug 28 2020 at 18:45):
@Rob Hausam Please enter a JIRA to track the maturity level change - this Zulip thread might not be remembered in the future. Thanks.
Rob Hausam (Aug 28 2020 at 18:53):
@Carmela Couderc I did that when I made the updates for the Connectathon build - J#28296.
Michael Lawley (Sep 10 2020 at 06:01):
Does it then make sense to generalise this notion of a named transient scope across all $operations and not just $expand and $validate-code?
Perhaps $begin-scope and $end-scope operations, where $begin-scope takes a Bundle and returns a scope-id? Then pass an _scope=[scope-id] parameter to other operations?
Grahame Grieve (Sep 10 2020 at 06:41):
.. I don't know
François Macary (Sep 10 2020 at 08:14):
FYI: Phast's terminology server has also implemented TerminologyCapabilities.
Last updated: Apr 12 2022 at 19:14 UTC
