FHIR Chat · ValueSet $expand questions · terminology

Stream: terminology

Topic: ValueSet $expand questions

Tim Dunnington (Apr 28 2020 at 19:53):

Hey all, I have a bunch of questions about the $expand operation that boil down to determinism: how do I know, and how can I prove, that my expand operation is working properly in all cases. I've read the documentation, and there are a lot of areas that are not completely clear (at least to me).

I started this discussion on the implementers stream and was directed to this stream by another user, so I'm hoping you all can help me fill in the blanks.

My first question is very basic (I think). I've been told that an expansion is supposed to be a flattened list of codes. But if that's the case, why does the ValueSet.expand.contains also have child contains (implying that it's not a flat list)? How would I know, given an input value set, that the expansion in one case is supposed to be a flattened list of codes, but in the other case the hierarchy is to be preserved?

Grahame Grieve (Apr 28 2020 at 20:03):

There's no supposed to be. First of all, the client can ask for flattened or not (forUI), but the server doesn't need to return a heirarchy unless it can

Tim Dunnington (Apr 28 2020 at 20:29):

The reason I started looking into this issue was around a specific value set. We've been adding code set validation to our server implementation over time. We started with our organization-specific code sets first, which were pretty straightforward, so our expand operation served us well for the past year or 2. But then today we added validation for an HL7 standard valueset (in this case, Location.type, which requires value set http://hl7.org/fhir/ValueSet/v3-ServiceDeliveryLocationRoleType).

My expand operation can't handle this value set, but that's fine, I'm happy to add support for the filters that will make it work.

However, I'm left with the following dilemma:

• I would like to preserve hierarchy, it's actually easier than trying to flatten the list. In this value set, I would copy the _ServiceDeliveryLocationRoleType node to the expansion. The "is-a" rule says that all descendants, and the node itself, get copied to the expansion. If that's the case, wouldn't I have an expansion with a single item (the _ServiceDeliveryLocationRoleType and its descendants)?
• But if I do that, the exclude rule would seem to remove the same node I added in the include rule.
• If instead the "is-a" condition means "copy the children to the expansion", then the root node (_ServiceDeliveryLocationRoleType) wouldn't even be in the expansion, so why the exclude rule? And doesn't that conflict with the "is-a" definition?

I can see that if I implement expand on these filters one way, it'll work for some value sets and not others, and vice versa. So I'm worried I'm in a catch-22 here...if you see what I mean.

Tim Dunnington (Apr 28 2020 at 20:41):

Here is the valueset for Location.type, for reference

{
  "resourceType": "ValueSet",
  "id": "282724b1-95a5-42fd-bd9d-e79e5ad3bd12",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2019-12-11T21:02:30.851+00:00",
    "profile": [
      "http://hl7.org/fhir/StructureDefinition/valueset-shareable-definition"
    ]
  },
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Narrative removed to reduce size</div>"
  },
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/valueset-oid",
      "valueUri": "urn:oid:2.16.840.1.113883.1.11.17660"
    }
  ],
  "url": "http://hl7.org/fhir/ValueSet/v3-ServiceDeliveryLocationRoleType",
  "version": "2014-03-26",
  "name": "ServiceDeliveryLocationRoleType",
  "status": "active",
  "experimental": false,
  "publisher": "HL7 v3",
  "compose": {
    "include": [
      {
        "system": "http://hl7.org/fhir/v3/RoleCode",
        "filter": [
          {
            "property": "concept",
            "op": "is-a",
            "value": "_ServiceDeliveryLocationRoleType"
          }
        ]
      }
    ],
    "exclude": [
      {
        "system": "http://hl7.org/fhir/v3/RoleCode",
        "concept": [
          {
            "code": "_ServiceDeliveryLocationRoleType"
          }
        ]
      }
    ]
  }
}

Grahame Grieve (Apr 28 2020 at 20:55):

so if you doing value set validation, flatter is easier for the consumer of the expansion. The java validator explicitly asks for flat value sets rather than hierarchical ones - it's easier

Grahame Grieve (Apr 28 2020 at 20:56):

but you can do it using heirarchical value sets, until you run into one defined like this, which doesn't have a sensible heirarchy.

Grahame Grieve (Apr 28 2020 at 20:58):

well, it does; you just omit the code and elevate it's descendents up a level, but the algorithm starts to break down as more sophisticated excludes get included. So I didn't bother; if I see any exludes, I just stop trying to do the expand heirarchically in the first place

Grahame Grieve (Apr 28 2020 at 20:58):

The "is-a" rule says that all descendants, and the node itself, get copied to the expansion

yes. the value set would be a lot simpler if it was defined this way:

Grahame Grieve (Apr 28 2020 at 20:59):

{
  "resourceType": "ValueSet",
  "id": "282724b1-95a5-42fd-bd9d-e79e5ad3bd12",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2019-12-11T21:02:30.851+00:00",
    "profile": [
      "http://hl7.org/fhir/StructureDefinition/valueset-shareable-definition"
    ]
  },
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Narrative removed to reduce size</div>"
  },
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/valueset-oid",
      "valueUri": "urn:oid:2.16.840.1.113883.1.11.17660"
    }
  ],
  "url": "http://hl7.org/fhir/ValueSet/v3-ServiceDeliveryLocationRoleType",
  "version": "2014-03-26",
  "name": "ServiceDeliveryLocationRoleType",
  "status": "active",
  "experimental": false,
  "publisher": "HL7 v3",
  "compose": {
    "include": [
      {
        "system": "http://hl7.org/fhir/v3/RoleCode",
        "filter": [
          {
            "property": "concept",
            "op": "descendent-of",
            "value": "_ServiceDeliveryLocationRoleType"
          }
        ]
      }
    ]
  }
}

Grahame Grieve (Apr 28 2020 at 20:59):

that means the same thing.

Tim Dunnington (Apr 28 2020 at 21:34):

Thank you thank you! You're on my page here, and this was very helpful!

I can see I have some options to consider:

• Given your comment on the java client preferring a flattened expansion, that alone is probably a good reason for me to go with that model and flatten the expansions.
• If I want to support hierarchies, I could do that with the the forUI parameter (although I'm on DSTU2, there's nothing to stop me from implementing it anyway, wouldn't break anything).
• I could create a new version of the value set above in my server, and remove the exclude statement as you suggest. For that matter, if I run into another case like this, where the value set is a bit iffy, I can correct it without breaking anything.

Any thoughts about handling/validation of abstract codes? This value set includes a whole bunch of abstract codes, that are basically there to create hierarchies and subsets of codes. I suppose including abstract codes on the expansion is not going to hurt anything, but again in this example you'd have a bunch of codes that really aren't valid to use in a coding.

Grahame Grieve (Apr 28 2020 at 22:07):

well, have you looked at the expansion operation parameters?

Tim Dunnington (Apr 29 2020 at 13:42):

I'd been focused on the DSTU2 implementation and its parameters, but I'll take a closer look at the R4 parameters at your suggestion here. Thanks Grahame.

Alexander Pavlushkin (May 15 2020 at 13:54):

Hello, I have a question about value set expansion. There are quite a few implicit SNOMED CT value sets that I get from a Snowstorm server using ECL expressions. These value sets are intended for a patient e-health app. Is there an opportunity to get patient-friendly terms in these value sets? Thank you!

Grahame Grieve (May 15 2020 at 17:37):

how are SI distributing the patient friendly terms? It's a different edition? or a supplement?

Peter Jordan (May 15 2020 at 18:05):

(deleted)

Grahame Grieve (May 15 2020 at 18:11):

sounds like a supplement to me, then?

Peter Jordan (May 15 2020 at 18:20):

Apologies - needed coffee! Yes patient-friendly terms could be viewed as a supplement (my initial reply related to the GPS). In the NZ Edition, patient-friendly terms are distributed as additional descriptions and a language reference set.

Grahame Grieve (May 15 2020 at 19:12):

they have a use code then? (in FHIR terms)

Peter Jordan (May 15 2020 at 19:32):

We don't have a designation use code for patient-friendly terms as yet. It's been discussed at Vocabulary, but not added to the FHIR ValueSet. For SCT expansions, I currently place the NZ Reference Set ID in the Designation Token passed in the useContext parameter, i.e. http://snomed.info/sct|281000210109... but we need a solution for all Code Systems.

Rob Hausam (May 15 2020 at 19:36):

I'm pretty sure that we agreed (voted) to add it. I need to pull up the Jira task

Alexander Pavlushkin (May 15 2020 at 20:59):

It's looks like we can find at least one patient-friendly synonym that already exists in the SNOMED edition (we use the NZ edition). And in some cases we can't find an appropriate definition and should provide it.

Alexander Pavlushkin (May 15 2020 at 21:06):

Peter Jordan said:

Apologies - needed coffee! Yes patient-friendly terms could be viewed as a supplement (my initial reply related to the GPS). In the NZ Edition, patient-friendly terms are distributed as additional descriptions and a language reference set.

Thank you!

Rob Hausam (May 15 2020 at 23:12):

We still need to apply this in the spec - J#19960. It looks like we didn't ever decide what the new code for "consumer friendly" terms should be. It's also not clear to me how robust this solution is of adding "consumer friendly" to the value set. Is "consumer friendly" a subtype of 'Synonym' - or not?

Alexander Pavlushkin (May 16 2020 at 01:24):

Rob Hausam said:

We still need to apply this in the spec - J#19960. It looks like we didn't ever decide what the new code for "consumer friendly" terms should be. It's also not clear to me how robust this solution is of adding "consumer friendly" to the value set. Is "consumer friendly" a subtype of 'Synonym' - or not?

I suppose yes.

Michael Lawley (May 16 2020 at 05:32):

Perhaps we should also have a debate about the need for "consumer friendly" terms?

Daniel Vreeman (May 16 2020 at 13:16):

The LOINC community has had a fair bit of discussion about this, but I suspect that like @Michael Lawley , it doesn't feel settled. Presently, LOINC uses the label "Consumer Name", which is partly for historical reasons (it's been there a while, so harder to change). The agreed rules around its construction explicitly omit key distinguishing term attributes, which is great for its intended context of use (display to end users) but not for others (i.e. mapping). Some have argued these names would work nicely for "generalist" clinicians and so the distinction should really be between domain generalists and specialists, not providers and consumers. (We heard this from knowledge vendors that make their content available publicly to all). Despite all this, I'm good with "consumer" because it is evocative of the intended context of use...not because it's perfect.

We could always make synonyms for "consumer name" :grinning_face_with_smiling_eyes:

Rob Hausam (May 16 2020 at 14:09):

I agree that some further discussion and looking at known use cases seems warranted. I'm inclined to do that before applying this change (or any other related changes) to the spec.

Peter Jordan (May 16 2020 at 21:23):

To some extent, this debate has already taken place in some countries - driven by a switch in emphasis from a reactive system of healthcare interventions to a consumer-driven health and wellness approach. While I understand terminologists' concerns in this area, my view is that consumer requirements need to be addressed. In NZ, I would be very surprised if our SNOMED NRC withdrew the 'Patient-Friendly' terms already in use as that would be in contravention of the overall NZ Health Strategy.

Rob Hausam (May 16 2020 at 21:35):

I agree we need it - just thinking about the details of how we address it in FHIR.

Last updated: Apr 12 2022 at 19:14 UTC