HTTP Editorial Style Guide

This page collects guidance for HTTP specification editors, to promote consistency and ease of use for the document set. See also the RFC Editor style guide.

NOTE: This guide is still in development; discuss improvements to it on the issues list.

Header and Trailer Fields

When defining a field, the first instance should be quoted; e.g.,

This document defines the “Foo” response header field.

If the field is specific to headers, trailers, requests, and/or responses, the definition should include the relevant terms, as above.

When referring to a field defined in a different document, the first instance should include a reference, and all instances should be unquoted. For example:

Add the Foo-Example header field (see {{RFCxxxx}}) to the response.

Subsequent occurrences should be unquoted, but always be followed by “field”, “header field”, or “trailer field” as appropriate.

See also Considerations for New Fields.

Structured Fields

Most HTTP headers defined by the Working Group should be Structured Fields. This isn’t an official policy, but many folks argue for them.

When specifying a Structured Field in prose, preferred practice is to add the following to your “Notational Conventions” section:

This document uses the following terminology from {{Section 3 of STRUCTURED-FIELDS}}
to specify syntax and parsing: List, Dictionary, and Integer.

adjusting the terms listed as appropriate. Then, when using one of the terms, just use the bare, capitalised term; e.g.,

The Foo header field’s value is a List of Integers.

All references to structured types should be made to Section 3 of the Structured Fields specification, not Section 4.

Although ABNF is defined for structured types, we do not recommend its use.

Content

Use ‘content’, not ‘body’ or ‘payload’.

Methods

Just use the bare method name (without quotes or emphasis); e.g.,

Send a request with the GET method.

Stating that it is a HTTP method is optional; this is equally acceptable:

Send a GET request.

See also Considerations for New Methods.

Status Codes

Use the bare status code number, followed by the reason phrase in parentheses. For example:

The 500 (Internal Server Error) status code.

When referring to multiple individual status codes, the reason phrase can be omitted; for example:

If the status code is 200, 202, or 204, proceed.

To refer to a range of status codes, use “xx” notation:

The 4xx range of status codes.

When discussing status codes in general, the correct reference is Section 15 of HTTP. Use ‘status code’, not ‘Status Code’.

See also Considerations for New Status Codes.

Example Messages

If your specification has examples of HTTP messages (and it probably should), they should give enough context for readers to understand. Generally, this means showing a substantial portion of the message; e.g., not just a header field in isolation, but an entire request or response message (with a truncated body). Where appropriate, an entire exchange (request and response) can be illustrated using two subsequent example sections.

Examples should be in HTTP/1.1 format unless they are specific to another version of the protocol. HTTP/1.1 examples should be labeled with the http-message type so that the validator can check them.

For example (in Markdown):

~~~ http-message
HTTP/1.1 200 OK
Content-Type: text/plain
Example-Header: foo

[ content ]
~~~

Examples with long lines (over 78 characters) should be wrapped using the line folding convention where possible. For example:

~~~ http-message
HTTP/1.1 200 OK
Content-Type: text/plain
Example-Header: this content is very long so we
   fold it to the next line and indent

[ content ]
~~~

If the too-long content cannot include whitespace, use RFC8792 encoding:

~~~ http-message
# NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 200 OK
Content-Type: text/plain
Example-Header: abcedfghijlkmnopqrstuvwxyzabcedfghijlkmnopqrstuvwxyzabc\
     edfghijlkmnopqrstuvwxyz

[ content ]
~~~

Note that the notice header has to occur on each section that uses this encoding.

Reference Style

Generally, named references are preferred for “core” specifications like HTTP and TLS. In addition to giving readers a cue about the purpose of the reference, this is a small hint that the RFC number is not the identifier they should be remembering. For example:

This document defines a HTTP {{HTTP}} header field that uses the conventions
in {{STRUCTURED-FIELDS}} to convey information about the TLS ({{TLS}}) session.

The following reference names are preferred:

Note that to include / in an anchor name in markdown, the reference needs to be declared in the YAML header like this:

normative:
  RFC9112:
    display: HTTP/1.1

Not HTTP Specific

The following are useful tips for reducing the amount of editing that the RPC needs to do, leading to cleaner diffs at the end of the process.

Creating and Modifying Registries

When referring to an IANA registry, quote its name. For example,

The Foo header field has been registered in the “Hypertext Transfer Protocol (HTTP) Field Name Registry”.

Create registry entries as Definition Lists. For example,

Name
: dns_timeout

Description
: The intermediary encountered a timeout when trying to find an IP address for the next hop hostname.

Extra Parameters
: None.

Recommended HTTP status code
: 504

Response only generated by intermediaries
: true

Reference
: {{&SELF}}

Self-References

If referring to the your document’s RFC number (e.g., in a registry entry), add this to your document’s YAML header:

entity:
  SELF: "RFC nnnn"

… and then for each reference, use {{&SELF}}, for example:

Reference
: {{&SELF}}

Source on GitHub