Thanks for clarifying that ISO will accept an OASIS submission “as is” for initial publication, but that they would require subsequent versions to conform to their format.
Yes, I was aware that there were more differences between OASIS and ISO format than just normative keywords. The first draft of the spec actually was in ISO format (because I wrote it before we decided on OASIS), and it took me a few hours to make the changes.
So, here is what I propose to do:
- David: Would you please add an agenda item for the next TC meeting to discuss whether “OASIS readiness” is an explicit goal of the first public release of the SARIF standard.
- Patrick: Since you are already assessing ISO requirements in the context of ebXML, would you please let us (the SARIF TC) know what you find? I’m particularly interested to know if Chet’s understanding is correct (namely, that the first ISO standard can be just “the OASIS standard with a new cover page”, but that subsequent versions need to be revised to ISO standards). That would make it burdensome to keep the OASIS and ISO versions in sync, right?
- SARIF TC: I propose to leave the existing wording in the spec as is. The Terminology section states explicitly that capitalized SHALL and MUST have their RFC 2119/8174 meanings, and the spec does indeed use those keywords as defined in RFC 2119. I think the capitalization is sufficient to alert both native non-native English speaking to the special meaning of those terms. And if we were going to standardize on one or the other, ISO conformance would have us use SHOULD throughout.
- David: Would you please add an agenda item for the next TC meeting to allow discussion of #3? I will move that the wording be maintained, and that will give anybody the opportunity to speak in debate on that point.
Thank you all!
From: email@example.com [mailto:firstname.lastname@example.org] On Behalf Of Chet Ensign
Sent: Tuesday, January 16, 2018 11:56 AM
To: Larry Golding (Comcast) <email@example.com>
Cc: firstname.lastname@example.org; OASIS TAB <email@example.com>
Subject: [sarif] Re: Research on keyword usage
First, thanks for all this due diligence! I suspect that others will benefit from your clarification.
> So Chet, could you please clarify? Are the ISO and OASIS versions of the OData standard identical – do they both use RFC 2119 keywords? [NOTE: I’d rather not have to buy a copy of the ISO standard to find the answer!] Is the OASIS keyword guidelines FAQ wrong, or out of date, on this point?
I copied the TAB on my reply in case Patrick or someone else wants to weigh in.
First, I do not think OData has been approved a second time at ISO. I just downloaded the copy (available for free) and it is simply the ISO cover pages on top of the OASIS spec. When an initial PAS submission is made, ISO accepts and publishes it as is. My understanding is that on the next submission - e.g. version 2.0 - the copy would have to conform to ISO requirements. Note that these are not just keywords - there are section requirements and some other fine tuning tweaks as well.
Second though - we are not entirely sure of ISO expectations. Patrick is working those out now as we prepare some ebXML specs. He should know how this all works in the not too distant future.
Bottom line: if you expect that you'll want to submit to ISO, you can't go wrong by sticking with the keywords that you know will be accepted. Since ISO's use of MUST differs (in what seems a meaningful way) from RFC2119, I would be careful to use both it and SHALL in a way that will meet ISO expectations to avoid any difficulties.
On Tue, Jan 16, 2018 at 2:23 PM, Larry Golding (Comcast) <firstname.lastname@example.org> wrote:
I’ve now read the various references on keyword usage. I also examined OData v4.0 Part 1 Protocol (the OASIS standard), as Stefan suggested. Here’s what I know so far:
- RFC 2119/RFC 8174 require normative keywords to be in upper case. ISO Directives Part 2 permits normative keywords to be upper case. So if you want to be both OASIS-conformant and ISO-ready, use upper case. We already do that.
- RFC 2119 allows MUST as a synonym for SHALL. ISO Directives Part 2 does not allow MUST. So it seems that if we want to be ISO-ready, we should use SHALL everywhere (but hold on! I’m not done yet…)
- The OASIS keyword guidelines FAQ say this:
As an editor, why would I use ISO keywords instead of RFC in a specification?
If you are planning on submitting an OASIS TC Specification or Standard to ISO/IEC, you can use [RFC 2119] keywords on a first submission.4 However, on subsequent submissions, you will be required to conform to [ISO/IEC Directives], which will require use of ISO keywords.
So again, it seems that if we want to be ISO-ready, we should use SHALL everywhere, because otherwise ISO will make us change it.
- The OData v4.0 Part 1 Protocol (the OASIS standard) uses MUST everywhere.
- In an earlier thread on this topic, Stefan wrote:
as OASIS is a public accepted submitter to ISO and with OData as an
example, we had no trouble after we made the OASIS Standard stage,
to also submit unchanged to ISO, fill in a form, where OASIS stated,
that the TC would continue to work on future versions, and then we
waited for the many months election period and the bunch of OData
standards was concat and wrapped as i[s] and is now an ISO standard -
That makes it sound like we did not have to change to ISO keywords, which contradicts what the OASIS keyword guidelines FAQ says.
So Chet, could you please clarify? Are the ISO and OASIS versions of the OData standard identical – do they both use RFC 2119 keywords? [NOTE: I’d rather not have to buy a copy of the ISO standard to find the answer!] Is the OASIS keyword guidelines FAQ wrong, or out of date, on this point?
Thanks for your help!
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society
Primary: +1 973-996-2298
Mobile: +1 201-341-1393