I filed Issue #78, “Decide on and implement uniform approach to normative keywords”:
We adhere to RFC 2119 in that we distinguish three categories of normative statements:
· The statement is an absolute requirement.
· There might be a valid reason to ignore the statement.
· The statement is truly optional.
We also adhere to RFC 2119 in that we use the (capitalized) keywords SHALL and MUST to designate "absolute requirements." (RFC 2119 also allows "REQUIRED", but we don't currently use it.) We treat SHALL and MUST as absolutely synonymous, and we choose between them on a case by case basis, purely on the basis of which one reads most naturally in English.
Stefan and Ykaterina have both said that they find it easier to distinguish MUST from SHOULD than to distinguish SHALL from SHOULD, and Stefan has suggested using MUST exclusively. On the other hand, if we want to be ISO ready, we should not use MUST in this sense, since "must" means something else in an ISO spec. On the other other hand, Stefan cites the OData spec, which was written to OASIS standards, and then accepted without change by ISO.
We need to establish, and then revise the spec to conform to, a policy for keyword usage that meets the following requirements:
· Maximize understandability for both native English speakers and non-native speakers.
· Maximize consistency of _expression_ throughout the spec (this improves understandability except in cases where an arbitrarily imposed consistency leads to strained _expression_).
· Make the spec ISO ready (if the TC agrees that this is a goal, which it has not yet explicitly done).
Larry
From: Michael Fanning [mailto:Michael.Fanning@microsoft.com]
Sent: Friday, January 12, 2018 12:47 PM
To: Larry Golding (Comcast) <larrygolding@comcast.net>; 'Chet Ensign' <chet.ensign@oasis-open.org>; 'Mr. Stefan Hagen' <stefan@hagen.link>
Cc: sarif@lists.oasis-open.org; 'OASIS TAB' <tab@lists.oasis-open.org>
Subject: RE: [sarif] Re: SHOULD => SHALL in "Security implications"
Yes. Nice analysis.
I think there is a clear case for consistency here, as far as we can achieve it. There’s no doubt that consistency will minimize understandability issues. Understandability is a difficult problem, obviously, every person may find different things more or less understandable. It is clear from the information that Chet and David have provided that MUST is a problematic term from the ISO compatibility standpoint. Btw – I think it’s possible our spec does not require the use of MUST as ISO defines it (though we’ll want Larry to confirm this point in order to accept it as a fact).
If we assume the above is accurate, I think the following approach makes sense:
- Ensure that our spec does the best job possible articulating definitions of terms in normative statements. We do this already, but we should be as thorough as possible.
- I suggest we make sure that we use a consistent set of UPPERCASE terms (SHALL, SHOULD, etc.) and avoid uppercasing any terms that are synonymous. That is, pick one of MUST/REQUIRED/SHALL
- If we proceed with SHALL, we have no work to do from an ISO compatibility standpoint. If we proceed with MUST, we can add clarifying text (or just be cognizant of this fact to drive some future transformation of the content) that our MUST is synonymous with ISO SHALL.
I am also very sensitive to issues of understandability. In this case, however, my personal opinion is that it is in our best interests to consistently use SHALL, because this term is commonly defined across both Oasis and ISO. But also because I have observed that even native English speakers are confused by the use of these terms and require explanation of them (the distinction between SHOULD and SHALL in particular). This underscores that no one solution will be perfect and that we are obligated to do as much work as possible to describe/point people to reference materials that explain the approach.
Michael
First of all, I want to assure you that as Editor, I take the needs of non-native English speakers very seriously, and will work hard to make sure that the spec is understandable to everyone.
We are really discussing three things here:
- The literal meaning of the words in the spec.
- The understandability of the words in the spec.
- Making the spec ISO-compatible, if we all decide that is important.
I would like to address each of these things in turn.
1. The meaning of the words
Stefan wrote:
What I would be very reluctant to follow are below (or in other
mails of this thread) noted specific differentiations in effective
meaning of (RFC 2119 synonyms) i.e. I want to preserve:
MUST == REQUIRED == SHALL
relations ...
For me a spec that utilizes more than these three dimensions (MUST,
SHOULD, MAY) is suspicious at least…
I want to be very clear, that in the spec, I use only three categories of normative statements, as described in RFC 2119:
- The statement is an absolute requirement.
- There might be a valid reason to ignore the statement.
- The statement is truly optional.
Furthermore, in the spec, I do indeed treat MUST == REQUIRED == SHALL as absolute synonyms, again as described in RFC 2119.
In my email below, I was only explaining why I sometimes chose one or another of those synonyms: I try to choose the one that reads most smoothly in English, the one that sounds most natural to a native English speaker. But, in terms of normative requirements, the meanings of those synonyms are exactly the same.
2. Understandability
Stefan and Katrina have both said that they find it easier to distinguish MUST from SHOULD than to distinguish SHALL from SHOULD. I’m certainly open to trying to rephrase SHALL to MUST throughout, but I’d like to first get more guidance on that, both from the OASIS Keyword Guidelines that Chet sent, and from Chet himself. I’ll file an issue and do some research here.
3. ISO Compatibility
I need to go back and re-read the ISO directives. Earlier in this thread, Michael mentioned that ISO treats MUST differently from SHALL. If that’s the case, I couldn’t just change SHALL to MUST everywhere.
Stefan, I see that you mentioned the OData spec as an example of a spec that uses keywords in a way you found understandable, and also was accepted without change by ISO. So as part of my research, I will also look at that OData spec (of course I won’t try to read the whole thing! 😊).
Thanks,
Larry
From: sarif@lists.oasis-open.org [mailto:sarif@lists.oasis-open.org] On Behalf Of Chet Ensign
Sent: Friday, January 12, 2018 6:19 AM
To: Mr. Stefan Hagen <stefan@hagen.link>
Cc: sarif@lists.oasis-open.org; OASIS TAB <tab@lists.oasis-open.org>
Subject: Re: [sarif] Re: SHOULD => SHALL in "Security implications"
On Fri, Jan 12, 2018 at 9:12 AM, Mr. Stefan Hagen <stefan@hagen.link> wrote:
Thank you Katrina!
for not letting me stand there alone in that language corner :-)
Sometimes we are reminded, that the world is not switching to English,
and the British and Americans do not have to fight against or for
extra "u" letters and the like or the order of er vs. re in word endings
or what exactly expiry means ...
*but* the world is forming a new language starting from English! ...
and as spec writers introduce meta languages like the MUST et al.
on top.
In OASIS and IETF we use RFC 2119 as updated by RFC 8174 - or
like every fresh workproduct will have in the boilderplate / frontmatter:
"""
1.2 Terminology
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,
“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in
this document are to be interpreted as described in [RFC2119] and [RFC8174].
"""
esp. the "[] only UPPERCASE usage of the key words have the defined
special meanings." part in RFC8174 emphasizes, that this is not
natural language.
I always understood this as highlighting or tagging with a code.
Clear understanding for implementers in exactly these situation
where (we) the spec writers point out something via MUST, SHOULD
or MAY justifies breaking the "reading flow".
Could we maybe also try to white instead of blacklist where possible
(which would help the reader a lot, as every "not" or "NOT" comes as
an extra evaluation task :-)
For me a spec that utilizes more than these three dimensions (MUST,
SHOULD, MAY) is suspicious at least provoking the question if another
spec staying with these three terms would lead to better interoperable
and conforming implementations.
I would suggest to focus on what we want and serve the OASIS rules,
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 and is now an ISO standard -
for free.
And much clearer in my opinion as with some IEEE -> ISO standards,
where to me accessibility and status of the originating IEEE standards
is not always clear, the OASIS OData standard documents are still the
accepted, and best navigateable form to "use" it ...
If you guys with native English reading capabilities perceive hurt
when reading clumsy UPPERCASED terms (MUST vs. SHALL) like Laurence
explained very well, IMO we should find a way that is good for the
group, easy to read and understand for all.
What I would be very reluctant to follow are below (or in other
mails of this thread) noted specific differentiations in effective
meaning of (RFC 2119 synonyms) i.e. I want to preserve:
MUST == REQUIRED == SHALL
relations ...
I wrote this in a (small) browser rendered html "textarea", so
albeit I wrote this mail a few times before sending, some hard to
understand text may have slipped through, and if so, I already feel
sorry for that.
All the best,
Stefan.
On 12/01/18 06:44, O'Neil, Yekaterina Tsipenyuk wrote:
> As a non-native speaker, I have to say I had to pause for a second to think about what the proposal of changing SHOULD to SHALL means. I did infer the meaning of the change correctly, but I think it was mainly due to the fact that the attention was drawn to making this change. That is, if I was just reading the final version of the spec, I would have not picked up on the connotation.
>
> I think the options listed below would not cause a confusion for me though.
>
> k
>
> -----Original Message-----
> From: sarif@lists.oasis-open.org [mailto:sarif@lists.oasis-open.org] On Behalf Of Michael Fanning
> Sent: Thursday, January 11, 2018 10:40 AM
> To: David Keaton <dmk@dmk.com>; Larry Golding (Comcast) <larrygolding@comcast.net>; 'Mr. Stefan Hagen' <stefan@hagen.link>; sarif@lists.oasis-open.org
> Subject: RE: [sarif] Re: SHOULD => SHALL in "Security implications"
>
> Hm, interesting. Use of MUST in our case certainly doesn't conform to ISO's notion of it.
>
> I see the following list of ISO acceptable alternates to SHALL NOT. Not sure whether any of these meet Stefan's criteria of being more accessible to non-native EN speakers.
>
> is not allowed [permitted] [acceptable] [permissible] is required to be not is required that … be not is not to be need not do not
>
> Again, back to this specific issue. I wonder if we shouldn't inject a note that amplifies on the spec language (which refers to SHALL NOT). We'd want to emphasize that it is really not acceptable for SARIF to contain executable code but that due to lack of controls on user-input and/or guaranteeing the integrity of a SARIF file and the dangers of failure to sanitize, consumers can't assume that the spec has been met for this case. It is not acceptable for producers to inject executable code into SARIF markdown. It is not acceptable for consumers to fail to sanitize.
> ... [ -- - 8< - -- ]
--
/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