Communicate CDS Hooks specification version

[bkaney]

Are there any thoughts on how to advertise/handle the CDS Hooks service version?

This could be handled as part of the service discovery -- e.g. include the version as an attribute in the cds-services payload.

{
  "services": [
    {
      "hook": "patient-view",
      "title": "Static CDS Service Example",
      "description": "An example of a CDS service that returns a static set of cards",
      "id": "static-patient-greeter",
      "cds-hooks-version": "1.0.0"
    }
  ]
}

[kpshek]

@bkaney - Can you elaborate on why you think this would be valuable?

For instance, we don't define this today with SMART apps. If a CDS Service is offered as software as a service (SaaS), and every company I've talked to is working under this model, then I'm not sure why version needs to be exposed.

If the CDS Service provider wants to explicitly version its services, this would be best put in the id field.

For instance, in your above example the CDS Service would be available at https://example.com/static-patient-greeter. So, when you version it to 2.0 it's still at the same URL. If your intention is to allow the EHR to make a purposeful decision to move to 2.0 then you'd want the URL to change too. So, the id could be static-patient-greeter-2.0 making the URL https://example.com/static-patient-greeter-2.0

Thoughts?

[bkaney]

I see the confusion. It's not about the cds service version, it's the CDS Hooks version the service conforms to. My example is misleading, so I updated it.

[robs16]

I agree that the version of CDS Hooks is relevant. However wouldn't that also potentially impact the fields/etc in the discovery endpoint? Do you see mixing versions of cds hooks (ie 2 services, 1 with hooks v1 and another with hooks v2)? If not, perhaps it should at the same level as "services". This should probably also align with how to represent the FHIR version that the service supports - #3.

[olbrich]

possible options:

1. version the api url.. [base_url]/v1.0/cds-services and then redirect [base_url]/cds-services to the latest version available. Not great since it ties you to a particular url, but it's not terrible since it's unlikely that others will be storing the URL in a large number of places.
2. add cds-hooks-version to the cds-service definition. Also not great because you need to parse the definition in order to find out what version it needs.
3. use the Content-Type / Accept header approach to negotiate a mutually supported version between the client and server.

see #154

[kpshek]

Some options I can imagine:

• The CDS Service definition returned from the Discovery call contains the CDS Hooks specification version supported
• Every call made by the EHR contains the CDS Hooks specification version. This allows the CDS Service to respond accordingly (for instance, perhaps the Discovery response flexes to only return CDS Services that can handle the particular CDS Hooks specification version in use).

Furthermore, I'll echo @olbrich's suggestion of a new JSON field or HTTP header are both options to communicate the specification version.

My proposal is that we do not address this today. We only need to address this once we introduce a new version of the CDS Hooks specification in which the CDS Service needs to change its behavior based upon the specification version in use. If we introduce a new specification version that contains breaking or other changes which necessitate its communication, we can simply add this per the above options. The absence of this version information just means we're dealing with pre-specification versions in which this information doesn't matter (eg, 1.0).

If the community is OK with this proposal, we'd close this issue and simply re-open it if we end up needing to address this due to a future specification change.

[robs16]

I'll disagree that we don't need to address this today as Stanson Health's solution is already providing multiple versions in production. The reality that the movement of the standard is rather slow, resulting in either un-official versions (which I have 2 of now) or extension needs which get augmented over time both on the caller and service ends. For example, the change from patient and encounter in the main request to being part of the context was a significantly breaking change - I realize the spec isn't official yet, but not allowing early implementations (and thereby multiple versions) leads to a chicken and the egg problem. At the moment URL differences are used, in part to allow easy movement by the EMR from one version to the next with minimal support by the service as well as supporting 'custom' versions on a one-off basis.

With respect to every call containing the Hooks specification, I believe this still should require the version(s) supported shown in the discovery or via some other mechanism. Ideally that would be coupled with the specification details in some form, such that an implementer could access those details and build their interface to the service without additional documentation.

As mentioned above, this and the FHIR version (which we certainly have 2 standards and both in production to various degrees) should be implemented similarly.

Ultimately I don't think this is a particularly hard issue to solve, and I really don't see it as controversial - unless the standard is a dead-end, there will be multiple versions.

[bkaney]

FWIW, since the return of the discovery call is also subject to variations across CDS Hooks versions, I'd opt to expose the version as an HTTP Header.

[mattvarghese]

I just want to add here that we are also now affected by this. We have released code where user is at the top level. However, user has now been moved to the context. Yet there is no version or any kind of differentiator we can include to allow the CDS Service to determine whether the payload has this change or not, (short of looking to see where the user is).

So adding myself also on the list of affected parties requesting some capability on this front.