Extensions

[robs16]

There will be times where CDS Hooks structure will need to be extended for a particular service provider, hook, etc. Can the documents be updated to describe how this should be done to limit impacts as the spec evolves? Should cover things like JWT extensions, discovery extensions, request extensions, etc.

The issue I see here is that a service provider could easily fall into the trap of building a service that actually broke when sent an extended request, and vice-versa where the response/discovery is extended and that breaks the EHRs implementation.

[robs16]

I haven't seen any comments on this and I believe it will be really important, so I wrote up the following as an example of what this should potentially be:

Extensibility
This specification is meant to cover the needs of most services. However it is clear
that this specification will evolve over time and may not meet the needs of all services 
and all consumers in any given revision. As a result, implementations may add extensions
to meet their particular needs. In order to keep these extensions from negatively 
impacting existing implementation, they will follow a form similar to FHIR, but available 
at each level of structure within the request and response. 

example discovery extension
{
  "services": [
    {
      "title": "Stanson Health Advisory",
      "hook": "patient-view",
      "id": "patientview",
      "prefetch": {
        "patient": "Patient/{{Patient.id}}"
      },
      "description": "clinical decision support for patient view",
      "extension": [
        {
          "url": "http://my.hooks.org/fhir/102/StructureDefinition/client-conformance",
          "valueUri": "http://my.hooks.org/fhir/102/Conformance/patientview"
        }
      ]

    }
  ]
}

example request extension:
{
  "hookInstance": "84162911-F961-4EE7-B348-3FCE01FFFDDF",
  "hook": "order-review",
  "user": "Practitioner/testdoc",
  "patient": "testpatient",
  "encounter": "testencounter",
  "context": {},
  "prefetch": {},
  "extension": [
    {
      "url": "http://my.hooks.org/fhir/102/StructureDefinition/requesting-organization",
      "valueId": "gastrointerology"
    }
  ]
}

example response extensions:
{
  "cards": [
    {
      "indicator": "warning",
      "summary": "Don't perform imaging of the carotid arteries for simple syncope without other neurologic symptoms.",
      "links": [
        {
          "label": "Review in the CDS application",
          "type": "absolute",
          "url": "https://my.not.smart.app/token=EA559D17-6FE1-4A1D-8976-06CE158EA40F"
          "extension": [
            {
              "url": "http://my.hooks.org/fhir/102/StructureDefinition/link-timeout",
              "valuePositiveInt": 3600
            }
          ]
        }
      ],
      "suggestions": [
        {
          "extension": [
            {
              "url": "http://my.hooks.org/fhir/102/StructureDefinition/suggestionType",
              "valueCode": "dismiss"
            },
            {
              "url": "http://my.hooks.org/fhir/102/StructureDefinition/PAMA-score",
              "valueCode": "inappropriate"
            }
          ],
          "label": "Dismiss",
          "actions": [],
          "uuid": "12C12C48-7985-43CF-A12C-D5D9458B1BF1",
        },
        {
          "extension": [
            {
              "url": "http://my.hooks.org/fhir/102/StructureDefinition/suggestionType",
              "valueCode": "accept"
            },
            {
              "url": "http://my.hooks.org/fhir/102/StructureDefinition/PAMA-score",
              "valueCode": "appropriate"
            }
          ],
          "label": "Remove Orders",
          "actions": [
            {
              "resource": {
                "resourceType": "DiagnosticOrder",
                "id": "C7ACB00B-C3B6-45E8-B469-CDCDABF905F6"
              },
              "description": "Remove imaging of carotid arteries",
              "type": "delete",
              "extension": [
                {
                  "url": "http://my.hooks.org/fhir/102/StructureDefinition/markdown-description",
                  "valueString": "**Remove imaging of carotid arteries**"
                }
              ]
            }
          ],
          "uuid": "12C12C48-7985-43CF-A12C-D5D9458B1BF2"
        },
        {
          "extension": [
            {
              "url": "http://my.hooks.org/fhir/102/StructureDefinition/suggestionType",
              "valueCode": "override"
            },
            {
              "url": "http://my.hooks.org/fhir/102/StructureDefinition/PAMA-score",
              "valueCode": "appropriate"
            }
          ],
          "label": "Focal neurological findings",
          "actions": [],
          "uuid": "12C12C48-7985-43CF-A12C-D5D9458B1BF3"
        },
        {
          "extension": [
            {
              "url": "http://my.hooks.org/fhir/102/StructureDefinition/suggestionType",
              "valueCode": "prompt"
            },
            {
              "url": "http://my.hooks.org/fhir/102/StructureDefinition/PAMA-score",
              "valueCode": "potentially inappropriate"
            }
          ],
          "label": "Other (please specify)",
          "actions": [],
          "uuid": "12C12C48-7985-43CF-A12C-D5D9458B1BF4"
        }
      ],
      "detail": "[Occlusive carotid artery disease does not cause fainting but rather causes focal neurologic deficits such as unilateral weakness. Thus, carotid imaging will not identify the cause of the fainting and increases cost. Fainting is a frequent complaint, affecting 40% of people during their lifetime.](http://www.choosingwisely.org/clinician-lists/american-academy-neurology-carotid-artery-imaging-for-simple-syncope/)\n* Secondary Source: American Academy of Neurology\n* Education: [The American Academy of Neurology's Top Five Choosing Wisely recommendations](http://www.neurology.org/content/early/2013/02/20/WNL.0b013e31828aab14.full.pdf+html)\n* Release Date: 02-18-2013\n\n# Supporting Evidence:\n\n1. [National Institute for Health and Clinical Excellence. Transient loss of consciousness (\u2018Blackouts\u2019) Management in adults and young people. [Internet]. London: Royal College of Physicians (UK); 2010](http://www.nice.org.uk/guidance/cg109/chapter/notes-on-the-scope-of-the-guidance)\n1. [Strickberger SA, Benson DW, Biaggioni I, Callans DJ, Cohen MI, Ellenbogen KA, Epstein AE, Friedman P, Goldberger J, Heidenreich PA, Klein GJ, Knight BP, Morillo CA, Myerburg RJ, Sila CA. AHA/ ACCF scientific statement on the evaluation of Syncope: From the American Heart Association councils on clinical cardiology, cardiovascular nursing, cardiovascular disease in the young, and stroke, and the quality of care and outcomes research interdisciplinary working group; and the American College of Cardiology Foundation in collaboration with the Heart Rhythm Society. J Am Coll Cardiol 2006 17;47(2):473-84](http://www.sciencedirect.com/science/article/pii/S0735109705030445)\n1. [The Task Force for the Diagnosis and Management of Syncope of the European Society of Cardiology. Guidelines for the diagnosis and management of syncope (version 2009). Eur Heart J 2009 ;30(21):2631-2671.](http://www.ncbi.nlm.nih.gov/pmc/articles/PMC3295536/)\n",
      "source": {
        "label": "Choosing Wisely",
        "url": "http://www.choosingwisely.org/clinician-lists/american-academy-neurology-carotid-artery-imaging-for-simple-syncope/",
        "extension": [
          {
            "url": "http://my.hooks.org/fhir/102/StructureDefinition/source-type",
            "valueCode": "Research"
          }
        ]
      },
      "extension": [
        {
          "url": "http://my.hooks.org/fhir/102/StructureDefinition/related-resources",
          "valueReference": {
            "reference": "DiagnosticOrder/C7ACB00B-C3B6-45E8-B469-CDCDABF905F6"
          }
        },
        {
          "url": "http://my.hooks.org/fhir/102/StructureDefinition/related-resources",
          "valueReference": {
            "reference": "Condition/3F244E7D-2A75-4BF8-900A-FA4FD67C29F9"
          }
        }
      ]
    }
  ],
  "decisions": {
    "create": [],
    "delete": []
  },
  "extension": [
    {
      "url": "http://my.hooks.org/fhir/102/StructureDefinition/request-reference",
      "valueId": "F59F2521-9653-4894-B0CB-09A7652B1FF6"
    }
  ]
}

[isaacvetter]

Hey @robs16,

Extensions are custom. It's perfectly reasonable to add in new, system-specific fields in an integration and even to use them across multiple implementations.

The concern with your above approach is that they enable the possibility of standardizing extensions and explicitly using the FHIR approach. It's not obvious that we need to either standardize extensions and in other aspects of the CDS Hooks specification, we've specifically avoided copying FHIR for the sake of copyign FHIR. Rather CDS Hooks has stayed simpler, with more elegant structures because we haven't copied FHIR.

To that end how about this:

• The CDS Hooks spec reserves the name "extension".
  • the content and datatype of this object is dependent upon the implementation.
  • extension can live at any level in any CDS Hooks message.
  • implementors should ignore any object named extension that they don't know about.

Isaac

[robs16]

With respect to extensions are custom. I am not under the impression that extensions will be custom for each pair of service and consumer. In most cases, certain consumers will require a particular set of extensions from all services, and a particular service will provide a set of extensions to all consumers. Over time, some of those extensions will become common among many services and many consumers before they are added to the spec. Also over time, many extensions may be added that are somewhat similar, but not semantically equivalent - ie the risk of extension name collisions will increase.

I actually think the FHIR approach for extensions is very elegant, though it does have its limitations. It solves the above issues and has already stood the test of (at least some) time.

In any case, an extension needs an identifier. This can be the field name (if it is long and doesn't conflict). However the FHIR approach of a list of objects, where the object contains a url is a bit cleaner IMHO.

[brynrhodes]

So we have two proposals on this, one is to use a scheme similar to the FHIR extension model, and the other is to simply reserve the name "extension" and leave the details out of scope for the spec. In the interest of simplicity, I suggest we adopt the simpler approach, and note that an implementation would be free to use a FHIR-like extension model within the "extension" element.

[js8080]

I left a comment on @brynrhodes commit .

However, I wasn't sure if that was the right place so I am posting my comment here as well:

Can we model this more like a FHIR Extension (http://hl7.org/fhir/extensibility.html)? I don't think we have to get quite as complicated as FHIR's extensibility model but using a key/value pair would be much more preferable than using dynamically named JSON properties.

For example, this is readable/writable using a standard JSON formatter/writer and does not require customizing out-of-the-box / off-the-shelf JSON libraries:

"services": [ { "extension": [{ "url": "http://domain/example-client-conformance", "value": "http://my.hooks.org/fhir/102/Conformance/patientview" }, { "url": "http://domain/example-client-another-extension", "value": "another-extension-value" }] }

Notice that I simplified this a little from the FHIR Extension type in that I am just using one "value" property instead of "valueInt", "valueDecimal", "valueString", etc.

To conclude, I think it is important that we stop requiring customization to off-the-shelf JSON libraries when adding support for new features in CDS Hooks as it will make implementation of those features more difficult for everyone and therefore, slower to reach users (customers).