| Internet-Draft | Simplified Language for Specifying Inter | July 2025 |
| Thomson | Expires 22 January 2026 | [Page] |
The key words used to establish interoperability requirements, can be reduced to a single key word, "MUST". All others are either redundant or cover for latent interoperability issues and can be discouraged.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://martinthomson.github.io/balsamic/draft-thomson-balsamic.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-thomson-balsamic/.¶
Source for this draft and an issue tracker can be found at https://github.com/martinthomson/balsamic.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 22 January 2026.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The most cited RFC ever, RFC 2119 [BCP14], defines 10 key words -- phrases really -- for use in specifications. THese key words have formed the backbone of interoperable specifications in many fields, not just the IETF.¶
These words and phrases represent part of the identity of the IETF. The list is also unnecessarily long.¶
This note argues that a single key word suffices: "MUST".¶
The remainder of this document provides arguments for why all other key words are unnecessary.¶
Most of the set of 10 key words or phrases used are strictly redundant with the term "MUST".¶
The terms "SHALL" and "REQUIRED" are defined to have the same definition as "MUST".¶
Neither term has ever been favoured relative to "MUST".¶
Of the 803 documents published after RFC 9000, 644 of these cite BCP 14. In those 644 documents, the word "MUST" appears 17,327 times, not including the quote from BCP 14. The word "SHALL" appears just 810 times.¶
This ratio (~21.4) is lower than for the RFCs between 2501 and 3000 (~8), which suggests a decline in the popularity of "SHALL".¶
As a perfect synonym of "MUST", it would be easy to stop using "SHALL" entirely.¶
The term "REQUIRED" has become even less popular than "SHALL". Though frequency of usage in RFCs 2501 through 3000 is close to that of "SHALL", it appears just 490 times in recent documents.¶
This word lends itself more to the use of passive voice, which has gradually fallen out of favour in technical writing. This would be easier to retire than "SHALL".¶
A "MAY" or "OPTIONAL" define optional behaviour.¶
On the face of it, these might seem necessary. In defining interoperability, every option that one actor might exercise requires every other actor to support that choice. That is, every "MAY" for one is a "MUST" for others.¶
For instance, if a field in a message is optionally present, every recipient of that message has to tolerate its presence or absence equally. It is therefore more precise to define requirements in terms of the mandatory behaviour of participants other than the one that can exercise choice.¶
Negations include "MUST NOT", "SHALL NOT", and "SHOULD NOT". The undefined and confusing "MAY NOT" appears in several RFCs as well, more early in the series, but also as recently as RFC 9783.¶
The inclusion of negations in key words is unnecessary. Saying "MUST not do X" is equally comprehensible to the shoutier "MUST NOT do X".¶
It is often better to phrase such statements positively, avoiding the use of negation entirely. By specifying the expected reaction of other protocol participants to a forbidden action -- such as to mandate the generation of a fatal error -- the prohibition is both more effective and more fully defined.¶
"SHOULD", its synonym "RECOMMENDED", and its antonym "SHOULD NOT", like the phrases from RFC 6919 [EXTRA], are best avoided in protocol specifications.¶
The use of the term "SHOULD" is one of the most hotly debated and misused of the key words defined in BCP 14. The IESG statement clarifying key word usage [IESG-KW] takes special effort to identify some of these inappropriate uses.¶
Use of "SHOULD" is almost always better phrased in less ambiguous terms, by defining the preferred behaviour, and the conditions where it is acceptable to deviate from that practice.¶
In many cases, "SHOULD" is used to cover deliberate ambiguity in specifications where agreement on specifics could not be reached. A commitment to stop using this language would also lead to better specification discipline and more interoperable specifications; see also [RFC9413].¶
The security of protocols can critically depend on the precision of the language used in specifications.¶
This document has no IANA actions.¶
Stuart Cheshire made the observation that a "MAY" for one is a "MUST" for others.¶