OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

csaf message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [csaf] Making progress on documenting CSAF specification

Thank you for creating this, Eric! I also made a few minor edits to the CSAF  2.0 initial draft document. However, following the guidelines you provided below and in the document makes complete sense. I have added this to the agenda for todayâs meeting. 


Omar Santos
Email: os@cisco.com
Phone: 919 476 6152
PGP: https://keybase.io/santosomar

On Apr 21, 2020, at 7:42 PM, Eric Johnson <eric@tibco.com> wrote:

Item 1:
I've created a document to track what is to be done, and what is left to do, and notes about what I'm doing, including some of the details in this email. It is in the same Google Drive folder as the specification itself. Email me if you want a link, and cannot find it.

Item 2:
Changing the document so that most of the content is non-normative. I'm changing it so that the normative content is highlighted with normative statements (such as "the value of the ____ property MUST ....") that use RFC 2119 keywords.

Item 3:
One issue relates to statements like this one about the "title" of the document: "This string SHOULD be a definitive canonical name for the document, providing enough descriptive content to differentiate from other similar documents, ideally providing a unique

While this statement uses the RFC 2119 keyword "SHOULD", it cannot, in fact, be a normative statement. A normative statement could be something like: elements of "product_ids" array must refer to a product identifiers defined under the "product_tree" element. This constraint cannot be enforced by JSON schema..., and so needs to be called out in the specification as a normative constraint.

However, the statement about the title is still an expectation for the author of contents that go into the document. As such, it is really guidance text for a tool that is prompting for input into material being provided for a document. As I started working on this, it occurred to me to flag and capture these statements as constraints on the author.

Net result: the document will have a section for normative constraints, and a section on author guidance.

Does that work for people?


Attachment: signature.asc
Description: Message signed with OpenPGP

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]