How do I extend a value set?

[Craig_Finch]

I need to add a new value to a value set, and I can’t seem to find an example of how to do that. For example, adding a new status to http://hl7.org/fhir/ValueSet/payment-status

I think I will need to create a structure definition and publish it. So far, I have:

{
  "resourceType": "StructureDefinition",
  "id": "expandedPaymentTypes",
  "url": "http://mysite.com/ValueSet/payment-status-extended",
  "name": "payment-status-extension",
  "status": "draft",
  "kind": "complex-type",
  "abstract": false,
  "contextType": "resource",
  "type": "Extension",
  "derivation": "specialization",
  "baseDefinition": "http://hl7.org/fhir/ValueSet/payment-status",
  "differential": {
      "element": [
          {

          }
      ]
  }
}

I think I would use it like this:

{
  "resourceType": "PaymentNotice",
  "id": "payment1",
  "identifier": [
    {
      "value": "if we have a reference number, it goes here"
    }
  ],
  "status": "active",
  "request": {
    "reference": "Claim/claim1"
  },
  "statusDate": "2017-07-23",
  "paymentStatus": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/paymentstatus",
        "code": "declined",
        "_code": {
            "extension": [
              {
                  "url": "http://mysite.com/ValueSet/payment-status-extended",
                  "valueString": "declined"
              }
           ]
        }
      }
    ]
  }
}

Am I on the right track?

[grahamegrieve]

There’s 2 different questions here, extending a value set, and when you can change a binding.

You don’t extend a value set - but you can create a new one that imports the existing value set and includes additional codes or imports other codes. In practice, you’ve ‘extended’ the value set by doing that

the resources are published with codeable elements bound to value sets. Whether you can extend these depends on the binding strength. If the binding strength is ‘preferred’ or ‘example’ then you can make up your own value set as you like. If the binding strength is ‘extensible’ then you can make a new value as described above and bind to that. If the binding strength is ‘required’, then you can’t extend it at all.

Since that appears to be the case here (I infer you are talking about PaymentNotification.status) then your only choice is to go talk to the relevant committee (Finanical management) and ask how they expect your requirement to be handed.

[Craig_Finch]

@grahamegrieve I’m actually referring to PaymentNotification.paymentStatus, which has a binding strength of Example.

So, how do I define and use a new value set that includes an existing one? Can you point me to an example? If not, I’d like us to create a minimal example, because I’m sure a lot of FHIR adopters will need to effectively “extend” an existing example value set.

[lloyd]

PaymentNotice.status has a binding strength of “required”. That means you can’t use any codes other than the ones listed. If you want to convey more nuanced codes (e.g. payment revoked vs. payment unsuccessful for ‘cancelled’), you’ll need a supplementary extension. If you feel the set of codes doesn’t cover the space, then for now you’ll also need to send an extension, though you should also submit a change request. (In looking at the statuses defined, they seem a tad unintuitive/generic to me, so feel free to provide feedback if you don’t think they’re adequate/appropriate.)

If the binding strength had been anything other than ‘required’ and you wanted to include all of the codes from the existing value set, you’d define a value set like any other (lots of examples of that), and as part of the ‘compose’ element, you’d have “valueset”: “some-valueset-canonical-url”

[Craig_Finch]

@lloyd As I explained to Graham and showed in my example, I want to define a new value set that adds a code to PaymentNotice.paymentStatus, which has a binding strength of Example.

I will follow your suggestion for defining a new ValueSet that includes an existing ValueSet by URL, and post my results.

[lloyd]

You’re not allowed to. PaymentNotice.status must use the codes HL7 has defined. You’re not allowed to change or override that binding. All you can do is define parallel extensions or try to convince HL7 to change it.

[grahamegrieve]

This is a version issue. in DSTU2. this was example. in STU3, it changed to required.

Argonaut shows how to to do this - see http://www.fhir.org/guides/argonaut/r2/StructureDefinition-argo-immunization.html and check out the changes around vaccine code. (not quite what you want to do, but the same basic pattern)

[Craig_Finch]

@grahamegrieve Thank you for trying to clarify, but I’m afraid that I’m even more confused now. I am looking at this page:

http://hl7.org/fhir/paymentnotice.html

It says “FHIR Release 3 (STU)” across the top, so I’m assuming it’s STU3. Below, for PaymentNotice.paymentStatus it says:

Whether payment has been sent or cleared
Payment Status Codes (Example)

It looks to me as though paymentStatus has a binding strength of Example.

Just to be absolutely clear, PaymentNotice has two status fields:
PaymentNotice.status with binding required, and PaymentNotice.paymentStatus with binding strength Example. I am looking to extend PaymentNotice.paymentStatus with binding strength Example.

[lloyd]

Apologies. I was looking at PaymentNotice.status, not PaymentNotice.paymentStatus. (I’m a tad confused about the reason for both). In any event, the paymentStatus is indeed example, so you’re free to extend it - or make up a completely different value set entirely.

[RichardT]

• paymentStatus - status of payment - about the world
• status - status of resource instance - about the record

Useful to separate the two.

[Craig_Finch]

It appears that the Java validator does not support the use of codes from custom ValueSets. I defined a ValueSet and validated it, and put it online. I then defined a PaymentNotice resource and referenced my custom ValueSet:

{
  "resourceType": "PaymentNotice",
  "id": "payment1",
  "identifier": [
    {
      "value": "if we have a reference number, it goes here"
    }
  ],
  "status": "active",
  "request": {
    "reference": "Claim/claim1"
  },
  "statusDate": "2017-07-23",
  "paymentStatus": {
    "coding": [
      {
        "system": "https://storage.googleapis.com/mend-fhir-public/valueSet.json",
        "code": "this_is_invalid"
      }
    ]
  }
}

Run the validator:

java -jar validator/org.hl7.fhir.validator.jar mend-fhir/resources/paymentNotice.json -defn definitions.xml.zip
  .. load FHIR from definitions.xml.zip
  .. connect to tx server @ http://tx.fhir.org/r3
    (vnull-null)
  .. validate
Success...validating mend-fhir/resources/paymentNotice.json:  error:0 warn:0 info:0

The validator ignores the invalid code. It will also validate if I put a nonsense URL into the “system” field.

Is there any way to validate a resource that references a custom code?

[lloyd]

First, you can’t use Coding.system to convey a ValueSet reference, only a CodeSystem reference. Second, the validator doesn’t attempt to resolve Coding.system references because few of them will resolve to FHIR instances (they’re not expected to). To get the validator to pay attention to your value set, you’ll need to do the following:

• Publish your value set within an igpack (by publishing it as part of the implementation guide)
• Create a profile on PaymentNotice that binds the status to your value set and put that in an igpack too. (It can be the same implementation guide if you wish.)
• Reference the igpack(s) when invoking the validator using the -ig parameter
• Either use meta.profile to declare the profile in your instance or specify the full profile URL as an argument to the validator