CINXE.COM

<!DOCTYPE HTML> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>HTTP Editorial Style Guide</title> <meta property="og:type" content="website"> <meta property="og:title" content="HTTP Editorial Style Guide"> <meta property="og:description" content=""> <meta property="og:url" content="https://httpwg.org/editors/style-guide.html"> <meta property="og:site_name" content="IETF HTTP Working Group"> <meta name="viewport" content="width=device-width, initial-scale=1"> <link href="/assets/node_modules/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet"> <link href="/assets/site.css" rel="stylesheet"> <link rel="shortcut icon" type="image/x-icon" href="/assets/favicon/favicon.ico"> <link rel="apple-touch-icon" sizes="57x57" href="/assets/favicon/apple-icon-57x57.png"> <link rel="apple-touch-icon" sizes="60x60" href="/assets/favicon/apple-icon-60x60.png"> <link rel="apple-touch-icon" sizes="72x72" href="/assets/favicon/apple-icon-72x72.png"> <link rel="apple-touch-icon" sizes="76x76" href="/assets/favicon/apple-icon-76x76.png"> <link rel="apple-touch-icon" sizes="114x114" href="/assets/favicon/apple-icon-114x114.png"> <link rel="apple-touch-icon" sizes="120x120" href="/assets/favicon/apple-icon-120x120.png"> <link rel="apple-touch-icon" sizes="144x144" href="/assets/favicon/apple-icon-144x144.png"> <link rel="apple-touch-icon" sizes="152x152" href="/assets/favicon/apple-icon-152x152.png"> <link rel="apple-touch-icon" sizes="180x180" href="/assets/favicon/apple-icon-180x180.png"> <link rel="icon" type="image/png" sizes="32x32" href="/assets/favicon/favicon-32x32.png"> <link rel="icon" type="image/png" sizes="96x96" href="/assets/favicon/favicon-96x96.png"> <link rel="icon" type="image/png" sizes="16x16" href="/assets/favicon/favicon-16x16.png"> </head> <body> <nav class="navbar navbar-dark bg-dark d-print-none navbar-expand-lg fixed-top ps-3 pe-3" role="navigation">  <div class="navbar-header"> <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbar-collapse" aria-controls="navbarToggler" aria-expanded="false" aria-label="Toggle navigation"> <span class="navbar-toggler-icon"></span> </button> <a class="navbar-brand" href="https://httpwg.org/"><img src="https://httpwg.org/assets/http.svg" height="23" /></a> </div> <div class="collapse navbar-collapse" id="navbar-collapse"> <div class="navbar-nav me-auto"> <a class="nav-item ms-1 text-white" href="https://httpwg.org/specs/">📄 Documentation</a> <div class="dropdown ms-4"> <a href="#" class="nav-item dropdown-toggle text-white" data-bs-toggle="dropdown">Work in Progress</a> <ul class="dropdown-menu"> <li class="dropdown-item"><a href="https://httpwg.org/http-extensions/">HTTP Extensions</a></li> <li class="dropdown-item"><a href="https://github.com/httpwg/admin/issues?q=is%3Aissue+is%3Aopen+label%3Aadoption">Future Work</a></li> </ul> </div> <div class="dropdown ms-4"> <a href="#" class="nav-item dropdown-toggle text-white" data-bs-toggle="dropdown">Participate</a> <ul class="dropdown-menu"> <li class="dropdown-item"><a href="https://httpwg.org/about/">About the HTTP Working Group</a></li> <li class="divider"></li> <li class="dropdown-item"><a href="https://httpwg.org/CONTRIBUTING.html">Contribution Policy</a></li> <li class="dropdown-item"><a href="http://datatracker.ietf.org/wg/httpbis/charter/">WG Charter</a></li> <li class="dropdown-item"><a href="http://lists.w3.org/Archives/Public/ietf-http-wg/">Group Mailing List 📨</a></li> <li class="dropdown-item"><a href="https://httpwg.org/wg-materials/">Meeting Materials</a></li> <li class="dropdown-item"><a href="https://httpwg.org/admin/editors/">Document Editor Resources</a></li> </ul> </div> </div> </div> </nav> <div class="container px-3 my-2 markdown-body"> <h2>HTTP Editorial Style Guide</h2> <p>This page collects guidance for HTTP specification editors, to promote consistency and ease of use for the document set. See also the <a href="https://www.rfc-editor.org/styleguide/">RFC Editor style guide</a>.</p> <p><strong>NOTE</strong>: This guide is still in development; discuss improvements to it on the <a href="https://github.com/httpwg/admin/labels/style-guide">issues list</a>.</p>   <ul> <li><a href="#header-and-trailer-fields">Header and Trailer Fields</a> <ul> <li><a href="#structured-fields">Structured Fields</a></li> </ul> </li> <li><a href="#content">Content</a></li> <li><a href="#methods">Methods</a></li> <li><a href="#status-codes">Status Codes</a></li> <li><a href="#example-messages">Example Messages</a></li> <li><a href="#reference-style">Reference Style</a></li> <li><a href="#not-http-specific">Not HTTP Specific</a> <ul> <li><a href="#creating-and-modifying-registries">Creating and Modifying Registries</a></li> <li><a href="#self-references">Self-References</a></li> </ul> </li> </ul>  <h2 id="header-and-trailer-fields">Header and Trailer Fields</h2> <p>When defining a field, the first instance should be quoted; e.g.,</p> <blockquote> <p>This document defines the “Foo” response header field.</p> </blockquote> <p>If the field is specific to headers, trailers, requests, and/or responses, the definition should include the relevant terms, as above.</p> <p>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:</p> <blockquote> <p>Add the Foo-Example header field (see {{RFCxxxx}}) to the response.</p> </blockquote> <p>Subsequent occurrences should be unquoted, but always be followed by “field”, “header field”, or “trailer field” as appropriate.</p> <p>See also <a href="https://httpwg.org/specs/rfc9110.html#considerations.for.new.fields">Considerations for New Fields</a>.</p> <h3 id="structured-fields">Structured Fields</h3> <p>Most HTTP headers defined by the Working Group should be <a href="https://httpwg.org/specs/rfc8941.html">Structured Fields</a>. This isn’t an official policy, but many folks argue for them.</p> <p>When specifying a Structured Field in prose, preferred practice is to add the following to your “Notational Conventions” section:</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>This document uses the following terminology from {{Section 3 of STRUCTURED-FIELDS}} to specify syntax and parsing: List, Dictionary, and Integer. </code></pre></div></div> <p>adjusting the terms listed as appropriate. Then, when using one of the terms, just use the bare, capitalised term; e.g.,</p> <blockquote> <p>The Foo header field’s value is a List of Integers.</p> </blockquote> <p>All references to structured types should be made to <a href="https://httpwg.org/specs/rfc8941.html#rfc.section.3">Section 3</a> of the Structured Fields specification, <strong>not</strong> Section 4.</p> <p>Although ABNF is defined for structured types, we do not recommend its use.</p> <h2 id="content">Content</h2> <p>Use ‘content’, not ‘body’ or ‘payload’.</p> <h2 id="methods">Methods</h2> <p>Just use the bare method name (without quotes or emphasis); e.g.,</p> <blockquote> <p>Send a request with the GET method.</p> </blockquote> <p>Stating that it is a HTTP method is optional; this is equally acceptable:</p> <blockquote> <p>Send a GET request.</p> </blockquote> <p>See also <a href="https://httpwg.org/specs/rfc9110.html#considerations.for.new.methods">Considerations for New Methods</a>.</p> <h2 id="status-codes">Status Codes</h2> <p>Use the bare status code number, followed by the reason phrase in parentheses. For example:</p> <blockquote> <p>The 500 (Internal Server Error) status code.</p> </blockquote> <p>When referring to multiple individual status codes, the reason phrase can be omitted; for example:</p> <blockquote> <p>If the status code is 200, 202, or 204, proceed.</p> </blockquote> <p>To refer to a range of status codes, use “xx” notation:</p> <blockquote> <p>The 4xx range of status codes.</p> </blockquote> <p>When discussing status codes in general, the correct reference is <a href="https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#status.codes">Section 15 of HTTP</a>. Use ‘status code’, not ‘Status Code’.</p> <p>See also <a href="https://httpwg.org/specs/rfc9110.html#considerations.for.new.status.codes">Considerations for New Status Codes</a>.</p> <h2 id="example-messages">Example Messages</h2> <p>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.</p> <p>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 <code class="language-plaintext highlighter-rouge">http-message</code> type so that the <a href="https://github.com/mnot/rfc-http-validate">validator</a> can check them.</p> <p>For example (in Markdown):</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>~~~ http-message HTTP/1.1 200 OK Content-Type: text/plain Example-Header: foo [ content ] ~~~ </code></pre></div></div> <p>Examples with long lines (over 78 characters) should be wrapped using the line folding convention where possible. For example:</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>~~~ 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 ] ~~~ </code></pre></div></div> <p>If the too-long content cannot include whitespace, use <a href="https://www.rfc-editor.org/rfc/rfc8792.html">RFC8792</a> encoding:</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>~~~ http-message # NOTE: '\' line wrapping per RFC 8792 HTTP/1.1 200 OK Content-Type: text/plain Example-Header: abcedfghijlkmnopqrstuvwxyzabcedfghijlkmnopqrstuvwxyzabc\ edfghijlkmnopqrstuvwxyz [ content ] ~~~ </code></pre></div></div> <p>Note that the notice header has to occur on each section that uses this encoding.</p> <h2 id="reference-style">Reference Style</h2> <p>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:</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>This document defines a HTTP {{HTTP}} header field that uses the conventions in {{STRUCTURED-FIELDS}} to convey information about the TLS ({{TLS}}) session. </code></pre></div></div> <p>The following reference names are preferred:</p> <ul> <li><code class="language-plaintext highlighter-rouge">HTTP</code> - <a href="https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html">HTTP Semantics</a></li> <li><code class="language-plaintext highlighter-rouge">HTTP-CACHING</code> - <a href="https://httpwg.org/http-core/draft-ietf-httpbis-cache-latest.html">HTTP Caching</a></li> <li><code class="language-plaintext highlighter-rouge">HTTP/1.1</code> - <a href="https://httpwg.org/http-core/draft-ietf-httpbis-messaging-latest.html">HTTP/1.1</a></li> <li><code class="language-plaintext highlighter-rouge">HTTP/2</code> - <a href="https://httpwg.org/http2-spec/draft-ietf-httpbis-http2bis.html">HTTP/2</a></li> <li><code class="language-plaintext highlighter-rouge">HTTP/3</code> - <a href="https://quicwg.org/base-drafts/draft-ietf-quic-http.html">HTTP/3</a></li> <li><code class="language-plaintext highlighter-rouge">STRUCTURED-FIELDS</code> - <a href="https://httpwg.org/specs/rfc8941.html">Structured Field Values for HTTP</a></li> <li><code class="language-plaintext highlighter-rouge">COOKIES</code> - <a href="https://httpwg.org/http-extensions/draft-ietf-httpbis-rfc6265bis.html">Cookies: HTTP State Management Mechanism</a></li> <li><code class="language-plaintext highlighter-rouge">TLS</code> - <a href="https://www.rfc-editor.org/rfc/rfc8446.html">The Transport Layer Security (TLS) Protocol Version 1.3</a></li> </ul> <p>Note that to include <code class="language-plaintext highlighter-rouge">/</code> in an anchor name in markdown, the reference needs to be declared in the YAML header like this:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">normative</span><span class="pi">:</span> <span class="na">RFC9112</span><span class="pi">:</span> <span class="na">display</span><span class="pi">:</span> <span class="s">HTTP/1.1</span> </code></pre></div></div> <h2 id="not-http-specific">Not HTTP Specific</h2> <p>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.</p> <h3 id="creating-and-modifying-registries">Creating and Modifying Registries</h3> <p>When referring to an IANA registry, quote its name. For example,</p> <blockquote> <p>The Foo header field has been registered in the “Hypertext Transfer Protocol (HTTP) Field Name Registry”.</p> </blockquote> <p>Create registry entries as Definition Lists. For example,</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>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}} </code></pre></div></div> <h3 id="self-references">Self-References</h3> <p>If referring to the your document’s RFC number (e.g., in a registry entry), add this to your document’s YAML header:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">entity</span><span class="pi">:</span> <span class="na">SELF</span><span class="pi">:</span> <span class="s2">"</span><span class="s">RFC</span><span class="nv"> </span><span class="s">nnnn"</span> </code></pre></div></div> <p>… and then for each reference, use <code class="language-plaintext highlighter-rouge">{{&SELF}}</code>, for example:</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Reference : {{&SELF}} </code></pre></div></div> <p class="github-link"><a href="https://github.com/httpwg/admin/blob/main/editors/style-guide.md"><img src="/assets/github.png" alt="Source on GitHub"/></a></p> <script src="/assets/node_modules/bootstrap/dist/js/bootstrap.bundle.min.js"></script> </div> </body> </html>