Stream: terminology
Topic: meaning of CodeSystem.valueSet in a supplement
Michael Lawley (Jan 27 2021 at 05:56):
If CodeSystem.valueSet has been given a value in a CodeSystem supplement (i.e., CodeSystem.supplements also has a value):
- is this legal
- if so, what should it mean?
I don't have a good feel for the answer to 1., but if it is yes, then I would suggest that the meaning is "all codes in the supplemented code system, supplemented by this supplement". i.e., with all the supplement's designations and properties.
Lloyd McKenzie (Jan 27 2021 at 14:58):
A supplement can't change a value set definition, it can only change the expansion contents. As such, my preference would be to say that supplements can't have a defining value set.
Robert McClure (Jan 27 2021 at 15:58):
I agree with @Lloyd McKenzie that supplements can not add concepts (per the defined intent of a supplement) and it is concepts that the value set "definition" (ie: the scope) represents. But it is possible that the scope describes concept attributes that are only available in the supplement, therefore determining the expansion can only be done by using the supplement.
Michael Lawley (Jan 27 2021 at 23:23):
Certainly a supplement should not change the meaning of the existing valueset declared on the base CodeSystem, but what about a new (different) valueSet URI?
If anything, it could either be all codes in the code system, with supplemented features, or just all supplemented (in this one) codes.
Lloyd McKenzie (Jan 28 2021 at 00:35):
So we'd define a separate value set that is identical to the canonical value set for the base code system and only adds "and use this supplement"? Is there really value in that?
Michael Lawley (Jan 28 2021 at 06:50):
Agreed, the value is possibly quite limited. But currently there is nothing said about the valueSet property in a supplement, and this leaves a grey are that really should be clarified.
As a potential use-case, consider a code system supplement for SNOMED CT that includes (a library of) post coordination expressions. It might be quite convenient to have the supplement's valueSet URI be usable as either: "all codes in SNOMED as well as the expressions in this supplement", or "all codes & expressions in this supplement".
Carol Macumber (Jan 28 2021 at 15:22):
@Michael Lawley , might be that it's Thursday of the WGM and my brain is mush, but I'm just going to restate my understanding for any other poor souls who are trying to follow.
The definition of codesystem.valueset = "Canonical reference to the value set with entire code system" where "The definition of the value set SHALL include all codes from this code system and only codes from this code system, and it SHALL be immutable"
while the definition of codesystem.supplements = "Canonical URL of Code System this adds designations and properties to"
In your example, that equates to a codesystem resource representing "all codes in SNOMED as well as the expressions in this supplement" via
codesystem.valueset = http://snomed.info/sct
codesystem.supplements = (library of SCT post coordinated expressions)
Where I get lost is the "It would be quite convenient to have the supplement's valueSet URI be usable"...are you saying you'd then use the URL for the codeystem defined above in another codesystem.valueset declaration?
There is still a lot of work to be done around further clarifying the use of supplements. Thus the "black box" type warning that still exists stating "The impact of Code System supplements on value set expansion - and therefore value set validation - is subject to ongoing experimentation and implementation testing, and further clarification and additional rules might be proposed in future versions of this specification."
Perhaps from this we could get some folks to start drafting that verbiage...
Michael Lawley (Jan 29 2021 at 02:43):
Perhaps it's best to avoid the SNOMED and post coordination example in the first case.
Let's start with a CodeSystem, A, with URI http://example.com/A and valueSet URI http://example.com/A/vs. This code system is in English and has codes X, and Y.
Thus an expansion of http://example.com/A/vs returns the codes X and Y with English display text.
Now define a CodeSystem supplement, B, of our CodeSystem A. The supplement will have the URI http://example.com/A-sup, supplements=http://example.com/A, a translation to Icelandic of code X, an extra property for X, and lets also set its valueSet URI to http://example.com/A-sup/vs.
So, what now should an expansion of http://example.com/A-sup/vs return, if anything at all?
I am suggesting that it should retain the "all codes from this code system and only codes from this code system" semantics, but that it should also behave as if the ValueSet included the http://hl7.org/fhir/StructureDefinition/valueset-supplement extension with a reference to http://example.com/A-sup.
Lin Zhang (Jan 30 2021 at 00:43):
CS and its supplement(s) are not aways from the same authoring organization. So how to determine the URIs for them?
Lloyd McKenzie (Jan 30 2021 at 14:50):
There's no algorithm to determine URIs. You have to find them declared - e.g. in a registry or documentation or something.
Lloyd McKenzie (Jan 30 2021 at 14:50):
Typically the owner of a code system will have no clue that many supplements even exist.
Lin Zhang (Feb 02 2021 at 01:26):
@Lloyd McKenzie Emm, Agree. Thanks a lot.
Grahame Grieve (Feb 04 2021 at 22:06):
I agree with @Michael Lawley above, but we would need to be clear that the membership of the value sets is identical; it's only the displays and properties that might be different
Robert McClure (Feb 12 2021 at 17:45):
@Michael Lawley It took me a while to work through your phrasing of "a value set of the supplement" because I think of this as a value set that uses something specific drawn from the supplement and not be "the supplement value set.". But I think we are assuming the same thing where e value set include would specify system/version of the supplement. And then I agree with @Grahame Grieve that things need to align, at least the code system supplement has to have all the concepts needed by the value set.
This does raise the real concern that this means value sets could be created that only rely upon the supplement for content meaning control of the code system content used may be suspect. Do others have this concern?
Lloyd McKenzie (Feb 12 2021 at 17:48):
Supplements can't define concept meaning, so not sure how this could be a concern.
Peter Jordan (Feb 12 2021 at 22:31):
Lloyd McKenzie said:
Supplements can't define concept meaning, so not sure how this could be a concern.
In Michael's example of a CodeSystem resource where the content is defined as 'supplement', the code of each post-coordinated concept contains the Compositional Grammar defining the meaning of the Concept. That begs the question as to whether the meaning of those concepts is defined exclusively in those codes, and therefore in the supplement, or elsewhere.
Lloyd McKenzie (Feb 12 2021 at 22:57):
A supplement can define relationships, it can't define an additional syntax. If you want to leverage existing codes and define a post-coordinated code that draws on them, that's a new CodeSystem. All "code" values must be recognized by the original code system, regardless of what supplements are in play.
Michael Lawley (Feb 13 2021 at 03:50):
All post coordinations _are_valid recognised members of the original CodeSystem.
Michael Lawley (Feb 13 2021 at 03:50):
At least in the case of SNOMED CT
Rob Hausam (Feb 13 2021 at 03:51):
yes - I was just going to say that
Michael Lawley (Feb 13 2021 at 03:54):
@Robert McClure what I'm referring to is an implicit ValueSet identified by the CodeSystem.valueSet URI as specified in the supplement itself.
At the moment there's no requirement that it has the same value as the CodeSystem being supplemented.
Peter Jordan (Feb 13 2021 at 04:23):
Michael Lawley said:
All post coordinations _are_valid recognised members of the original CodeSystem.
OK, the concepts in the post-coordinated expressions (PCE) are valid members of the supplemented Code System - but I don't see how the concept represented by the complete PCE can be said to be in that code system. While I realize that supplements are a handy containers for PCEs, I don't see how they fit into the definition of a supplement in the spec as being ' designations or properties'. Maybe that definition is the problem and needs to be extended to include PCEs?
Michael Lawley (Feb 13 2021 at 04:31):
I would expect CodeSystem/$validate-code for a snomed PCE to succeed (subject to syntax etc), so I should be able to use the PCE in a supplement to, for example, supply designations.
After all, the spec says:
The following SNOMED CT artifacts are valid in the code element for the http://snomed.info/sct namespace: Concept IDs and SNOMED CT Expressions (using SNOMED CT Compositional Grammar ). SNOMED CT Terms and Description Identifiers are not valid as codes in FHIR, nor are other alternative identifiers associated with SNOMED CT Concepts.
Lloyd McKenzie (Feb 13 2021 at 04:34):
Supplements can't define post-coordinated expressions. I'm not even sure they can supplement them - we've never talked about that and I think it'd be problematic. SNOMED doesn't allow you to define a designation for a PCE. Why should a supplement? Supplements don't allow you to do anything you couldn't do in the original code system if the code system author had wanted to.
Michael Lawley (Feb 13 2021 at 04:56):
The snomed PCG specification at least allows:
Automatically transforming the expression into a human-readable term using a predefined algorithm. For example, a simple algorithm may just remove the concept identifiers and nesting – e.g. "fracture of bone: finding site = arm, laterality = left". More sophisticated algorithms may use pattern matching and predefined templates to construct a more natural term – e.g. "fracture of bone in left arm";
So it should at least be allowable to record the result of such an algorithm in a supplement?
Also, PCEs are valid snomed codes - the supplement isn't "defining them", only using them.
Michael Lawley (Feb 13 2021 at 04:56):
Sorry, link for above text is https://confluence.ihtsdotools.org/plugins/servlet/mobile?contentId=29951571#content/view/29951571
Lloyd McKenzie (Feb 13 2021 at 07:04):
No. Because there's no mechanism to record the result of executing the algorithm in the base code system. The code system allows you to list codes and display names. It doesn't allow you to list display names for a post-coordinated expression. A supplement is no different in that respect.
Lloyd McKenzie (Feb 13 2021 at 07:06):
CodeSystem.concept.code isn't allowed to contain a post-coordinated expression. That's as true when defining the code system as when defining a supplement. Valueset.compose.concept.code is free to contain post-coordinated expressions, and you're free to list the results of the naming algorithm in the designations there.
Michael Lawley (Feb 13 2021 at 08:06):
Where is that stated?
Element Id CodeSystem.concept.code
Definition A code - a text symbol - that uniquely identifies the concept within the code system.
421720008 |Spray dose form| + 7946007 |Drug suspension| or 421720008 + 7946007 is a SNOMED code that identifies the concept "drug suspension in spray dose form"
Lloyd McKenzie (Feb 13 2021 at 16:04):
CodeSystem defines codes, not combinations.
Lloyd McKenzie (Feb 13 2021 at 16:05):
Allowed combinations is defined by an algorithm that, at present, is shareable in CodeSystem as descriptive text.
Michael Lawley (Feb 13 2021 at 22:14):
So you would have the same constraints for common UCUM expressions?
Michael Lawley (Feb 13 2021 at 22:27):
My reading of the spec doesn't include the constraints you're talking about:
http://hl7.org/fhir/codesystem.html#scope
In addition, the CodeSystem resource may list some or all of the concepts in the code system
But, I'm approaching this from a "is it ruled out" perspective, whereas (I assume) you're approaching it from a different perspective which is not at all clear to me.
Lloyd McKenzie (Feb 13 2021 at 22:34):
I would. I'd expect to see "m" and "L" as codes in a UCUM code system, but I'd only expect to see "mL" in a value set.
Lloyd McKenzie (Feb 13 2021 at 22:37):
Certainly this is something we ought to clarify in the resource. Right now, the words pre and post-coordination don't appear on the page at all...
Thoughts @Grahame Grieve @Rob Hausam?
Lloyd McKenzie (Feb 13 2021 at 22:38):
My concern with allowing post-coordinated codes to be listed is how a consumer differentiates post-coordinated expressions from actual 'codes'. Also, what's the value of enumerating the combinations in the system when the whole point of having post-coordination is to avoid having to enumerate when defining?
Michael Lawley (Feb 13 2021 at 22:41):
I would ask why a consumer needs to do such differentiation? In SNOMED, expressions _are_ codes, just as concept ids _are_ codes. But when does a consumer need to differentiate m from mL in UCUM?
Michael Lawley (Feb 13 2021 at 22:44):
Being able to enumerate some post-coordinations is not the same as _having_ to enumerate them.
Michael Lawley (Feb 13 2021 at 22:51):
The use-case we are trying to support is an 'expression library' -- from an implementation perspective, enumerating the expressions in a supplement means we can pre-process them (run a classifier and pre-compute subsumptions etc), using the results to inform ValueSet expansions. It also allows people to associate designations, including translations, with the expressions to support $expand?filter=...
Michael Lawley (Feb 13 2021 at 23:03):
Our other use-case is for things like UCUM, where we allow for a CodeSystem fragment to enumerate all the "well known" codes so we have a simplified implementation strategy
Lloyd McKenzie (Feb 13 2021 at 23:11):
Consumers generally don't need code systems. Consumers need value sets. Terminology servers need to be able to consume code systems. If the postcoordinated symbols and raw codes are intermingled, how is a valueset to know what to do?
Robert McClure (Feb 13 2021 at 23:20):
I'm with @Michael Lawley here in agreeing that we have not, and should not, disallow codes that technically are the result of a code system defined algorithm for valid post or pre-coordinated expressions. I guarantee that users are not interested in more hurdles in using UCUM and they consider existing combinations of atoms valid codes in the UCUM code system. Regenstrief considers the common UCUM Units list a set of UCUM codes. SNOMED can't get out of it's own way regarding the use of expressions as "real" codes but they certainly do consider an expression equivalent to a concept and assume and expression should be treated as a valid concept when determining equivalence and placement in the inferred structure. Ergo, an expression is a code in the code system.
As for using a supplement to hold a set of enumerated expressions, I think we need to really discuss the pros and cons of using that vehicle versus allowing this to be done in a fragment. I'd rather we found it acceptable to use fragment I think, but want to hear why supplement is better.
Michael Lawley (Feb 13 2021 at 23:35):
What valueset features need to distinguish between postcoordinated symbols and raw codes ?
Michael Lawley (Feb 13 2021 at 23:39):
@Robert McClure The reason we opted for supplements and not fragments is twofold:
- only the code system authority can publish fragments, and
- there is a documented mechanism for bringing the content of a supplement into the scope of a ValueSet. How and when fragments combine (if at all) is undefined (http://hl7.org/fhir/codesystem.html#fragments)
Lloyd McKenzie (Feb 13 2021 at 23:52):
For one, if you're going to post-coordinate, you need to know what are 'real' codes and what's already an expression - because the rules for inclusion are likely to be different.
Robert McClure (Feb 14 2021 at 16:52):
@Michael Lawley I think we need to clarify what "Publish" means regarding fragments. FHIR servers through out the world contain code system fragment resources that exist solely on that server and no place else. IE: it seems to me that anyone can decide what subset they want and need in a resource for use and this is not only useful, it is demonstrably practical. I'd be very surprised if your server does not contain code system resources that are (or should be) marked as fragments that you did not get for the code system authority as an officially published fragment. So #1 is not practically true and it should be made clear that it is not a requirement because it's simply impossible and wrong to make this a requirement. That leaves #2 and I wondered if that was the problem so I suggest we work on clarifying what needs to change to make use of fragments for PCE the proper solution. Then the argument that PCEs are "real codes" fits.
Peter Jordan (Feb 14 2021 at 20:13):
@Robert McClure for SNOMED CT, my (slightly informed) guess is that FHIR Terminology Servers generally implement subsets as Value Set resources based on Reference Sets - not as Code System Fragments. I also don't see how the current definition of a Code System Fragment in the FHIR Specification would allow us to treat PCEs (particularly those created 'close-to-user form') as Fragments. The better solution is to extend the definition of Supplements to include PCEs.
Michael Lawley (Feb 15 2021 at 01:17):
@Robert McClure I think it's more than just a definition of "Publish" in this case (and I agree with your sentiments on pragmatic uses), but rather some of the technical aspects, as well as some conceptual ones.
From a technical perspective, a supplement can express explicit dependencies on the base CodeSystem content it is referencing - specifically via the version field. A fragment doesn't really do this; it effectively exists in isolation from other fragments or a complete CodeSystem.
From a conceptual perspective, if a terminology server contains two CodeSystem instances for the same code system (and version), one of which is complete and the other is a fragment, it would seem entirely reasonable for it to completely ignore the fragment as extraneous, especially if the server has in-built support for the code system. On the other hand, a supplement is intrinsically positioned as containing information additional to the base.
Robert McClure (Feb 15 2021 at 16:39):
@Michael Lawley @Peter Jordan Yep, this is complicated. I can tell you that I know IGs are including code system fragments that only include the codes needed to support expansions defined in the IG, so they don't have to represent all the concepts they don't need. Make sure as you consider this you are not focused solely on SCT, LOINC. Also keep in mind that for UCUM I would presume it's always a fragment and I suspect that every server will have a different set. So we need to make what is practically happening technically correct. This sounds like a topic for a call - can we do it during a main vocab call normally 3:30p ET? Say 30min max? @Ted Klein @Carol Macumber
Lloyd McKenzie (Feb 15 2021 at 16:47):
UCUM doesn't need to be a fragment. Enumerating full UCUM is pretty easy. You just can't enumerate all the post-coordinated concepts.
Robert McClure (Feb 15 2021 at 16:52):
But we have been including the PCEs as codes and it's honestly the best way to do it. But I get that this means it's technically confusing. I really don't want to complicate the majority in order to force 'correctness" on one or two.
Michael Lawley (Feb 15 2021 at 21:29):
@Robert McClure What would an IG do that? Surely IGs shouldn't be including code systems that they aren't themselves defining?
If they want to ensure a certain rendering of a ValueSet, then I would have expected them to instead include an expansion in the ValueSet definition?
Richard Townley-O'Neill (Feb 16 2021 at 00:25):
If partial code systems are being included in IGs so that the value sets can contain the concepts definitions, there is no need. There is an extension on value set that allows definitions to be recorded: http://hl7.org/fhir/R4/extension-valueset-concept-definition.html
Edited: This is a bad idea, as pointed out by @Michael Lawley below.
Robert McClure (Feb 16 2021 at 17:17):
Good lord. You all have made this value set round hole the size of a truck so that every code system truck gets to drive right on in. Yes, yes I understand that no one cares about code systems and only value sets really matter. But even a trivial FHIR server should be able to provide an Expansion so that there is consistency across value set use of concepts. I hope that concept definition extension is from the pre-code system in FHIR days. @Richard Townley-O'Neill Including definitions is only one reason to have code system resources available to an IG. @Michael Lawley IGs may need concept information for a variety of reasons. From what I understand, very few FHIR implementations make use of a terminology service, so anything they need is inside the FHIR server. Yes, point-in-time expansions included in a FHIR value set resource (best using ExecutableValueSet Profile can be a very useful approach when the code system rarely changes. But for IGs that need code systems that have complexity that various value sets use differently, we need to encourage the use of the code system resource as a central concept repository. Not demand it, but support it properly. And I'd agree that we need to make adding definitions to concepts in a code system resource easy so people don't use the absolutely easier value set extension. Having to create a supplement seems heavyweight given the "but it's fine" consideration for doing it in a value set.
Michael Lawley (Feb 16 2021 at 21:19):
@Richard Townley-O'Neill no that is an entirely inappropriate use of that extension. It is designed for the case where the underlying code system does not define a meaning for the code, not for when you just don't have a representation of it to hand.
That extension is a last resort mechanism for use when someone else has painted you into a corner.
Michael Lawley (Feb 18 2021 at 00:30):
+1 for ExecutableValueSet Profile
Grahame Grieve (Feb 24 2021 at 02:16):
I see I'm late to this party, but I definitely disagree with @Lloyd McKenzie on this one. if the code system defines a grammar, but does not enumerate all the possible codes allowed under the grammar, a supplement can enumerate additional codes and define displays and properties for them.
Grahame Grieve (Feb 24 2021 at 02:16):
the fact that enumerates them does not make any difference to their validity, only their properties and displays
Lloyd McKenzie (Feb 24 2021 at 03:47):
That's going to make checking supplements for validity darn hard. The rule is "supplements can't have codes that aren't in the base code system". If a supplement includes post-coordinated expressions created with an algorithm that's opaque to the terminology server, how is it to check that the codes in the supplement that aren't in the base code system are legitimate?
Grahame Grieve (Feb 24 2021 at 03:49):
it can't, of course. Grammars are hard. But tx.fhir.org can and the validator, at least, can check the grammar for snomed and ucum
Grahame Grieve (Feb 24 2021 at 03:50):
though it doesn't actually happen right now
Grahame Grieve (Feb 24 2021 at 03:50):
supplements, generally, are on my to do list
Lloyd McKenzie (Feb 24 2021 at 03:53):
It seems weird to me - because it's giving supplements a capability to do something the base code system can't do. A post-coordinating system can define algorithms to determine properties and/or representations for post-coordinated concepts, but it can't enumerate them and define non-algorithm-based properties or representations. In general, supplements haven't been able to do things the base code systems couldn't have done. Why are we making an exception here?
Grahame Grieve (Feb 24 2021 at 03:58):
it can enumerate them, or some of them, if it wants to. There's nothing here that a base code system can't do
Lloyd McKenzie (Feb 24 2021 at 04:14):
UCUM can't define a custom display-name or properties for mL. Nor can SNOMED do so for 298756009:{363698007=371195002,116676008= 72704001} - at least not without defining a pre-coordinated term for it.
Grahame Grieve (Feb 24 2021 at 05:03):
I'm not sure what you mean there.
Grahame Grieve (Feb 24 2021 at 05:04):
a code system resource can do that if it wants, if the rules of the code system allow it. I'm not sure about UCUm but SCT allows it to happen with a pre-coordinated term
Lloyd McKenzie (Feb 24 2021 at 14:20):
Sure - but a pre-coordinated term is a distinct code. Are we aware of any post-coordinated code system that allows defining properties or display names for post-coordinated terms except algorithmically?
Grahame Grieve (Feb 24 2021 at 20:16):
sorry, I meant, SCT allows it to happen with a post-coordinated term
Lloyd McKenzie (Feb 24 2021 at 23:15):
That's surprising to me, but ok, if code systems can do it, then certainly supplements can do it too.
Robert McClure (Feb 25 2021 at 04:10):
@Lloyd McKenzie Yes - BCP47 does exactly that - algorithmically determined names for expression-based codes. en-CA = Canadian english.
Lloyd McKenzie (Feb 25 2021 at 04:23):
Algorithmic is fine. Grahame is saying that SNOMED-CT allows non algorithmic names to be assigned to specific post-coordinated expressions. If that's true, there's no reason why supplements couldn't do the same.
Lin Zhang (Feb 25 2021 at 14:07):
So called "properties" in FHIR actually include concept relationships but the latters might lead to a structured definition meaningfully different from their original one in the code system.
Last updated: Apr 12 2022 at 19:14 UTC
