Stream: cds hooks/github
Topic: docs / Issue #92 Specification format improvements
Github Notifications (Sep 11 2017 at 06:16):
bvdh opened Issue #92
In order for the current CDS-Hooks specification to become a proper standard, We need formalize the document on the following elements:
- to be able to refer to a specific version. Please indicate the version of the spec in the documentation.
- the specification is written in a descriptive manner. This makes it hard to distinguish between mandatory, optional and recommended specification elements. One way to address this it to follow is to label them with SHALL, SHOULD, MAY type of statement as is defined by the IETF guidelines on this topic (https://www.ietf.org/rfc/rfc2119.txt)
- where the specification refers to elements defined elsewhere, please provide a reference and version indication.
Github Notifications (Sep 12 2017 at 17:59):
brynrhodes labeled Issue #92
Github Notifications (Sep 12 2017 at 19:18):
Per discussion at the Sept WGM (Tue Q2), a more formal/crisp specification will be very important when CDS Hooks goes through the HL7 ballot/publication process. This will also help remove ambiguity from implementers.
@bvdh - If you have specific examples of MUST/SHALL/MAY/etc that are important to add, please add them here to make sure we get them specified in the spec.
Related to this, @bvdh also pointed out that the Swagger API will need to be versioned and 'released' in order to reference it in the spec.
Github Notifications (Sep 13 2017 at 04:05):
olbrich commented on Issue #92
@kpshek It may also be a good idea to embed version metadata in the actual data payload so it is possible to determine which version a message is conformant to at run time.
Github Notifications (Nov 26 2017 at 15:14):
@bvdh - We've addressed one of your comments:
to be able to refer to a specific version. Please indicate the version of the spec in the documentation.
We've now clearly indicated the specification vs the rest of the documentation/website. The specification will be versioned and the 1.0 draft is available at http://cds-hooks.org/specification/1.0/ (see PR #115 for this change). The rest of the documentation will be un-versioned as it will support all version(s) of the specification and be a living document.
Additionally, we moved the Swagger API into the
docsrepository so it can be versioned and live alongside the specification.
Last updated: Apr 12 2022 at 19:14 UTC
