Stream: terminology
Topic: ICD-11 + root of a codesystem
Carl Leitner (Dec 09 2021 at 13:53):
We are working on adding SVCM compliance to the ICD-11 API. For the CodeSystem resource (specifically for linearizations such as MMS) we don't think it make sense to return the full set of concepts under CodeSystem.concept. Rather, we want to have the root concept be identified somehow in the CodeSystem resource. One option is to have CodeSystem.concept have a single concept in it, which is the root, but that seems perhaps a misleading. Is there another approach that others use in such a situation such as an extension to the CodeSystem resource to designate a root code? @Joe Amlung @Rob Hausam @jon payne
Rob Hausam (Dec 09 2021 at 14:13):
@Carl Leitner I have not heard of anyone so far doing this, or needing to do it. Of course someone might have done that, or something like it, and I'm not aware. Can you describe a little more the rationale for why identifying and calling out the root code like this is specifically needed for the ICD-11 API? I have some idea why you may want to do that, but it would be good to hear more of your thoughts. My inclination is that, assuming that it is needed, an extension on CodeSystem would be the way to do it.
Carl Leitner (Dec 09 2021 at 14:16):
Specific use case is that Open Concept Lab (OCL) is building a multi-code system browser and wants to show a hierarchy. To do so, they need to know the root to get started on the hierarchy and then use parent-child relationships on concepts to build out the hierarchy from there.
Jonathan Payne (Dec 09 2021 at 14:19):
Hi @Rob Hausam and @Carl Leitner - The only way to get the root code now is from the native ICD-11 API or manually from the ICD-11 browser. Once you have the root entity ID, you can use the ICD-11 FHIR API to visualize and traverse the entire hierarchy, but there's that manual step that you have to start with. Ideally we'd like a way for FHIR to respond with the root so that it is a fully FHIR-based process with no manual steps.
Lloyd McKenzie (Dec 09 2021 at 14:41):
Would selecting from a valueset of root concepts not work?
Carl Leitner (Dec 09 2021 at 14:59):
so a singleton valueset? but then you would need to know that this is the 'special' valueset that contains the root. we want to avoid having to hardcode these types of associations in the browser.
Jonathan Payne (Dec 09 2021 at 15:01):
Agree- Would still want to have that ValueSet available as an attribute of the CodeSystem, meaning either a list of root code(s) or a pointer to a valueset. Both would get the job done
Carl Leitner (Dec 09 2021 at 15:04):
a special valueset (as opposed to a special concept) would make sense if we have a multi-rooted codesystem. that's not exactly the case with ICD-11. Foundation is unrooted. MMS is a rooted subset that is published as its own code system. I don't think we will need multi-root with ICD-11. But not sure of other codesytems.
Carl Leitner (Dec 09 2021 at 15:06):
so i think we need an extension defined for 'root' as a concept or 'roots' as a valueset. the question is if there would be any use cases for the second option or should we just go with the first.
Jonathan Payne (Dec 09 2021 at 15:41):
Something like this? Here's the ICD-11 MMS codesystem in FHIR: https://icdapitest2.azurewebsites.net/fhir/CodeSystem/ICD11-MMS-2021-05/
An example of how we might add a root extension to the CodeSystem response. (I'm new to extensions, so definitely looking for input!) And need to draft the structure definition...
"_root": {
"extension": [
{
"extension": [
{
"url": "root",
"valueCode": "455013390"
}
],
"url": "http://hl7.org/fhir/StructureDefinition/codeSystemRoot"
}
]
},
Rob Hausam (Dec 09 2021 at 15:50):
I think that looks pretty good (I didn't try to verify the syntax). SNOMED CT has exactly the same situation with a root concept (138875005 |SNOMED CT Concept (SNOMED RT+CTV3)|), but this issue has never come up there (or with any other code system) that I am aware of. Again, though, an extension as Jonathan is proposing I think is likely going to be the cleanest and best way to do this. I agree with the other comments about using a value set - it seems that trying to use ValueSet probably doesn't add anything here (and may be more cumbersome).
Grahame Grieve (Dec 09 2021 at 19:16):
One option is to have CodeSystem.concept have a single concept in it, which is the root, but that seems perhaps a misleading
Why is that misleading? Why isn't the simplest solution the best?
Grahame Grieve (Dec 09 2021 at 19:16):
and why did no one talk about a property based solution?
Rob Hausam (Dec 09 2021 at 19:40):
Yes, I think that a property could work. It maybe is the most obvious solution - and could handle either the single or multiple root cases. Presumably (in most cases) the property(ies) would need to be added in a code system supplement - since if they were already present in the code system itself then we most likely wouldn't be having this discussion.
Grahame Grieve (Dec 09 2021 at 19:54):
I think @Jonathan Payne is making his own one up. I'm not aware of an agreed fhir distribution of icd-11 at least
Carl Leitner (Dec 09 2021 at 21:11):
Grahame Grieve said:
One option is to have CodeSystem.concept have a single concept in it, which is the root, but that seems perhaps a misleading
Why is that misleading? Why isn't the simplest solution the best?
Receiving system could say - oh wow here is a code system with only one code in it. The definition says "Concepts that are in the code system. The concept definitions are inherently hierarchical, but the definitions must be consulted to determine what the meanings of the hierarchical relationships are." and I would think it is a larger assumption to interpret this sentence as "Some of the concepts that are..." rather then "If present, all of the concepts that are"
Carl Leitner (Dec 09 2021 at 21:12):
Grahame Grieve said:
I think Jonathan Payne is making his own one up. I'm not aware of an agreed fhir distribution of icd-11 at least
No, @Jonathan Payne and I working with the ICD-11 team on this. They have started adding SVCM support and this was the one major gap. There is initial support for FHIR in the ICD-API.
Carl Leitner (Dec 09 2021 at 21:13):
we are trying to figure out what to get back to the ICD-11 API dev lead as needed changes in their FHIR API response.
Grahame Grieve (Dec 09 2021 at 21:24):
Receiving system could say - oh wow here is a code system with only one code in it
yeah well, receiving system could just as well say, 'I never even looked for any concepts at all'. That would be the same thing - ignoring an element in the resource. So I think that shouldn't be an issue
Grahame Grieve (Dec 09 2021 at 21:25):
great. I'm happy to be in on the conversation - I've been talking to Can about this (though not recently). Have you looked at the importer I already wrote?
Carl Leitner (Dec 09 2021 at 21:26):
Grahame Grieve said:
great. I'm happy to be in on the conversation - I've been talking to Can about this (though not recently). Have you looked at the importer I already wrote?
I have not seen that.
Grahame Grieve (Dec 09 2021 at 21:27):
Grahame Grieve (Dec 09 2021 at 21:27):
I have no need to continue to maintain that, btw. Just for consideration around consistency, though it's draft, so it's not authoritative in any way
Carl Leitner (Dec 09 2021 at 21:28):
Rob Hausam said:
Yes, I think that a property could work. It maybe is the most obvious solution - and could handle either the single or multiple root cases. Presumably (in most cases) the property(ies) would need to be added in a code system supplement - since if they were already present in the code system itself then we most likely wouldn't be having this discussion.
OK. That's better than a extension and less ambiguous as to the intent of singleton list of conepts.
Carl Leitner (Dec 09 2021 at 21:30):
oh... wait. There is no property.type code that we could use as 'root' and it is not extensible.
Carl Leitner (Dec 09 2021 at 21:31):
so what did you intend here?
Grahame Grieve (Dec 09 2021 at 21:53):
the type would be boolean - true | false. The code you're thinking about goes in CodeSystem.property.code - whatever you want, with your definition. If you want a formally defined thing, then use URL like http://hl7.org/fhir/concept-properties#root (we'd have to define that code in the code system)
Michael Lawley (Dec 09 2021 at 21:56):
We use a filter of `parent exists false
Michael Lawley (Dec 09 2021 at 21:56):
To determine root concepts (ie in a valueSet)
Michael Lawley (Dec 09 2021 at 21:57):
This is how the Shrimp browser determines hierarchy roots.
Michael Lawley (Dec 09 2021 at 21:58):
Adding a property to specify this means that it can be wrong, which can lead to strange behaviour from a user oerspective
Michael Lawley (Dec 09 2021 at 22:04):
Shrimp is a SMART app and can be launched to point at any FHIR terminology server (assuming CORS is permitted).
https://ontoserver.csiro.au/shrimp/launch.html?iss=[endpoint]
Michael Lawley (Dec 09 2021 at 22:07):
Shrimp does rely on being able to POST a ValueSet to the $expand operation to drive the hierarchy view
Carl Leitner (Dec 09 2021 at 22:20):
Michael Lawley said:
Shrimp does rely on being able to POST a ValueSet to the $expand operation to drive the hierarchy view
SVCM 3.97 has a GET for this. Why POST? https://www.ihe.net/uploadedFiles/Documents/ITI/IHE_ITI_Suppl_SVCM.pdf
Carl Leitner (Dec 09 2021 at 22:20):
Michael Lawley said:
We use a filter of `parent exists false
@Jonathan Payne @Joe Amlung @jon payne would this work for ICD-11-API+FHIR and OCL?
Carl Leitner (Dec 09 2021 at 22:21):
Michael Lawley said:
Adding a property to specify this means that it can be wrong, which can lead to strange behaviour from a user oerspective
OK. Thanks
Michael Lawley (Dec 09 2021 at 22:25):
POST means that the ValueSet doesn't need to exist on the server -- Shrimp can construct them on the fly and get them $expanded and thus work with a readonly server
Michael Lawley (Dec 09 2021 at 22:27):
From the spec, POST is primary and GET is "additional" for idempotent operations:
3.2.0.1 Executing an Operation
Operations are executed using a URL derived from the FHIR endpoint, where the name of the operation is prefixed by a "dollar sign" ('$') character. For example:
POST http://fhir.someserver.org/fhir/Patient/1/$everything
When an operation has affectsState = false, and the parameters are all primitive data types with no extensions (as is the case with the example above), it may be invoked using GET as well.
Carl Leitner (Dec 09 2021 at 23:00):
not sure if I fully understand here. under 2) here http://hl7.org/fhir/valueset.html#expansion it shows a GET as an example. expansion should be an idempotent operation. why would POST allow an expansion against a valueset that does not exist on the server while GET would not allow?
Carl Leitner (Dec 09 2021 at 23:03):
and here http://hl7.org/fhir/R4/terminology-service.html#expand there is not difference in expected behavior between GET and POST. I had understood that one of the main reason for POST is that there are practical limitations in GET request parameters (e.g. https://stackoverflow.com/questions/2659952/maximum-length-of-http-get-request)
Carl Leitner (Dec 09 2021 at 23:03):
(trying to understand if there is a reason for a change request against SVCM or not)
Michael Lawley (Dec 09 2021 at 23:04):
Yes, in a GET, there's no way to include the ValueSet definition in the request URL
Grahame Grieve (Dec 09 2021 at 23:04):
well, there is, but it's not convenient or reliable
Grahame Grieve (Dec 09 2021 at 23:05):
and I don't even know whether my server supports GET for that
Michael Lawley (Dec 09 2021 at 23:06):
oh! -Where is that documented?
Grahame Grieve (Dec 09 2021 at 23:13):
where is what documented?
Grahame Grieve (Dec 09 2021 at 23:13):
no actually, i lie:
Grahame Grieve (Dec 09 2021 at 23:13):
When an operation has affectsState = false, and the parameters are all primitive data types with no extensions (as is the case with the example above), it may be invoked using GET as well.
Grahame Grieve (Dec 09 2021 at 23:14):
so technically you could squeeze a value set into the URL, but we said not to
Grahame Grieve (Dec 09 2021 at 23:15):
anyway @Carl Leitner it's purely an encoding difference - GET/POST are the same in terms of meaning: do an expansion on this value set that you haven't previously seen.
Grahame Grieve (Dec 09 2021 at 23:15):
I make extensive use of this technique
Carl Leitner (Dec 09 2021 at 23:17):
@Jonathan Payne @Luke Duncan flagging for you for SVCM. Looks like we may need it to support both a GET and a POST
Michael Lawley (Dec 09 2021 at 23:17):
One thing on my todo list is a FHIR ValueSet equivalent of SNOMED's ECL and then we can define compact implicit ValueSets URIs for use in GET requests
Luke Duncan (Dec 10 2021 at 02:49):
Carl Leitner said:
Jonathan Payne Luke Duncan flagging for you for SVCM. Looks like we may need it to support both a GET and a POST
I believe there may be an appendix that calls out POST and GET can be used, but I'll double check and we can specifically call it out when I convert it to an IG format.
Jonathan Payne (Dec 10 2021 at 17:36):
Grahame Grieve said:
the type would be boolean - true | false. The code you're thinking about goes in CodeSystem.property.code - whatever you want, with your definition. If you want a formally defined thing, then use URL like http://hl7.org/fhir/concept-properties#root (we'd have to define that code in the code system)
Catching up- sounds like the use of a CodeSystem property may be the way to go? Seems like this works well if only a single root -- would this method work for a multi-root system? (Do we need to worry about that use case?)
Carl Leitner (Dec 10 2021 at 17:46):
no @Jonathan Payne i think the filter approach that @Michael Lawley is best.
Jonathan Payne (Dec 10 2021 at 18:12):
Carl Leitner said:
no Jonathan Payne i think the filter approach that Michael Lawley is best.
Got it- thanks @Carl Leitner for pointing that out - I missed that. And good approach @Michael Lawley
There's the possibility of orphaned codes that would be returned with the parent exists false approach, in which case you'd also need to look at whether a code also had children. This probably wouldn't be a concern in a major reference vocabulary, but could easily see this happening with other content.
Carl Leitner (Dec 10 2021 at 19:13):
(@Jonathan Payne and @Joe Amlung assuming you will coordinate with Can if any changes are needed, but please let me know if I am wrong)
Joe Amlung (Dec 10 2021 at 19:25):
Carl Leitner said:
(Jonathan Payne and Joe Amlung assuming you will coordinate with Can if any changes are needed, but please let me know if I am wrong)
We will coordinate with Can about this. We are drafting the recommendations and feedback for ICD-11's FHIR API in this document.
Jonathan Payne (Feb 02 2022 at 18:42):
Michael Lawley said:
We use a filter of `parent exists false
@Michael Lawley do you think you could provide a quick example (i.e. the body of the POST request) of how shrimp uses $expand to filter by parents exists false?
Michael Lawley (Feb 03 2022 at 00:00):
Sure, here's a ValueSet definition for the root concepts in LOINC:
{
"resourceType": "ValueSet",
"url": "urn:loinc-root-concepts",
"title": "Find root concept",
"status": "draft",
"compose": {
"include": [
{
"filter": [
{
"property": "parent",
"op": "exists",
"value": "false"
}
],
"system": "http://loinc.org"
}
]
},
"name": "Find_root_concept"
}
There's a couple of caveats to bear in mind. You may also want to limit the expansion to just active concepts since this definition will also find "orphan" concepts and in some code systems, inactive concepts are removed from the hierarchy. Hence, if you do this with SNOMED, then you'll get a lot of undesirable codes (or you can add inactive = false as an additional filter condition:
{
"resourceType": "ValueSet",
"url": "urn:sct-root-concepts",
"title": "Find root concept",
"status": "draft",
"compose": {
"include": [
{
"filter": [
{
"property": "parent",
"op": "exists",
"value": "false"
},
{
"property": "inactive",
"op": "=",
"value": "false"
}
],
"system": "http://snomed.info/sct"
}
]
},
"name": "Find_root_concept"
}
Jonathan Payne (Feb 03 2022 at 21:49):
Thank you @Michael Lawley ! Really really helpful, especially your comment on the orphaned concepts. Will play around with this and see if this approach works for the ICD11 FHIR endpoint.
Last updated: Apr 12 2022 at 19:14 UTC
