Codesystem and ValueSet Implementation

1

I am having a difficult time wrapping my head around codesystems and valuesets, so I am taking it to the community in hopes that I can get some clarity.

  1. $lookup operation: https://www.hl7.org/fhir/codesystem-operation-lookup.html I struggled with this for a while and then I read that system and code are required, but the table only says if a code is provided a system must be provided. It doesn’t say you can’t just pass a system and I think it should, because in the top description it states: “a client SHALL provide both a system and a code”

So to be clear, $lookup must have at a minimum code and system to process the request?

1a. For the result of a $lookup, what is the payload response? Are we to return a single codesystem resourceType with the matching results? I have been searching on the docs and can only find what to pass in not what the response includes.

  1. General CodeSystem searches, ie /CodeSystem?system=http://examplecodes.org. Is this supposed to return all values for this codesystem? Or is it just supposed to return the properties that are custom to X codesystem? Where the user then uses a $lookup to get the code they need?

2a. For example, if I have a codesystem with information such as { full_name, short_name, status, code, description, last_updated_date } am I supposed to translate that data to the property array?

Example property array on CodeSystem resourceType:

{
  "resourceType": "CodeSystem",
  "id": "example",
  "url": "http://hl7.org/fhir/CodeSystem/example",
  "version": "20190522",
  "name": "Sample System",
  "title": "Sample System of Codes",
  "status": "active",
  "experimental": true,
  "date": "2019-05-22",
  "description": "Sample System to understand Codesystems resourceType",
  "caseSensitive": true,
  "content": "complete",
  "property": [{
    "code": "code",
    "description": "the code value of the sample system",
    "type": "code"
  }, {
    "code": "full_name",
    "description": "the full official name of the sample code in the system",
    "type": "string"
  }, {
    "code": "short_name",
    "description": "the abbreviated name of the sample code in the system",
    "type": "string"
  }, {
    "code": "nonvaccine",
    "description": "whether or not the code is a vaccine",
    "type": "boolean"
  }, {
    "code": "active",
    "description": "the codes status as active or inactive in the system",
    "type": "boolean"
  }, {
    "code": "description",
    "description": "the description of the sample code entry",
    "type": "string"
  }, {
    "code": "last_update_date",
    "description": "the last time the sample code entry was updated",
    "type": "dateTime"
  }]
}

2b. Then if a user wants to do a lookup and get back the code, short_name, and last_update_date would the request be: /CodeSystem/$lookup?code=24&sytem=http:example.org&active=true&&property=code&&property=full_name&&property=last_update_date

2c. What would the response be?

  1. ValueSet: Is this were we would return lists of values from a codesystem?

3a. Where can I get a list of all available valuesets in a system?

3b. In the above example we stated our example system had the following properties: full_name, short_name, status, code, description, last_updated_date. So how would I request a list of all { code, full_name, last_update_date } from a code system? I see a valueset has compose.include but I dont see any examples where the values from a codesystem’s properties are coming back in a valueset response.

I am sorry if this is all over the place, the CodeSystem and ValueSet are complex and have been really tricky for me to understand and I want to make sure I am doing the right things.

Any help is appreciated!

2
  1. If system is provided, then yes code must also be provided. Can you submit a change request for us to make this clarification?

2a. If you do a RESTful search, then you would typically return the entire code system - including every code it has and all properties for those codes. However, it’s possible that a server might expose certain code systems with content=not-present, example or fragment in which case there might not be any codes or only a subset of the codes provided. The only control in a RESTful query of what you get back is whether you ask for _summary or not.

It is possible that a terminology server might expose a CodeSystem with content=not-present (meaning that it only exposes the code system metadata and what properties are defined) but is still capable of performing full terminology and lookup validation operations against the code system. HL7’s terminology server does this for large (or infinite) code systems such as LOINC, SNOMED and UCUM. However, for most code systems when you query the code system, we expose all of the codes.

Note that neither the code nor the description/definition should be represented as properties. And typically full_name and short_name would be captured as designations (assuming they’re both distinct from the display value)

2b. It should be this:
[base]CodeSystem/$lookup?code=24&system=http%3A//example.org%active=true&property=code&property=full_name&property=last_update_date

2c. The response would be:

{
    "resourceType":"Parameters",
    "parameter": [
        {
            "name": "name",
            "valueString": "Example Code System"
        },
        {
            "name": "display",
            "valueString": "display for code"
        },
        {
            "name": "designation",
            "part": [
                {
                    "name" : "use",
                    "valueCoding" : {
                        "system": "http://someothersystem",
                        "code": "long-name"
                    }
                },
                {
                    "name" : "value",
                    "valueString": "Long name for the code"
                }
            ]
        },
        {
            "name": "property",
            "part": [
                {
                    "name": "code",
                    "valueCode": "nonvaccine"
                }
                {
                    "name": "code",
                    "valueBoolean": "true"
                }
            ]
        },
        {
            "name": "property",
            "part": [
                {
                    "name": "code",
                    "valueCode": "active"
                }
                {
                    "name": "code",
                    "valueBoolean": "true"
                }
            ]
        },
        {
            "name": "property",
            "part": [
                {
                    "name": "code",
                    "valueCode": "last_update_date"
                }
                {
                    "name": "code",
                    "valueDateTime": "2018-03-18T15:07:22"
                }
            ]
        },
    ]
}

Ideally, description should come back as a “definition” parameter, but for some reason it doesn’t. I asked around and it seems to be an accidental omission. I expect it’ll be added in FHIR R5. If you wanted to pre-adopt, that’s probably safe.

  1. ValueSet is how you select a subset of values from a code system for use. For example, if the code system were SNOMED CT (which contains hundreds of thousands of codes), for your particular use, you might only want a couple of hundred

3a - you can’t. Anyone in the world can define a value set using any code system (or set of code systems) they like. The maintainer of the code system can’t possibly know (and has no control over) all of the value sets that exist.

3b - value set expansions don’t generally contain the code properties, just the codes. If you want the code properties, you need to invoke $lookup on each one. The terminology services group is exploring options for combining those two operations, but I don’t believe anything’s been landed yet.

One way to understand the area better is to look at the code systems and value sets HL7 has defined and also do some playing with the HL7 terminology server (http://tx.fhir.org)

1 Like
3

Thanks Lloyd,

  1. Yes, I can submit a change request.

2c. This helps a lot and clears up the response body, thank you!

3a. I’ll try to expand on what I am asking here… If I was communicating with the Loinc fhir api, for example, (https://loinc.org/fhir/), is there no way to request a listing of all valuesets that the loinc fhir api has defined? Or a list of all ValueSets that include a specific codesystem ie, /ValueSet?url=http://loinc.org? Still not possible?

In their docs, they go on to say they have 3 defined valuesets. Is there no way for me to retrieve those from the api? Or would I have to read those from their docs and just know that those are the valuesets that exist? Hoping that clears up what I am asking.

Thanks for the resource (http://tx.fhir.org/) I am digging into it now!

4

You can query a given server to find out all ValueSets it knows about that use LOINC. ValueSet?reference=http%3A//loinc.org. That will give all value sets that include LOINC either directly or indirectly known to that particular server. If you hit LOINC.org’s official API, it would presumably give you any ‘official’ LOINC value sets - but it wouldn’t give you the tens of thousands of value sets defined elsewhere that draw on one or more LOINC codes.

5

I just tested that out on their beta API and that’s exactly what I wanted. Thank you!

6

Hello CragVFX,
I have met the same question as your question.3b. Could you share your solution, please?
Since codesystem have concepts, and those which in valueset.contains are some kind of concepts( only without properties), I am planning to simply add ‘property’ in valueset.contains.