Clarification on datatype of Context and Prefetch properties

[mattvarghese]

With clarifying that Context is an object and not an array, Context and Prefetch are both similar JSON Objects which have member properties as FHIR objects, and are therefore very much alike, except for Context is defined by the hook and Prefetch by the CDS service. So far, this is great.

However, with moving patient and encounter into Context, this opens a new can of worms. Now some properties in the Context are string - patient and encounter, whereas others are FHIR objects.

1. Will there be other properties that are not FHIR objects?
2. Will we have properties with a different datatype than string or FHIR object?
3. Will prefetch also contain non FHIR object properties?

It would be great from a CDS-Hooks Client / EMR perspective to have these clarified.

[mattvarghese]

Likewise, at the connectathon there were a few different CDS Services that needed the Patient resource as prefetch. But each of these used a different property name for the patient resource. One was just "patient," another was "requestedPatient," and the example in the specification uses "patientToGreet." This does not play nicely with the objective in the spec:

The EHR may compute an efficient set of prefetch templates from multiple CDS Services, thereby reducing the number of network calls to a minimum

since to make a consolidated prefetch template, now the patient may need to be included three times under three different names.

How do we resolve this? And should this be also scoped under this issue, or does this merit opening a new issue?

[jmandel]

Agreed we should clarify — and my preference would be to leave this open, at the CDS Hooks overall specification level, to say that Context values can be any valid JSON datatype (and that specific hooks will provide constraints/guidance on their own Context values).

[kpshek]

In the specification we do say that the Context values are any valid JSON datatype (emphasis mine):

"Description: The value of the property in the context JSON object, expressed both as the JSON data type as well as a functional description of the value. If this value can change according to the FHIR version in use, the description SHOULD describe the value for each supported FHIR version."

If we can make this more clear, I'm open to suggestions.

[kpshek]

3. Will prefetch also contain non FHIR object properties?

IMHO, prefetch should be reserved for FHIR data exclusively (extensions aside)

[js8080]

Aren't we really risking the robustness of the specification by allowing anything in the Context element? Isn't there a risk that CDS Hooks services (or clients) will put things in there that maybe shouldn't be or do so in an unorthodox manner that would cause problems with reusability across different servers?

For example, one server could say "I want an array of Encounter IDs in format X" and another server could say "I want an array of Encounter IDs in format Y". Now a client that wants to connect to both servers has to do development to support both when they probably want the same thing and could have done it consistently.

Just feels a little messy to me and like we're kicking the can down the road instead of coming up with smart recommendations now. After all, if someone needs to add something outside the scope of the specification, isn't that what extensions are for?

[robs16]

So from my perspective, for approved hooks, prefetch is FHIR only, context is defined per spec and agreed by the community (ie voted on). This should be prescriptive enough to stop format X, format Y issues.

For proprietary hooks, do as both parties agree assuming it doesn't change pre-defined structure defined in the spec - If on my proprietary 270-hook, I want a context to include a X.12 message as a string (or the JSON equivalent) and a prefetch which provides an encoded CDA in a string, I am stretching the structure a bit, but in this case I am using the interaction model of cds hooks, which is useful with or without FHIR. Of course, such a proprietary hook cannot become part of the standard and would require proprietary coding on both sides.

[mattvarghese]

My way of looking at it is to try to find use cases (standard ones - I am ignoring non-standard hooks for now) for such data of type other than FHIR object in the Context. Can we enumerate some good clinically valid use-cases which will justify us taking the effort?

[kpshek]

This is great discussion everyone!

@mattvarghese - I agree with @robs16 and think he did provide some good napkin sketches of potential hooks that would make use of non-FHIR data.

The most compelling reason that prefetch leverages FHIR data is because our prefetch template is expressed as a FHIR query path thereby predicating that the result would be FHIR. For context, there is no similar constraint. Additionally, I don't see a reason why context cannot contain any valid JSON datatype. Context is workflow/EHR dependent (we obviously want to align/standardize common hooks like patient-view) and the contextual data may fall outside of FHIR.

I don't feel like we're shirking our responsibilities here. I think defining context as we've done today is prudent and, until we start seeing the hooks defined by the community, we can start promoting concrete best practices. Until we have a far more robust hook catalog, I don't see increasing our initial release scope to embark on an effort to determine such guidelines, recommendations, or best practices nor establish what an official hook registry may contain. In the latter case, we made a conscious design to break the individual hooks out of the specification -- both so that we can add/modify hooks without releasing a new specification version as well as the ability to defer some of these questions which will remain unanswered until we see more hook definitions being prototyped and implemented in production.

In an effort to keep these ideas flowing around hook design best practices, I've started this Wiki page. Please feel free to add to it and suggest additional best practices.