Navigating DRY IETF Specs

I’ve been reading IETF specifications for a number of years now and I find them fairly pleasant to read.  But I remember when I started there were a whole bunch of huh!? moments.  Since then I have learned many of the conventions and developed a few tricks that make the process easier.  I was just reminded of one of those huh!? moments and figured I would share my solution.

I was reading through RFC 7235 which is the HTTP Authentication specification because I wanted to get a good picture of what the header and parameter values actually look like. 

Where To Start

I always start with the HTML version of the spec (there are also a .txt and .pdf version of all specs) so that I can use the hyperlinks in the contents page.  The contents page showed me what I was looking for:

I clicked on the link for section 4.2 and got this,

Ok, so Authorization = credentials !!!.  How completely useless is that? 

A Slight Detour

However, because we are looking at a header definition, I know that what is on the left of the equals is the text that will actually appear in the HTTP request.  All HTTP headers are formatted the same way:

I happen to know this information is in RFC 7230.  One of the tricky parts to working with IETF specs is that they are the ultimate example of DRY.  In order to avoid ambiguous definitions, things tend to be only defined once and everything builds on other things that have been defined elsewhere.  It leads to lots of digging for details. 

So getting back to our example.  We know that an Authorization header-field is made up of the field-name Authorization followed by a colon and then a field-value which is defined as credentials. But how do we know what that means? 

Needle In A Haystack

Looking in the contents page will not find a reference for credentials.  Searching on the term credentials returns 56 results. The trick is to search on “credentials =”.  IETF specifications define syntax using ABNF and that means that somewhere in the document will be a syntax assignment.    Adding the space and equals reduces that search down to just two results. 

The first results is:

Now we can start to see how the field-value is defined.  But now we have more definitions to search for.

Things Are Getting Easier

The reason there are two matches for the credentials = search is because recent IETF specifications have started creating an appendix called Collected ABNF.  This makes it easier to find all the definitions that are used in the current document.

When you drill down, you will find that not everything is defined in the current document.  The syntax for token is defined elsewhere, but there is a link to locate that definition in another spec. 

Some Stuff Is Written In Stone

Older specifications do not have the Collected ABNF appendix so the search trick becomes really helpful when you hunt for obscure syntax definitions in arcane specs that you really don’t want to read in full.

What Are Your Secrets?

If you have other tips that you use for deciphering specifications that you read, I’d love to hear about them.