Re: Research on keyword usage

Hi Larry,

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.

Best,

/chet

On Tue, Jan 16, 2018 at 2:23 PM, Larry Golding (Comcast) <larrygolding@comcast.net> 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.⁴ 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.

BUT!

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 -
for free.

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!
Larry

/chet
----------------
Chet Ensign
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

sarif message