Pulse check: formal verbiage (SHOULD, SHALL, MAY, etc) in the specification?

[Kevin Shekleton]

Hi everyone,

We have had a couple of people comment on our lack of formal verbiage in the CDS Hooks specification. For instance, words like SHOULD, SHALL, MAY, MUST, etc (see rfc2119 and FHIR's conformance language). Also see issue #92. We'd like to get a pulse check on the community's feelings on this type of language.

- How important is this formal language to the CDS Hooks specification?

- Do you feel like this should be expressed in the upcoming 1.0. release? Or, can it come in a later release?

- Are there specific instances of where this formal language would have aided your implementations/integration? If so, can you be specific?

If we adopt this formal language, we feel that the Open API (Swagger) document is the best fit for this formal language as it already provides us a formal grammar to express the CDS Hooks specification/API. Additionally, if you feel strongly about the inclusion of this type of language, we would love to have you help incorporate this into the spec by working with us on a pull request! :-)

Thanks!

Kevin

[Josh Mandel]

Thanks Kevin! The fact that we're having this conversation is a good sign for project health, in my book.

I don't feel strongly about whether we should introduce formal language at this stage. My general leaning is to move towards a 1.0 publication with clear (but potentially less formal) language and tighten this up over time.  We should be very careful to address specific points of confusion or ambiguity regardless of whether we adopt formal, capitalized conformance descriptors :-)

I'm not sure I followed what you said about the connection between formal language and our Swagger/OpenAPI formatted specification. Are you suggesting that we might point to our OpenAPI YAML file as the official source of truth, and then treat our narrative HTML site as merely descriptive "color"? Or if you meant something different, could you clarify? (In general I like the idea of using our OpenAPI specification as a source of truth, although it can be hard to provide overall context within that format and I expect that there will be nuances that are not well represented in the open API specification, meaning that we would rely on the presence of narrative descriptions/comments even inside of the JSON/YAML doc. If I was going to recommend a concrete path forward, it would be to keep the narrative specification as our source of truth moving into 1.0, and then evaluate what it would take to shift in a following release.)

--
You received this message because you are subscribed to the Google Groups "CDS Hooks" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cds-hooks+unsubscribe@googlegroups.com.
To post to this group, send email to cds-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/cds-hooks/4523ad6a-6ea5-4e6c-8735-f86645619082%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Grahame Grieve]

hi Kevin

I think that introduction of formal verbs is inevitable, but it shouldn't (SHOULD NOT) be done in a hurry.

So not 1.0

There's 2 parts to this about formal language - one is using the verbs correctly and carefully, 

and the other is drawing out specific conformance statements. Both need care, and both

are useful for resolving lack of clarity/

I don't think that the swagger document is related to the question, personally. To take

a recent discussion, and remembering pre-fetch data on a hook instance, you might

want the spec to say:

* CDS Servers SHALL remember the pre-fetch data associated with the first 

  invocation of a hook instance

(actually, I hope we don't say that, but it will do as an example)

This is not something you can say in an OpenAPI document.

Grahame

--

You received this message because you are subscribed to the Google Groups "CDS Hooks" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cds-hooks+unsubscribe@googlegroups.com.
To post to this group, send email to cds-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/cds-hooks/4523ad6a-6ea5-4e6c-8735-f86645619082%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

-----
http://www.healthintersections.com.au / gra...@healthintersections.com.au / +61 411 867 065

[Chuck Feltner]

Hi Kevin,

 

Thanks for all your efforts on the specification. Here is some input on the questions.

 

- How important is this formal language to the CDS Hooks specification?

 

I think it is important that the specification clearly shows which fields and functionality are required and which are optional. The formal language is definitely a good way to specify that. It seems that in most places the specification states that it is optional using descriptive text which seems to work fine. For the fields we could also do this with a simple required/optional column in the tables.

 

- Do you feel like this should be expressed in the upcoming 1.0. release? Or, can it come in a later release?

 

I think showing the required/optional needs to be expressed in the 1.0 release whether this is done with formal language or some other means.

 

- Are there specific instances of where this formal language would have aided your implementations/integration? If so, can you be specific?

 

Prefetch, EHR Trust JWT, and Access Token. Some examples in the current version of the specification.

1. Discovery response, is the prefetch field optional?
2. Service request, is the encounter id, context, prefetch optional?

 

Thanks,

   Chuck

--

You received this message because you are subscribed to the Google Groups "CDS Hooks" group.

To unsubscribe from this group and stop receiving emails from it, send an email to cds-hooks+...@googlegroups.com.