Keyword Guidelines for OASIS Specifications and Standards

Version 2.0

This document provides guidelines for using keywords based on the IETF definitions (BCP 14, RFC 2119, etc.) and the ISO/IEC Directives when writing specifications. It includes a mapping table between the two keyword types to assist editors changing a specification from one style to the other. The target audience is primarily specification writers and project team members.

Status: TAB-approved deliverable with revisions in 2021.

Editors: Patrick Durusau, Paul Knight

1 Introduction

Keywords establish the requirements that implementers follow in conforming to OASIS specifications and standards.

This guide explains how to use two of the more popular keyword sets, [IETF BCP14] (consisting of both [RFC2119] and [RFC8174]) and [ISO/IEC Directives]. After explaining the basic rules for each keyword set, we provide examples of the keywords in use in OASIS specifications.

In general, OASIS standards-track documents should use the capitalized IETF keywords, unless the developers expect to submit the final OASIS Standard to a standards body requiring the ISO/IEC keywords.

1.1 Changes from earlier OASIS guidelines – IETF keywords

Incorporated IETF RFC 8174 and the expansion of BCP 14 to include RFC 8174 as well as RFC 2119.

Beyond simply adding a reference to RFC8174, the expansion of BCP 14 involves changes to the text describing the use of keywords in a specification:

  • Adds the keyword phrase “NOT RECOMMENDED”
  • Extends the text describing the usage of RFC 2119 or BCP 14 keywords to include the phrase “when, and only when, they appear in all capitals, as shown here.”

1.2 Changes from earlier OASIS guidelines – ISO/IEC keywords

Updated the reference for ISO/IEC keywords from the Fifth Edition to the Eighth Edition. Beyond simply updating the reference, this incorporates changes to the text describing the use of ISO/IEC keywords in a specification:

  • Deprecates “need not”
  • Adds “may” and “may not”.

2 Keywords in OASIS TC specifications and standards

2.1 Introduction to keywords

The term keywords as used in OASIS specifications or standards means terms specified either by [IETF BCP14] or the [ISO/IEC Directives]. Every OASIS specification or standard will choose (and use) one or the other. The two keyword sets are never mixed in a specification or standard.

Keywords identify the requirements for conforming to a specification or standard. RFC 2119 gives the following guidance on keywords (called “imperatives”):

Imperatives of the type defined in this memo must be used with care and sparingly. In particular, they MUST only be used where it is actually required for interoperation or to limit behavior which has potential for causing harm (e.g., limiting retransmissions) For example, they must not be used to try to impose a particular method on implementors where the method is not required for interoperability. RFC2119

For example, ODF 1.2 [OpenDocument-v1.2] went to great lengths to say how the format was written and to specify its semantics. However, not one word was said about how an implementation would accomplish that task. It wasn’t relevant. It could be an in-memory table, graph, key-value data store, etc. The only thing ODF 1.2 constrains is how to interpret the markup and how to write it back out.

Normative contents don’t always use keywords. Often a descriptive or declarative style reads better than an imperative style based on keywords. In that case, such content may still be referred to by a more general statement — e.g., in a conformance clause — where normative keywords are used to clearly indicate what is expected from a conforming implementation.

In a very real sense, ODF 1.2 is a collection of statements about elements and attributes, which are then referred to by keywords, should you want to conform to the ODF 1.2 standard.

For example, under section 19.402 Presentation Node Type, one would not say:

The presentation:node-type attribute MUST specify a node type for an animation element. (incorrect)

Rather, as the standard reports:

The presentation:node-type attribute specifies a node type for an animation element.

The defined values for the presentation:node-type attribute are:

This has the advantage of freeing the author to write in simple, declarative prose and to save the hard part of keywords for conformance clauses.

2.2 Keywords and normative text

“Normative” text includes the parts of a specification or standard that set forth definitions, rules, conformance clauses and other statements that are part of a standard.

By way of contrast, “informative” text contains material that may help understand the standard or give examples of its use, but that don’t have to be followed in order to implement the specification or standard.

The distinction is an important one because keywords cannot appear as keywords in informative text. Readers might confuse purely informative text with normative text if keywords were found in informative text.

Conformance to a standard requires that everyone recognize normative and informative text the same way. Use of keywords in informative text interferes with a uniform reading of text as normative or informative.

Some examples of informative text include: notices, tables of contents, introductions, notes, examples, etc.

2.3 IETF BCP14 rules

2.3.1 Introduction to IETF BCP14 rules

[IETF BCP14] keywords are the most common keywords used in OASIS TC specifications and standards to define normative statements and conformance clauses.

IETF BCP14 keywords are written in UPPERCASE. When IETF BCP14 keywords are written in lowercase, they have only their normal English usage meaning. In lowercase, IETF BCP14 keywords do not state normative or conformance requirements.

WARNING: Changing an IETF BCP14 keyword, such as lowercase “must” to UPPERCASE “MUST”, changes the conformance requirements of a specification. If that happens, it may constitute a Material Change that requires a public review under OASIS rules.

The following section provides the [IETF BCP14] definitions of keywords, along with examples of their use in some existing OASIS specifications.

2.3.2 IETF BCP14 examples in OASIS specifications

2.3.2.1 MUST

Definition in BCP 14

MUST   This word, or the terms “REQUIRED” or “SHALL”, means that the definition is an absolute requirement of the specification.

Example

“A PullRequest signal message always indicates in its header (see Section 5.2.3.1) the MPC on which the message must be pulled. If no MPC is explicitly identified, the default MPC MUST be pulled from. The pulled message sent in response MUST have been assigned to the indicated MPC.”

  • ([EBMS-v3.0], section 3.4.3. Definition and Usage Requirements.)

Discussion

Note that “must” appears in both lower and upper case. In the first sentence, “must” only indicates the intended objective or effect one wants to produce. The second and thirds uses, in upper case, are requirements that must be met in order to conform to the specification.

2.3.2.2 MUST NOT

Definition in BCP 14

MUST NOT   This phrase, or the phrase “SHALL NOT”, means that the definition is an absolute prohibition of the specification.

Example

“OData-defined system query options are prefixed with “$”. Services may support additional query options not defined in the OData specification, but they MUST NOT begin with the “$” or “@” character.”

  • ([OData-Part1], section 6.1 Query Option Extensibility.)

Discussion

Here MUST NOT appears in upper case and announces a requirement conforming to OData.

Definition in BCP 14

SHOULD   This word, or the adjective “RECOMMENDED”, mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

Example

“If the eb:PartyId/@type attribute is not present, the content of the PartyId element MUST be a URI [RFC2396], otherwise the Receiving MSH SHOULD report a “ValueInconsistent” error with severity “error”. It is strongly RECOMMENDED that the content of the eb:PartyId element be a URI.”

  • ([EBMS-v3.0], section .5.2.2.4. eb:Messaging/eb:UserMessage/eb:PartyInfo/eb:From/eb:PartyId.)

Discussion

The use of IETF BCP14 SHOULD and RECOMMENDED are shown by use of upper case. The example specification has numerous uses of “should” in lower case, i.e., in normal English usage. The “strongly RECOMMENDED” does not require “report[ing of] a ValueInconsistent error,” but the implications of not doing so must be understood before making that choice.

Definition in BCP 14

SHOULD NOT   This phrase, or the phrase “NOT RECOMMENDED” mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.

Example

“OData services SHOULD NOT require any query options to be specified in a request. Services SHOULD fail any request that contains query options that they not understand and MUST fail any request that contains unsupported OData query options defined in the version of this specification supported by the service.”

  • ([OData-Part1], section 6.1 Query Option Extensibility.)

Discussion

The example shows a correct usage of SHOULD NOT.

2.3.2.5 MAY or OPTIONAL

Definition in BCP 14

MAY   This word, or the adjective “OPTIONAL”, mean that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein an implementation which does include a particular option MUST be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides).

Example

“The element encapsulates the authorization decision produced by the PDP. It includes a sequence of one or more results, with one element per requested resource. Multiple results MAY be returned by some implementations, in particular those that support the XACML Profile for Requests for Multiple Resources [Multi]. Support for multiple results is OPTIONAL.”

  • [XACML-v3.0], section 5 Syntax (normative, with the exception of the schema fragments)

Discussion

A correct usage of MAY as a keyword, but also an illustration of designating part of a section as normative. Note that OPTIONAL is an alternative to MAY, when required by the syntax of the text.

2.4 ISO/IEC Directives

2.4.1 ISO/IEC Directives introduction

Unlike [IETF BCP14], section 7, “Verbal forms for expression of provisions” of [ISO/IEC Directives] does not require or even discuss the use of upper case forms of its keywords. Using the [ISO/IEC Directives], an author can write keywords in upper or lower case.

The ISO/IEC Directives do define equivalent expressions for keywords, to be used only in certain cases when the preferred form cannot be used for linguistic reasons.

The ISO/IEC Directives define five classes of keywords or “provisions”:

  • requirements
  • recommendations
  • permissions
  • possibilities
  • capabilities

The ISO/IEC Directives provide a table for each class of provision, defining the preferred form and the equivalent expressions.

Writers of OASIS specifications that use ISO/IEC keywords should consult [ISO/IEC Directives] Section 7 for the normative definitions of those keywords. For use with the mapping table in Section 5 below, a synopsis of ISO/IEC Directives Section 7 reads as follows:

Requirements:

  • shall – to indicate requirements strictly to be followed in order to conform to the standard and in which no deviation is permitted. Do not use “must” as an alternative for “shall”.
  • shall not – converse of shall. Do not use “must not” instead of “shall not”.

Recommendations:

  • should – to indicate that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others.
  • should not – converse of should.

Permissions:

  • may – to indicate a course of action permissible within the limits of the standard. Do not use “can” instead of “may”
  • may not – to indicate a course of action is not required. (converse of may) (“need not” was used in ISO/IEC 5th Edition)

Possibilities and capabilities:

  • can – statement of possibility and capability, whether material, physical, or causal.
  • cannot – converse of can.

2.4.2 ISO/IEC Directives examples in an OASIS specification

In the following ISO/IEC examples, note that keywords do not require UPPER case or bolding in order to be keywords. They are keywords by definition, not typography.

The following examples are derived from the OASIS Standard Open Document Format for Office Applications (OpenDocument) Version 1.2 ([OpenDocument-v1.2]). The section numbers listed are from that specification.

shall

“An OpenDocument document shall meet the following requirements:”

  • (section 2.2.1 OpenDocument Document.)

shall not

“OpenDocument extended documents may contain elements and attributes not defined by the OpenDocument schema. Elements and attributes not defined by the OpenDocument schema are called foreign elements and attributes. Foreign elements and attributes shall not be associated with a namespace that is listed in tables 1, 2 or 3 of section 1.5.”

  • (section 3.17 Foreign Elements and Attributes.)

should

“The generator string should allow OpenDocument consumers to distinguish between all released versions of a producer.”

  • (section 4.3.2.1 <meta:generator>.)

should not

“consumers should not permit characters defined by the [SQL] feature F392 for new or changed names of tables, views, columns, and queries.”

  • (section 19.49 db:enable-sql92-check.)

need not

“letters in a custom shape need not have the same height.”

  • (section 19.224 draw:text-path-same-letter-heights.)

can

“The draw:transform attribute specifies a list of transformations that can be applied to a drawing shape.”

  • (section 19.228 draw:transform.)

cannot

“If an OpenDocument producer that creates a document cannot provide an identifier string, the producer shall not export this element. “

  • (section 4.3.2.1 <meta:generator>)

3 OASIS Committee Notes and Project Notes

OASIS Committee Notes and Project Notes are not standards-track documents, and should not contain specification-like language.

IETF BCP 14 capitalized keywords should not be used in these documents, except when quoting another document.

ISO/IEC keywords should not be used in these documents to indicate requirements.

4 Frequently asked questions

  • When are [IETF BCP 14] keywords (or other keywords) required?
    All OASIS work products that will become OASIS Specifications or OASIS Standards, should use the IETF BCP 14 keywords.
  • When are IETF BCP 14 keywords (or other keywords) to be avoided?
    An OASIS Committee (or Project) Note, also known as a “non-standards track” work product, should not use IETF BCP14 keywords, to avoid confusion with OASIS Specifications and Standards.
  • Do keywords only appear in conformance clauses?
    No. Keywords appear in normative parts of a document that are then referred to by clauses in a conformance clause.
  • As an editor, why would I use [ISO/IEC Directives] keywords instead of IETF BCP 14 in a specification?
    If you are planning on submitting an OASIS Standard to ISO/IEC, you can use IETF BCP 14 keywords on a first submission. However, on subsequent submissions, you will be required to conform to the ISO/IEC Directives, which will require use of ISO/IEC keywords.
  • Is “MAY NOT” an IETF BCP 14 keyword?
    No, although it is an ISO/IEC key word in the Eighth Edition of the ISO/IEC Directives.

5 Mapping table for IETF and ISO/IEC keywords

Table 1 lists semantic equivalents between IETF BCP 14 and ISO/IEC keywords. Where there is an empty cell, this means there is no equivalent in that set. If specification writers restrict themselves to keywords that have semantic equivalents, conversion between IETF BCP 14 and ISO/IEC, or vice versa will be easier. In developing this table, we consider IETF BCP 14 treatment of interoperability to be narrow, and interpret requirements as broadly as possible in the manner interpreted by ISO/IEC. The third column in the table lists synonyms that may be considered when specification writers are trying to avoid using one the formal keywords.

Table 1
IETF BCP 14ISO/IECEquivalent phrases, only if necessary
MUST, SHALL, REQUIREDshallis to, is required to, it is required that, has to, only … is permitted, it is necessary
MUST NOT, SHALL NOT, REQUIREDshall notis not allowed [permitted] [acceptable] [permissible], is required to be not, is required that … be not, is not to be, do not
SHOULD/RECOMMENDEDshouldit is recommended that, ought to
SHOULD NOT/NOT RECOMMENDEDshould notit is not recommended that, ought not to
MAY/OPTIONALmayis permitted, is allowed, is permissible
*may notit is not required that, no … is required
*canbe able to, there is a possibility of, it is possible to
*cannotbe unable to, there is no possibility of, it is not possible to

Entries with “*” indicate that no [IETF BCP14] equivalent is defined.

Appendix A. References

A.1 Keyword references

[IETF BCP14]

The two IETF RFCs [RFC2119] and [RFC8174]

[ISO/IEC Directives]

ISO/IEC Directives, Part 2 (Eighth edition) Principles and rules for the structure and drafting of ISO and IEC documents, International Organization for Standardization and International Electrotechnical Commission, 2018. https://www.iso.org/sites/directives/current/part2/index.xhtml.

[RFC2119]

Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, http://www.rfc-editor.org/info/rfc2119.

[RFC8174]

Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, http://www.rfc-editor.org/info/rfc8174.

A.2 OASIS specifications cited

[EBMS-v3.0]

OASIS ebXML Messaging Services Version 3.0: Part 1, Core Features. 01 October 2007. OASIS Standard. http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/core/os/ebms_core-3.0-spec-os.html.

[OData-Part1]

OData Version 4.0 Part 1: Protocol. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. 24 February 2014. OASIS Standard. http://docs.oasis-open.org/odata/odata/v4.0/os/part1-protocol/odata-v4.0-os-part1-protocol.html.

[OpenDocument-v1.2]

Open Document Format for Office Applications (OpenDocument) Version 1.2. 29 September 2011. OASIS Standard. http://docs.oasis-open.org/office/v1.2/os/OpenDocument-v1.2-os.html.

[XACML-v3.0]

eXtensible Access Control Markup Language (XACML) Version 3.0. 22 January 2013. OASIS Standard. http://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html.

Appendix B. Revision History

RevisionDateEditorChanges Made
Initial publication2014-03-21Patrick Durusau–
Revision 22021-04-08Paul KnightRFC 2119 extended per BCP 14; Use of Eighth Edition of ISO/IEC Directives