December 18, 2017

RFC2119, do you speak it?

As a developer you should not only be familiar with Request For Comments, or RFCs, but capable of reading them and understanding the concepts they describe. There’s also a lot to love with them: their initials line up perfectly on a standard QWERTY keyboard (seriously, take a peek!), and they detail some of the greatest technical advances of the last few decades.

One RFC in particular - RFC 2119 - is arguably of particular importance though; it details the concept of ‘requirement levels” that are used in many many subsequent RFCs.

In every day vernacular, the words “must”, “should”, or “may” all sound pretty obvious, and we instinctively know what they mean. In the highly specific world of engineering though, knowing isn’t always good enough.

Requirement Levels, and defining the obvious

The title of RFC2119 is officially “Key words for use in RFCs to Indicate Requirement Levels” - and as the name suggests, it codifies a mechanism for expressing how to interpret requirements outlined in an RFC.

The document itself is refreshingly simple, weighing in at under 2 pages without boilerplate (i.e formatting and authorship details), and it provides the technical equivalent of the definitions you may find in a legal contract.

Authored by Scott Bradner of Harvard University in 1997, the RFC lists previous definitions for various requirement levels, and provides consistent definitions for the future.

It’s adoption is such that it’s now ubiquitious to see the following paragraph appear in technical documents:

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 RFC 2119.

To aid the reader in interpreting requirement levels correctly, as well as to signify the importance of these levels, it’s standard practice to capitalise the key-words as they are in the above quote.

Actual Definitions

Although the RFC explicitly lists 10 key-words, some are equivalent - and thus there’s actually only 5 requirement levels.

1. “Absolute requirements” (aka “mandatory”)“MUST”, “REQUIRED”, “SHALL”

Something that belongs to this requirement level is explicitly required by the described system; that is to say it’s mandatory. A failure to adhere to this requirement is a failure to adhere to the spec outlined in the RFC.

2. “Absolute prohibition” (aka “forbidden”)“MUST NOT”, “SHALL NOT”

This requirement level is a negation of the above. A system which features something which is categorised under “absolute prohibition” is not compliant with the spec outlined in the RFC.

3. Desirable, but not mandatory (aka “recommended”)“SHOULD”, “RECOMMENDED”

Something that is “recommended” is expected to feature in an implementation that adheres to the spec, although a system which adheres to the spec can forego this feature with a good and valid reason.

4. Not desirable, but allowable“SHOULD NOT”, “NOT RECOMMENDED”

This is a negation of the “recommended” level, and describes features that should not be found in an implementation of the spec. However, if a given system does have a good and valid reason for doing so, it can implement the feature and still be considered as adhering to the spec.

5. Optional.“MAY”, “OPTIONAL”

Lastly, RFCs can contain requirements which are not required, and not recommended, but may be included in an implementation regardless. RFC 2119 dictates that the implementation of these requirements should not come at the cost of interoperability with other systems, as other systems are not expected to possess optional requirements.

Why does this matter to me?

The Internet Engineering Task Force possess RFCs for all manner of technologies and protocols. These documents describe a whole plethora of every day technologies like UDP, IP, POP3, HTTP, FTP and DNS, including modern proposals like HTTP/2 and HTTP Status Code 451

Understanding how to interpret and understand these documents is a crucial tool in any developer’s toolkit. From those who are working on low level protocols like those mentioned above, to web developers who rely upon technologies like HTTP, TLS, and even OAuth (RFC6749).

Utilising the terminology laid out in RFC2119 goes beyond consumption though, and there are plenty of use cases where it can - and should - be adopted as an everyday part of your practice.

I’ll admit that my own usage of the terms has been sloppy at times - and once I was even picked up on it by a rather astute client who sought clarification. To me, this underlines just how important these terms can be when writing my own specifications.

Another potential use case for the terminlogy outlined in RFC 2119 is documenting security procedures; another area where definitions are important, and misunderstandings via ambigious terminology can be costly.

Ultimately, using the terminology outlined in RFC2119 is a simple step to aid communication and ensure clarity. Not only does it increase your understanding of existing specifications, but it also removes ambiguity from your own.

© Fergus In London 2019

Powered by Hugo & Kiss. Source available on Github.