Generating Correct Examples in Specifications

Correct by Construction

DestinaDesign/Shutterstock.com

The following text fragment is part of the specification for HTTP/1.1 (RFC 2616). Can you spot the error ?

The Accept-Encoding request-header field is similar to Accept, but
restricts the content-codings (section 3.5) that are acceptable in
the response.

  Accept-Encoding  = "Accept-Encoding" ":"
                    1#( codings [ ";" "q" "=" qvalue ] )
  codings          = ( content-coding | "*" )

Examples of its use are:

    Accept-Encoding: compress, gzip
    Accept-Encoding:
    Accept-Encoding: *
    Accept-Encoding: compress;q=0.5, gzip;q=1.0
    Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0

The error is that the second example is invalid, as stated in erratum #411. At first glance this is not a big deal, because in that kind of specifications it is always assumed that when an example does not match the normative text, then the example must be ignored.

The reality is that, when both are available, developers code from examples, not from the normative text as they should. This creates interoperability issues, which is the very thing that specifications were supposed to prevent in the first place.

Because I am in the habit of ignoring examples, I developed a knack at finding these kind of problems in most…