FHIR Chat · Codesystems and Valuesets · shorthand

Stream: shorthand

Topic: Codesystems and Valuesets

Bob Milius (Apr 17 2020 at 21:02):

I'm not sure where to post this, but I thought I'd start here since I'm using FSH/Sushi, but it could also be because of my limited understanding of codesystems and valuesets in general. I have a toy IG that binds a value to a valueset, but the publisher doesn't seem to recognize it. I tried to create a codesystem in IG that it refers to, but doesn't seem to help. I keep getting

None of the codes provided are in the value set http://example.org/ig/vscs/ValueSet/hla-geneid-valueset (http://example.org/ig/vscs/ValueSet/hla-geneid-valueset), and a code from this value set is required) (codes = http://www.genenames.org/geneId#HGNC:4931)

and

The code system "http://www.genenames.org/geneId" is not known (encountered paired with code = "HGNC:4931"); The code provided (http://www.genenames.org/geneId#HGNC:4931) is not valid in the value set All codes known to the system for "http://www.genenames.org/geneId#HGNC:4931"

I posted the published IG at http://fhir.b12x.org/ig/vscs, and you can see the qa.html.

Here's my fsh file

Any insight will be appreciated.

Chris Moesel (Apr 17 2020 at 21:23):

I don't really know anything about the gene-related terminologies, so forgive me if these questions are naive, but...

The FHIR spec already defines a code system for HGNC with the canonical url: http://www.genenames.org (see CS doc). Is there a reason you are not using that? Is it different?

FHIR also defines a value set for all codes in the HGNC code system. The canonical url for that value set is: http://hl7.org/fhir/ValueSet/genenames (see VS doc). Again, is that different than the VS you're trying to define?

Chris Moesel (Apr 17 2020 at 21:29):

Also note, however, that if you look at the doc for the genenames value set, you'll also see "Error from server: Unable to provide support for code system http://www.genenames.org" -- so I guess it is expected that the FHIR publication tooling doesn't support that value set. You can suppress these expected errors by adding the warning messages to your ig-data/input/ignoreWarnings.txt file (as demonstrated in the sample-ig).

Bob Milius (Apr 17 2020 at 21:30):

yeah, those need to be updated. www.genenames.org isn't specific enough. We need to distinguish be gene names (codes that have a HGNC: prefix) and gene groups (codes without a prefix). The Clinical Genomics workgroup is using http://www.genenames.org/geneIds and http://www.genenames/genegroup in the Genomics-Reporting IG

Bob Milius (Apr 17 2020 at 21:31):

I thought that if I created codesystems in the IG, it would find them there and use them.
@Patrick Werner

Chris Moesel (Apr 17 2020 at 21:34):

Ah. OK. So... here is what I think is happening w/ the code system you defined in the IG... You forced the canonical URL to be http://www.genenames.org/geneId, which is outside of your IG's canonical URL base. But when you reference the code system in your value set by name, SUSHI is assuming the default canonical URL for that system instead (which would be {ig-canonical}/CodeSystem/{code-system-id}) instead of the external canonical you overrode it with.

Chris Moesel (Apr 17 2020 at 21:38):

At one point, defining a CodeSystem in an IG with a canonical URL outside of that IG's canonical URL was discouraged (or even not supported). I'm not sure if that's still the case or not -- but I noticed the publisher didn't actually complain about that, so maybe it is OK now. Let me see if I can tweak your FSH to make something work. If not, and if this is actually a FHIR-supported scenario, we'll need to update SUSHI so it doesn't assume that all CodeSystems defined in the IG actually use the IG canonical URL.

Bob Milius (Apr 17 2020 at 21:40):

ok, thanks! I touched on this subject in https://chat.fhir.org/#narrow/stream/179252-IG-creation/topic/Use.20of.20NamingSystem.20in.20an.20IG.3F where it sounded like Lloyd was saying it was okay.

Peter Jordan (Apr 17 2020 at 22:08):

Chris Moesel said:

At one point, defining a CodeSystem in an IG with a canonical URL outside of that IG's canonical URL was discouraged (or even not supported). I'm not sure if that's still the case or not -- but I noticed the publisher didn't actually complain about that, so maybe it is OK now. Let me see if I can tweak your FSH to make something work. If not, and if this is actually a FHIR-supported scenario, we'll need to update SUSHI so it doesn't assume that all CodeSystems defined in the IG actually use the IG canonical URL.

I think that update will be essential - unless you are referring to CodeSystem resources that are only used within the domain of a particular, project-based IG and are 'owned' by that project. In reality the canonical URL of a Code System is likely to have a base endpoint belonging to the owner of that Code System and that organisation may well not be the publisher of the IG - e.g. a national medicines terminology, or other code systems owned by public authorities.

Further thoughts @David Hay ?

Chris Moesel (Apr 17 2020 at 22:13):

I found that the Implementation Guide Parameters doc defines a parameter called special-url with this description:

If a canonical resource in the IG should actually have a URL that isn't the one implied by the canonical URL for the IG itself, it must be listed here explicitly (as well as defined in the resource itself). It must be listed here to stop it accidentally being different. Each canonical url must be listed in full as present on the resource; it is not possible to specify a pattern.

So... it seems that if we set that parameter in the ImplementationGuide JSON w/ the special canonical for the code system, that it _should_ work. But... I tried that an it seemed to make no difference as far as I could tell.

David Hay (Apr 17 2020 at 22:27):

Well, I've been creating codesystems and specifying the url (which we need in our implementation) - and the IG publisher doesn't seem to complain...

Chris Moesel (Apr 17 2020 at 22:29):

@Peter Jordan said:

I think that update will be essential - unless you are referring to CodeSystem resources that are only used within the domain of a particular, project-based IG and are 'owned' by that project. In reality the canonical URL of a Code System is likely to have a base endpoint belonging to the owner of that Code System and that organisation may well not be the publisher of the IG - e.g. a national medicines terminology, or other code systems owned by public authorities.

Just to ensure we're all on the same page -- we're talking about defining the content of external code systems not referencing or using external code systems.

I think the question is more of a human one than a technical one: should it be easy for IG authors to define resources that represent concepts that do not belong to the IG (or any of its authors), and furthermore should it be easy for them to assign those resource definitions canonical URLs using the real code system owner's domain as their base? Isn't that kind of a form of domain squatting, but in the standards space?

Or on the other end of the spectrum, what if the owner of the codes doesn't care, so five different IGs all publish different versions of that code system but every single one uses the same canonical URL? Isn't that a recipe for disaster?

Sorry... I think I'm getting philosophical now! But anyway, sticking strictly to the technical bit of this, it feels like the special-url IG parameter should all for this, but that doesn't seem to be working when I try it. Either that or the publisher isn't checking to see if Code Systems are defined in the IG before asking the tx server about them.

Peter Jordan (Apr 17 2020 at 22:31):

David Hay said:

Well, I've been creating codesystems and specifying the url (which we need in our implementation) - and the IG publisher doesn't seem to complain...

Is that because they are all have a base URL of https://standards.digital.health.nz/ ?

Peter Jordan (Apr 17 2020 at 22:35):

Chris Moesel said:

Just to ensure we're all on the same page -- we're talking about defining the content of external code systems not referencing or using external code systems.

Thanks for the swift reply @Chris Moesel . I suspected that we might be on separate pages, but it would make more sense to me if you were talking about defining the content of internal (to the IG) code systems. I'm not sure how you'd go about doing that for external Code Systems. In an IG you're more likely to be defining subsets of an external Code System in ValueSet resources.

Bob Milius (Apr 17 2020 at 22:40):

@Lloyd McKenzie

David Hay (Apr 17 2020 at 22:59):

Nope - I assign the url directly to the one - eg, in the Codesystem definition I have the following

• ^url = https://standards.digital.health.nz/cs/dhb

The base Url for the IG is http://hl7.org.nz/fhir/StructureDefinition/NHI

Lloyd McKenzie (Apr 18 2020 at 01:18):

The canonical URLs of code systems are allowed to diverge from the base URL of your value set, but I believe you need to set a special extension to have the publisher not yell at you. @Grahame Grieve ?

Grahame Grieve (Apr 20 2020 at 00:50):

catching up on this:

• the canonical URL can be different from the base. But you have to say that you know what you are doing by using the special-url parameter. No extension necessary
• it doesn't need to be easy to do it, but it does need to be possible.
• FMG will usually review any that are different to ensure that some of the policy concerns @Chris Moesel raised are being handled ok
• looking back at what Bob is doing... sounds like it should be discussed on the terminology track to see what should be done. Typically, these gene terminologies are very large, and you can't simply define them
• more likely, I'll need to do implementation work on tx.fhir.org to support these kinds of terminologies
• I don't know what this means

that doesn't seem to be working when I try it

Chris Moesel (Apr 20 2020 at 13:29):

that doesn't seem to be working when I try it

@Grahame Grieve -- I assumed that if Bob defined a code system in the IG w/ URL http://www.genenames.org/geneId and the codes were enumerated in that CodeSystem definition, and he added http://www.genenames.org/geneId as a special-url in the IG parameters, that the IG publisher would not complain about not supporting the http://www.genenames.org/geneId CodeSystem since it is fully defined in the IG (e.g., not an external dependency). But... when I tried it, the IG Publisher still complained about it.

Grahame Grieve (Apr 20 2020 at 13:31):

what was the complaint?

Bob Milius (Apr 21 2020 at 18:44):

I tried editing the ImplemenationGuide-vscs.json file that sushi created, by adding this to definition.parameter

      {
        "code": "special-url",
        "value": "http://www.genenames.org/geneId"
      }

but the qa.html file still contained the same errors.

Bob Milius (Apr 21 2020 at 18:56):

I also added an additional special-url for http://glstring.org, but again no change in the qa.html file generated by the publisher.

      {
        "code": "special-url",
        "value": "http://www.genenames.org/geneId"
      },
      {
        "code": "special-url",
        "value": "http://glstring.org"
      }

Grahame Grieve (Apr 21 2020 at 19:56):

that should work ( the first one). I'll have to debug

Grahame Grieve (Apr 21 2020 at 19:56):

how do I do that?

Bob Milius (Apr 21 2020 at 20:12):

You can find the build files of this example here.
https://github.com/bmilius-nmdp/fshing/tree/master/test/build
The input/ImplementationGuide-vscs.json file was hand-edited after sushi generated it.

Grahame Grieve (Apr 21 2020 at 22:18):

ok so I fixed one issue, but you have two issues remaining:

• Code System URI "http://glstring.org" is unknown so the code cannot be validated - because you defined it as http://www.glstring.org
• None of the codes provided are in the value set http://example.org/ig/vscs/ValueSet/hla-geneid-valueset - looks like you need to update the system value in that value set *

Bob Milius (Apr 22 2020 at 01:36):

@Grahame Grieve Thank you!

• I fixed the system in the valueset and don't see the "http://glstring.org" warning anymore.
• I still get the 2 errors. When you said you fixed one issue, will this be in the next release of the publisher?

Bob Milius (Apr 22 2020 at 01:40):

@Chris Moesel I had to change the system in the valueset from http://example.org/ig/vscs/CodeSystem/hla-genename-codesystemto http://www.genenames.org/geneId in valueset SD to get rid of the warning msg. This was generated by sushi. I did set it in my fsh file, but it looks like sushi overwrote it.

Grahame Grieve (Apr 22 2020 at 01:43):

yes next release

Chris Moesel (Apr 22 2020 at 13:17):

@ Bob Milius said:

This was generated by sushi. I did set it in my fsh file, but it looks like sushi overwrote it.

I'm looking at the FSH you posted before and I think I see the issue (if it's the same as you're using now):

ValueSet:  HLAGeneIdVS
Title: "HLA Gene Name Value Set"
Id: hla-geneid-valueset
Description:  "HLA HGNC GeneIds Valueset"
* codes from system HGNCGeneIdCS
* HLAGeneIdCS#HGNC:4931   "HLA-A"
* HLAGeneIdCS#HGNC:4932   "HLA-B"
* HLAGeneIdCS#HGNC:4933   "HLA-C"
// ... cut out the rest

This line references the external value set and essentially says the VS is comprised of all codes from that value set:

* codes from system HGNCGeneIdCS

That's fine, but then you also have lines like this:

* HLAGeneIdCS#HGNC:4931   "HLA-A"

This says to also include this specific code, but note that the CodeSystem you reference here is the alias HLAGeneIdCS which points to your local definition of the code system. So SUSHI is putting that local CS in the VS because you individually specified codes from the local CS. I expect that if you look at the exported VS, it actually contains references to both the external code system and the local one.

Bob Milius (Apr 22 2020 at 14:28):

Yes, you're right. Here's a snippet my exported VS.

...snip...
  "url": "http://example.org/ig/vscs/ValueSet/hla-geneid-valueset",
  "compose": {
    "include": [
      {
        "system": "http://www.genenames.org/geneId"
      },
      {
        "system": "http://example.org/ig/vscs/CodeSystem/hla-genename-codesystem",
        "concept": [
          {
            "code": "HGNC:4931",
            "display": "HLA-A"
          },
...snip...

I removed the * codes from system HGNCGeneIdCS line from the fsh file and sushi removed the first "system": "http://www.genenames.org/geneId" and left the local system.

...snip...
"url": "http://example.org/ig/vscs/ValueSet/hla-geneid-valueset",
  "compose": {
    "include": [
      {
        "system": "http://example.org/ig/vscs/CodeSystem/hla-genename-codesystem",
        "concept": [
          {
            "code": "HGNC:4931",
            "display": "HLA-A"
          },
...snip...

But now I have to edit that system to http://www.genenames.org/geneId to remove the qa warning for the example. How do I tell sushi to use that in the VS? The CS I have is a local fragment of the http://www.genenames.org/geneId. (Sorry for what I'm sure are naive questions)

Chris Moesel (Apr 22 2020 at 14:58):

I'm not 100% sure I understand what you're looking to do... I think you're wanting to use a local CodeSystem definition to define an external code system (w/ an external canonical URL) and then create a value set of all the codes defined there? Is that right?

Bob Milius (Apr 22 2020 at 15:39):

Yes, and also to have the publisher/validator not produce errors with an proper example. I edited the system in the VS to http://genenames.org/geneId, ran publisher, and posted the output here. You can see the VS has found the local fragment of the CS, and even populated the definitions which weren't in the VS structuredefinition. The qa.html still shows errors though. @Grahame Grieve said he fixed something in the publisher, but I don't think it's in the current release.

Bob Milius (Apr 22 2020 at 15:53):

btw, I just tried removing the individual codes from the VS fsh, and only use the * codes from system HGNCGeneIdCS. That worked in removing the warning without further editing of the VS, and the expansion from the local CS is seen in the rendered page, so that may be the way to go. But the same errors are still in the qa.html.

Chris Moesel (Apr 22 2020 at 16:54):

OK. I think there may be somewhere in our code that assumes a locally defined CS has a URL based on the IG canonical -- so it's also possible you've run into that during one of these variations of your FSH code. I'm going to file an issue for us to look into that.

Last updated: Apr 12 2022 at 19:14 UTC