RFC-2119 terminology

[Kristen James Eberlein <kris@eberleinconsulting.com>]

The DITA specification uses RFC-2119 keywords. To quote from the OASIS directives about normative terminology:

"Keywords establish the requirements that implementers follow in conforming to OASIS specifications and standards. Careful use of keywords is one part of creating standards that help different implementers to have the same interpretation of these requirements and lead to interoperable applications from different vendors."

We began implementing these keywords for DITA 1.2, but we now have much clearer guidance from OASIS (see attached PDF if you want all the details).

Here are the RFC keywords:

MUST

This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.

MUST NOT

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

SHOULD

This word, or the adjective "RECOMMENDED", means 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.

SHOULD NOT

This phrase, or the phrase "NOT RECOMMENDED", means 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.

MAY

This word, or the adjective "OPTIONAL", means 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 inter operate 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).

Right now, the spec does not always use these keyword correctly. Part of our moving forward is to correct this. Here are some examples of current correct and incorrect usage:

Correct:

"Processors SHOULD be able to perform filtering and flagging using the attributes listed above. The @props attribute can be specialized to create new attributes, and processors SHOULD be able to perform conditional processing on specializations of @props.

Comment: This reflects the RFC-2119 terminology. It pertains to interoperation. This could be improved so that the normative statement actually listed the attributes and can be read by itself.


Incorrect:

"For each extension element type in the base vocabulary module whose content model or attributes are to be constrained in the constraint module, there MUST be a <xs:redefine> element that defines the restricted content model for the base element. Attributes for an element type MAY be constrained as part of the redefinition of the complex type."

Comment: This simply has to do with how XML Schema works. It can be rewritten as follows: "For each element type in the vocabulary module whose content model or attributes are to be constrained in the constraint module, use an <xs:redefine> element to define the restricted content model. Attributes for an element type can be constrained as part of the redefinition of the complex type."
--

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)

Attachment: OASIS-Keywords-Directives-v6.0-1.pdf
Description: Adobe PDF document