FHIR Chat · Code System Supplements · terminology

Stream: terminology

Topic: Code System Supplements

Grahame Grieve (Dec 15 2017 at 01:41):

I don't understand part #2 of the GF#13730. Why iterate supplements in the value set? is the server supposed to ignore supplements if the value set doesn't use them?

Rob Hausam (Dec 15 2017 at 02:14):

I believe I understand the intent of part #2: "Also add an extension on ValueSet called "usesSupplement 0..* Reference(CodeSystem)" with a textual constraint indicating that the referenced CodeSystem must supplement one of the code systems used in defining the value set." The intent, I think is to declare that the the value set is using the specified code system supplements when generating expansions (that part wasn't stated). A supplement, as defined here, wouldn't have any use other than in a expansion. So probably that should actually be part of ExpansionProfile (rather than an extension on ValueSet itself)?

Grahame Grieve (Dec 15 2017 at 03:42):

well, that ducks my original question: shouldn't the server just use the supplement when it implements the code system? why should the value set have to say something about that?

Lloyd McKenzie (Dec 15 2017 at 04:29):

Supplements can add properties and ValueSets can filter based on those properties. Value Sets can also make use of display names defined by supplements.

Lloyd McKenzie (Dec 15 2017 at 04:30):

For example, Canada has a code system extension on LOINC that adds a boolean "orderable" flag to the codes. We then define a value set of Orderable lab codes that include all LOINC codes where that flag is true (plus codes from a supplemental code system).

Grahame Grieve (Dec 15 2017 at 04:57):

there's 2 different questions here; does value set expansion use code system supplements if the value set doesn't mention them? and can a value set nominate it's dependency on value sets

Lloyd McKenzie (Dec 15 2017 at 05:10):

I wouldn't expect value set expansion to make use of code system supplements if the value set doesn't mention them, though I guess that could be handled through expansion configuration. A value set can certainly indicate its dependency on supplements (I presume that's what you're asking). The author of the value set would know what supplements were relevant - and an authoring tool would presumably only allow the use of a supplement's properties if the use of the supplement were declared

Grahame Grieve (Dec 15 2017 at 05:12):

well, I don't see why a value set has to declare that it uses a language pack in order for it to be used in an expansion

Lloyd McKenzie (Dec 15 2017 at 05:16):

If the value set includes display names drawn from a supplement, declaring the supplement would be appropriate. If it uses properties from the expansion, declaring the supplement is essential. If an expansion just wants to use names from a supplement, then that should be in the ExpansionProfile and wouldn't need to be in the ValueSet

Grahame Grieve (Dec 15 2017 at 05:17):

or it could be in several other places that tell the tx server that you want a language that was provided from the supplement.

Grahame Grieve (Dec 15 2017 at 05:18):

so I'm still not seeing what the definition associated with the value set list of supplements is - this value set expects you to have this supplement, and you should not process it if you don't. Or, you only use the supplements if the value set says so. From a tx server point of view, I strongly prefer the first

Lloyd McKenzie (Dec 15 2017 at 05:29):

Definitely the first

Lloyd McKenzie (Dec 15 2017 at 05:30):

Essentially it's saying "this value set depends on the supplement" - so good luck understanding it/expanding it if you don't have the supplement

Rob Hausam (Dec 15 2017 at 16:59):

What Lloyd said about "Supplements can add properties and ValueSets can filter based on those properties" is a primary example of where the value set depends on the supplemement and declaring the supplement would be required, as the supplement is actually used in the value set definition (CLD).

Grahame Grieve (Dec 15 2017 at 20:05):

ok I'm fine with that - I just have to write some documentation

Grahame Grieve (Dec 15 2017 at 20:17):

done

Grahame Grieve (Dec 28 2017 at 06:56):

ok, here's a little test code system supplement to help people:

{
    "resourceType": "CodeSystem",
    "id": "1",
    "meta": {
        "versionId": "2",
        "lastUpdated": "2017-12-28T06:53:07Z"
    },
    "language": "de",
    "url": "http://hl7.org/fhir/bundle-type-de",
    "version": "3.2.0",
    "name": "BundleTypeGerman",
    "status": "draft",
    "experimental": false,
    "date": "2017-12-21T16:40:38+11:00",
    "publisher": "HL7 (FHIR Project)",
    "description": "German Translations for Bundle Type",
    "content": "supplement",
    "supplements": {
        "reference": "http://hl7.org/fhir/bundle-type"
    },
    "concept": [
        {
            "code": "document",
            "display": "Dokument"
        },
        {
            "code": "message",
            "display": "Nachricht"
        },
        {
            "code": "transaction",
            "display": "Transaktion"
        },
        {
            "code": "transaction-response",
            "display": "Transaktionsantwort"
        },
        {
            "code": "batch",
            "display": "Stapel"
        },
        {
            "code": "batch-response",
            "display": "Batch-Antwort"
        },
        {
            "code": "history",
            "display": "Verlaufsliste"
        },
        {
            "code": "searchset",
            "display": "Suchergebnisse"
        },
        {
            "code": "collection",
            "display": "Sammlung"
        }
    ]
}

Grahame Grieve (Dec 28 2017 at 06:56):

This makes a difference to this expand operation:

Grahame Grieve (Dec 28 2017 at 06:57):

GET [base]/ValueSet/bundle-type/$expand?displayLanguage=de

Grahame Grieve (Dec 28 2017 at 09:40):

a couple of questions:

Grahame Grieve (Dec 28 2017 at 09:41):

• can a supplement change the value of a property? or just add new properties? or new values for properties?
• can a supplement change the heirarchy?

Grahame Grieve (Dec 28 2017 at 09:41):

@Ted Klein @Rob Hausam maybe these are good for discussion in tomorrow's vocab call?

Lloyd McKenzie (Dec 28 2017 at 14:43):

Supplements can't change anything in a code system - including properties and relationships. All they can do is define new properties, relationships and display names. (And typically, if defining new relationships it'll be relationships to other code systems, though I suppose you could supplement a code system to define the "obvious" hierarchy in a code system that didn't bother to do so.)

Grahame Grieve (Dec 28 2017 at 21:19):

new properties = new values on already define properties?

Lloyd McKenzie (Dec 29 2017 at 16:35):

Typically new properties entirely. New values on properties already defined by the code system would be dicey as you're treading on turf where an update to the base code system could create a conflict with the supplement. So my leaning would be to say "no". If you had to, the supplement could define a parallel property with a similar meaning.

Michael Lawley (Jan 09 2018 at 03:15):

@Grahame Grieve your example changes the URL for the CodeSystem doesn't it?

Grahame Grieve (Jan 09 2018 at 03:17):

the supplement has a URL of it's own, but it adds to the URL that is supplements.

Michael Lawley (Jan 09 2018 at 03:23):

So the supplement's url no longer identifies the code system, but instead identifies the supplement? Does this apply to all the other similar fields - name, version, status, caseSensitive, compositional, valueSet, etc?

Michael Lawley (Jan 09 2018 at 03:25):

Which URL would be used in the $expand result?

Grahame Grieve (Jan 09 2018 at 03:27):

the supplement's URL identifies the supplement. caseSensitive and compositional have no meaning - they can only repeat what the base code system says. same for value set.

Grahame Grieve (Jan 09 2018 at 03:27):

the base code system URL would be used in the $expand result

Michael Lawley (Jan 09 2018 at 03:32):

I notice also that the value of supplements.reference does not resolve to a Resource, so it is not a valid reference (http://build.fhir.org/references.html#literal)

Grahame Grieve (Jan 09 2018 at 04:07):

umm, why?

Michael Lawley (Jan 10 2018 at 01:43):

From the above link:

Whether or not the reference is to a FHIR RESTful server, the reference SHALL point to a Resource as defined by this specification

Michael Lawley (Jan 10 2018 at 01:46):

The link in your example (http://hl7.org/fhir/bundle-type) resolves to an HTML web page

Grahame Grieve (Jan 10 2018 at 03:05):

Hah. Not if you try with the right accept header

Peter Jordan (Jan 15 2018 at 23:39):

Having played with Grahame's example, I was left wondering how one might discover that any given Code System is supplemented by another. It's possible to search for Code Systems that have content mode of 'supplement' and request all the Code Systems that another system supplements, but there doesn't appear to be a property within a Code System resource that indicates that it's referenced by supplements. Might it be useful to add a property, or content mode value, for this use case - or am I missing something.

Lloyd McKenzie (Jan 16 2018 at 00:50):

Code systems generally don't know what supplements exist. They may not even like the fact that supplements exist. As with most things in FHIR, we only point one way - from supplement to code system. That allows you to do all the searching you need. We don't want bi-directional references

Peter Jordan (Jan 16 2018 at 01:12):

Nice to know that Code Systems have feelings. :heart:

Lloyd McKenzie (Jan 16 2018 at 01:17):

Well, perhaps it's more the feelings of the responsible organization. But those definitely have feelings and opinions :)

Michael Lawley (Jan 16 2018 at 13:00):

Why do we need CodeSystem.supplements to do translations? Is it not sufficient to just use the existing ValueSet mechanism?
That is, given a ValueSet, A, that picks some codes from the CodeSystem http://hl7.org/fhir/bundle-type, and a ValueSet DE that adds in German display text for each code in http://hl7.org/fhir/bundle-type (ie DE contains the translation), then can I not define a ValueSet A_DE that is the intersection of A and DE and behaves as desired?

Lloyd McKenzie (Jan 16 2018 at 19:44):

You want supplements to do translations because you want the translations to be available in a wide variety of value sets. You can't define a value set against a value set.

Lloyd McKenzie (Jan 16 2018 at 19:45):

If you do an intersection of two value sets, it's not clear what set of display names you'd end up with.

Jim Steel (Jan 17 2018 at 06:46):

It probably should be clear, regardless of what happens with supplements

Michael Lawley (Jan 29 2018 at 22:51):

Indeed, lack of clarity about how to manage overlapping display/designation information in the face of valueset intersection and exclusion is an issue that needs resolving regardless of supplements.
If we do this carefully, then a "translation ValueSet" would seem to satisfy the translation use-case obviate the need for supplements to support this. It would also leave the ValueSet author much more in control of what happens, whereas supplements subvert that control which I find very disconcerting.

Robert McClure (Jan 31 2018 at 20:31):

@Michael Lawley I don't see why you want to use a value set to do this translation stuff unless the translation is specific to the value set use. In that case I'd say we have different concepts in play because the meaning of the concept should be the same independent of the language used to describe it. I'd like to see the examples that prove that is wrong, then think about how to solve that problem.

Michael Lawley (Jan 31 2018 at 23:44):

I'm yet to be convinced about the need for supplements, and certainly it is currently very under-specified (I cannot implement it with any chance of being consistent with others). So, because I believe that the requirement for language packs is apparently satisfiable using existing machinery - ValueSets - I'm pushing to understand what the other use-cases for supplements might be.
From the definition (http://build.fhir.org/codesystem-definitions.html#CodeSystem.supplements), it would seem to be adding properties. I don't buy this for things like billing amounts (since they are time-variable and dependent on the context, not properties of the code), but I can envisage people (mis-)using supplements as a mechanism for this. What are the real use cases?

Lloyd McKenzie (Feb 01 2018 at 03:21):

Canada adds a property a whole bunch (thousands) of LOINC codes indicating that they are "orderable". We define multiple value sets on the basis of that property.

Lloyd McKenzie (Feb 01 2018 at 03:25):

Another use-case off the top of my head: flagging certain drug codes as "controlled" in a particular jurisdiction if you don't want the overhead of having a Medication instance for every code

Grahame Grieve (Feb 01 2018 at 11:33):

ValueSets doesn't work for Language packs

Michael Lawley (Feb 02 2018 at 00:39):

@Lloyd McKenzie How does this work when your terminology server spans jurisdictions?

Michael Lawley (Feb 02 2018 at 00:41):

@Grahame Grieve What am I missing? Can't you use a new ValueSet to mix in the base ValueSet definition with the translation ValueSet?

Grahame Grieve (Feb 02 2018 at 00:48):

a value set defines designations for use with the value set

Michael Lawley (Feb 02 2018 at 01:36):

And if ValueSet A is imported / included in ValueSet B, are those designations not also then used by ValueSet B?

Lloyd McKenzie (Feb 02 2018 at 01:50):

@Michael Lawley I don't really understand the question. Your terminology server would host whatever supplements it chooses from whatever jurisdictions choose to post them. Australia might have a different supplement and propose different orderable codes. Or they might choose to adopt the Canadian one but define their own value sets. What's the issue?

Michael Lawley (Feb 02 2018 at 02:30):

I'm running a terminology server that hosts content from multiple jurisdictions. Canada has a supplement for LOINC for property "orderable" and Australia has a different supplement for LOINC also specifying an "orderable" property. However, as I understand things, both supplements will affect the LOINC code system and create a mess.

Lloyd McKenzie (Feb 02 2018 at 02:42):

Neither will affect the LOINC code system in any way

Lloyd McKenzie (Feb 02 2018 at 02:42):

Value Sets can be created that leverage one or the other (or maybe both) and filter based on the properties they declare.

Michael Lawley (Feb 02 2018 at 04:27):

So if I have the following ValueSet definition, will its expansions be affected by either or both of the supplements? I don't see how a ValueSet can opt-in/out of using a given supplement.

{
  "resourceType": "ValueSet",
  "url": "urn:loinc-orderables",
  "name": "LOINC AU Orderables",
  "status": "draft",
  "compose": {
    "include": [{
        "filter": [{
            "property": "orderable",
            "op": "=",
            "value": "true"
          }],
        "system": "http://loinc.org"
      }]
  }
}

Lloyd McKenzie (Feb 02 2018 at 05:56):

My understanding is that it's been agreed that we'll add a "usesSupplement" element of type Relationship<CodeSystem> 0..*. I know Grahame has accepted this. It's essential to allow value sets to be dependent on supplement properties.

Michael Lawley (Feb 05 2018 at 23:18):

Thanks @Lloyd McKenzie , I'm much happier about this approach. @Grahame Grieve is this documented anywhere yet?

Grahame Grieve (Feb 05 2018 at 23:22):

no. on my list for this week. note, though, that if you define a supplement that defines designations for a language, and then request displays in that language in an expansion (profile) parameter, then the designations should be available, irrespective of whether the value set names the supplement. Also, supplement information should be available when doing $lookup

Michael Lawley (Feb 06 2018 at 00:30):

Thanks. Is there a mechanism for $lookup to indicate the source of its result information in case it comes from a supplement?

Rob Hausam (Feb 06 2018 at 01:40):

@Michael Lawley I don't believe we have a mechanism (outside of extension space) to flag information that is being returned from a supplement, but it seems like that may be important to know and we probably should have a way to do it.

Grahame Grieve (Feb 06 2018 at 03:39):

I don't know either, and it's something I'll be investigating

Grahame Grieve (Feb 16 2018 at 12:44):

I documented fragments and supplements. Once built, see http://build.fhir.org/codesystem.html#fragment

Last updated: Apr 12 2022 at 19:14 UTC