Reading an RFC

Most developers have never read a specification end to end. They search for the bit they need, misread it, and implement something that works against one server.

RFCs are dense but they are not difficult, and they follow conventions that make them scannable once you know them.

the keywords are load-bearing#

RFC 2119 defines a small vocabulary, and in a specification these words are technical terms, not English:

• MUST / REQUIRED / SHALL — absolute requirement. Violating it makes your implementation non-conforming.
• MUST NOT / SHALL NOT — absolute prohibition.
• SHOULD / RECOMMENDED — there may be valid reasons to ignore this, but understand the implications first. In practice: everyone does it, and if you do not, something will break eventually.
• SHOULD NOT — same, inverted.
• MAY / OPTIONAL — genuinely optional. Critically: an implementation that does not do it must interoperate with one that does, and vice versa.

When reading, look for the capitalised words first. They are the actual requirements; everything around them is explanation. Skimming an RFC by jumping between MUSTs is a legitimate and efficient way to read one.

the structure is consistent#

Abstract — one paragraph. Read it to decide whether you want this document.

Introduction / Terminology — read the terminology. Specifications define ordinary-looking words precisely, and misreading one is the most common source of implementation bugs.

The body — the actual protocol.

Security Considerations — mandatory in every RFC and consistently the most interesting section. It is where the authors say what they could not fix, what attacks apply, and what implementers get wrong. If you read one section, read this one.

IANA Considerations — registries. Where you find the canonical list of registered values, which is often the thing you actually needed.

ABNF grammar — usually an appendix. The precise syntax, in a formal grammar. If you are writing a parser, this is authoritative and the prose is not.

the things that trip people up#

Updated and obsoleted. An RFC is never edited. It is replaced. Always check the header for "Obsoleted by" — implementing an obsolete specification is a common and embarrassing mistake, and HTTP/1.1 alone has been re-specified several times.

Errata. Published RFCs have errata filed against them. Check them; some are substantive corrections.

Not all RFCs are standards. The series includes Informational, Experimental, Best Current Practice, Historic, and April Fools jokes. The status is in the header. "It's an RFC" is not the same as "it's a standard."

The grammar wins over the prose. Where the ABNF and the description disagree, the ABNF is normative. This is the single most useful thing to know when a specification appears ambiguous.

the reading strategy#

For a specification you need to implement:

1. Abstract, to confirm it is the right document.
2. Check the header for obsoletions, then the errata.
3. Terminology section, properly.
4. Security Considerations — early, not last. It tells you what the hard parts are before you have written anything.
5. Skim for MUST and MUST NOT to get the shape of the requirements.
6. Then the relevant sections in detail, with the ABNF beside you.

That is maybe ninety minutes for a substantial specification, and it is dramatically cheaper than the alternative, which is discovering the requirements one interoperability bug at a time.

why bother#

Because the specification is the only source that is actually authoritative. Blog posts, Stack Overflow answers and library documentation are all someone's interpretation, and interpretations drift.

When two implementations disagree — and they will — the specification is what settles it. Being the person on the team who can read one and say "we are wrong, section 4.2 says the header is case-insensitive" is a genuinely useful thing to be, and it costs one afternoon of learning the conventions.