API and Technical Documentation Editing and Proofreading Services

Capitalization decides what a sentence in a specification requires. RFC 2119, written by S. Bradner and published in March 1997, gave a short list of ordinary English words a defined meaning for use in protocol specifications.¹ Its abstract says only that these words "are often capitalized," which left the status of the lowercase forms open.¹ Twenty years later the IETF published a second memo whose main work was to settle that question.²

What the words were defined to mean

RFC 2119 sets out the terms plainly. "MUST" and the terms "REQUIRED" or "SHALL" mean "that the definition is an absolute requirement of the specification."¹ "SHOULD", 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."¹ "MAY", or "OPTIONAL", means "that an item is truly optional."¹

That last definition does not end there, and the rest of it is easy to miss. Section 5 goes on to say that an implementation omitting an option "MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality."¹ The reverse case carries a MUST as well.¹ The definition of the weakest keyword contains two instances of the strongest one.

The memo demonstrates its own ambiguity

Section 6 offers guidance on using the words. It opens: "Imperatives of the type defined in this memo must be used with care and sparingly."¹ The sentence after that one carries the capitalized form.¹ It reads: "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 retransmisssions)" and then stops without a period.¹ A lowercase must and an uppercase MUST sit in consecutive sentences of the memo that gives the capitals their defined meaning.

The example inside that parenthesis also spells "retransmisssions" with three esses. Both faults are in the published text of a Best Current Practice document dated March 1997.¹ The RFC Editor's information page for RFC 2119 links to a list of errata reported against it, and the document itself has not been reissued.³

RFC 8174, by B. Leiba, was published in May 2017. Its abstract says the document "aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings."² RFC 8174 updates RFC 2119 as a separate document rather than replacing it.³ The two together now form BCP 14, and the RFC Editor lists that subseries as containing exactly those two documents.⁴

What a specification inherits by citing BCP 14

Version 3.1.0 of the OpenAPI Specification, dated February 15, 2021, adopts the convention and spells out the condition.⁵ It names eleven terms, from "MUST" through "OPTIONAL", and says they are to be interpreted as described in BCP 14 "when, and only when, they appear in all capitals, as shown here."⁵ A specification that cites BCP 14 without repeating that clause has still adopted the condition, because the condition is inside the memos being cited.

Other standards bodies handled the same problem with a different vocabulary. ISO writes that "shall" indicates a requirement and "should" indicates a recommendation, while "may" is used to indicate that something is permitted.⁶ A writer moving between an ISO document and an IETF one is moving between two vocabularies that overlap without matching.

The IETF also published guidance for people writing standards. RFC 2360, edited by G. Scott, is dated June 1998. It tells editors of standards track documents that they "must not deviate from the definitions provided as they are intended to identify interoperability requirements or limit potentially harmful behavior."⁷

What we can check, and what we cannot

Whether an endpoint behaves as its documentation claims is a question for the engineers who built the endpoint. We cannot answer it, we do not test software, and we do not decide what a specification ought to require. A keyword is chosen by the people writing the specification, and we leave the choice where they made it.

Reading is a narrower job than that. A search through a document citing BCP 14 returns every appearance of a keyword, capitalized and lowercased alike, and that is how an inconsistency turns up. The RFC Style Guide asks in its own house rules for an abbreviation to be expanded on first use, and first use is a locatable place in the file.⁸ The Google developer documentation style guide asks writers to "aim for a conversational tone rather than a formal one," which is a description of register.⁹ Where one entry moves between that register and a formal one, the move is on the page. Nothing a client sends us is shared.

There is a practical consequence for anyone running a copy edit over a specification. A pass that sentence-cases headings can turn MUST into Must. In a document that cites BCP 14, that is not a formatting change.