Skip to content

RFC 9651: Structured Field Values for HTTP

  • M. Nottingham,  
  • P-H. Kamp
Proposed Standard

Abstract

This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header and trailer fields, known as "Structured Fields", "Structured Headers", or "Structured Trailers". It is intended for use by specifications of new HTTP fields.

This document obsoletes RFC 8941.

Status of This Memo

This is an Internet Standards Track document.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at .

1. Introduction

Specifying the syntax of new HTTP header (and trailer) fields is an onerous task; even with the guidance in Section 16.3.2 of [], there are many decisions -- and pitfalls -- for a prospective HTTP field author.

Once a field is defined, bespoke parsers and serializers often need to be written, because each field value has a slightly different handling of what looks like common syntax.

This document introduces a set of common data structures for use in definitions of new HTTP field values to address these problems. In particular, it defines a generic, abstract model for them, along with a concrete serialization for expressing that model in HTTP [] header and trailer fields.

An HTTP field that is defined as a "Structured Header" or "Structured Trailer" (if the field can be either, it is a "Structured Field") uses the types defined in this specification to define its syntax and basic handling rules, thereby simplifying both its definition by specification writers and handling by implementations.

Additionally, future versions of HTTP can define alternative serializations of the abstract model of these structures, allowing fields that use that model to be transmitted more efficiently without being redefined.

Note that it is not a goal of this document to redefine the syntax of existing HTTP fields; the mechanisms described herein are only intended to be used with fields that explicitly opt into them.

Section 2 describes how to specify a Structured Field.

Section 3 defines a number of abstract data types that can be used in Structured Fields.

Those abstract types can be serialized into and parsed from HTTP field values using the algorithms described in Section 4.

1.1. Intentionally Strict Processing

This specification intentionally defines strict parsing and serialization behaviors using step-by-step algorithms; the only error handling defined is to fail the entire operation altogether.

It is designed to encourage faithful implementation and good interoperability. Therefore, an implementation that tried to be helpful by being more tolerant of input would make interoperability worse, since that would create pressure on other implementations to implement similar (but likely subtly different) workarounds.

In other words, strict processing is an intentional feature of this specification; it allows non-conformant input to be discovered and corrected by the producer early and avoids both interoperability and security issues that might otherwise result.

Note that as a result of this strictness, if a field is appended to by multiple parties (e.g., intermediaries or different components in the sender), an error in one party's value is likely to cause the entire field value to fail parsing.

1.2. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [] [] when, and only when, they appear in all capitals, as shown here.

This document uses the VCHAR, SP, DIGIT, ALPHA, and DQUOTE rules from [] to specify characters and/or their corresponding ASCII bytes, depending on context. It uses the tchar and OWS rules from [] for the same purpose.

This document uses algorithms to specify parsing and serialization behaviors. When parsing from HTTP fields, implementations MUST have behavior that is indistinguishable from following the algorithms.

For serialization to HTTP fields, the algorithms define the recommended way to produce them. Implementations MAY vary from the specified behavior so long as the output is still correctly handled by the parsing algorithm described in Section 4.2.

2. Defining New Structured Fields

To specify an HTTP field as a Structured Field, its authors need to:

  • Normatively reference this specification. Recipients and generators of the field need to know that the requirements of this document are in effect.

  • Identify whether the field is a Structured Header (i.e., it can only be used in the header section -- the common case), a Structured Trailer (only in the trailer section), or a Structured Field (both).

  • Specify the type of the field value; either List (Section 3.1), Dictionary (Section 3.2), or Item (Section 3.3).

  • Define the semantics of the field value.

  • Specify any additional constraints upon the field value, as well as the consequences when those constraints are violated.

Typically, this means that a field definition will specify the top-level type -- List, Dictionary, or Item -- and then define its allowable types and constraints upon them. For example, a header defined as a List might have all Integer members, or a mix of types; a header defined as an Item might allow only Strings, and additionally only strings beginning with the letter "Q", or strings in lowercase. Likewise, Inner Lists (Section 3.1.1) are only valid when a field definition explicitly allows them.

Fields that use the Display String type are advised to carefully specify their allowable Unicode code points; for example, specifying the use of a profile from [].

Field definitions can only use this specification for the entire field value, not a portion thereof.

Specifications can refer to a field name as a "Structured Header name", "Structured Trailer name", or "Structured Field name" as appropriate. Likewise, they can refer its field value as a "Structured Header value", "Structured Trailer value", or "Structured Field value" as necessary.

This specification defines minimums for the length or number of various structures supported by implementations. It does not specify maximum sizes in most cases, but authors should be aware that HTTP implementations do impose various limits on the size of individual fields, the total number of fields, and/or the size of the entire header or trailer section.

2.1. Example

A fictitious Foo-Example header field might be specified as:

42. Foo-Example Header Field

The Foo-Example HTTP header field conveys information about how much Foo the message has.

Foo-Example is an Item Structured Header Field [RFC9651]. Its value MUST be an Integer (Section 3.3.1 of [RFC9651]).

Its value indicates the amount of Foo in the message, and it MUST be between 0 and 10, inclusive; other values MUST cause the entire header field to be ignored.

The following parameter is defined:

  • A parameter whose key is "foourl", and whose value is a String (Section 3.3.3 of [RFC9651]), conveying the Foo URL for the message. See below for processing requirements.

"foourl" contains a URI-reference (Section 4.1 of [RFC3986]). If its value is not a valid URI-reference, the entire header field MUST be ignored. If its value is a relative reference (Section 4.2 of [RFC3986]), it MUST be resolved (Section 5 of [RFC3986]) before being used.

For example:

  Foo-Example: 2; foourl="https://foo.example.com/"

2.2. Error Handling

When parsing fails, the entire field is ignored (see Section 4.2). Field definitions cannot override this because doing so would preclude handling by generic software; they can only add additional constraints (for example, on the numeric range of Integers and Decimals, the format of Strings and Tokens, the types allowed in a Dictionary's values, or the number of Items in a List).

When field-specific constraints are violated, the entire field is also ignored, unless the field definition defines other handling requirements. For example, if a header field is defined as an Item and required to be an Integer, but a String is received, it should be ignored unless that field's definition explicitly specifies otherwise.

2.3. Preserving Extensibility

Structured Fields are designed to be extensible because experience has shown that, even when it is not foreseen, it is often necessary to modify and add to the allowable syntax and semantics of a field in a controlled fashion.

Both Items and Inner Lists allow Parameters as an extensibility mechanism; this means that their values can later be extended to accommodate more information, if need be. To preserve forward compatibility, field specifications are discouraged from defining the presence of an unrecognized parameter as an error condition.

Field specifications are required to be either an Item, List, or Dictionary to preserve extensibility. Fields that erroneously defined as another type (e.g., Integer) are assumed to be Items (i.e., they allow Parameters).

To further assure that this extensibility is available in the future, and to encourage consumers to use a complete parser implementation, a field definition can specify that "grease" parameters be added by senders. A specification could stipulate that all parameters that fit a defined pattern are reserved for this use and then encourage them to be sent on some portion of requests. This helps to discourage recipients from writing a parser that does not account for Parameters.

Specifications that use Dictionaries can also allow for forward compatibility by requiring that the presence of -- as well as value and type associated with -- unknown keys be ignored. Subsequent specifications can then add additional keys, specifying constraints on them as appropriate.

An extension to a Structured Field can then require that an entire field value be ignored by a recipient that understands the extension if constraints on the value it defines are not met.

2.4. Using New Structured Types in Extensions

Because a field definition needs to reference a specific RFC for Structured Fields, the types available for use in its value are limited to those defined in that RFC. For example, a field whose definition references this document can have a value that uses the Date type (Section 3.3.7), whereas a field whose definition references RFC 8941 cannot because it will be treated as invalid (and therefore discarded) by implementations of that specification.

This limitation also applies to future extensions to a field; for example, a field that is defined with a reference to RFC 8941 cannot use the Date type because some recipients might still be using a parser based on RFC 8941 to process it.

However, this document is designed to be backward compatible with RFC 8941; a parser that implements the requirements here can also parse valid Structured Fields whose definitions reference RFC 8941.

Upgrading a Structured Fields implementation to support a newer revision of the specification (such as this document) brings the possibility that some field values that were invalid according to the earlier RFC might become valid when processed.

For example, a field instance might contain a syntactically valid Date (Section 3.3.7), even though that field's definition does not accommodate Dates. An implementation based on RFC 8941 would fail parsing such a field instance because it is not defined in that specification. If that implementation were upgraded to this specification, parsing would now succeed. In some cases, the resulting Date value will be rejected by field-specific logic, but values in fields that are otherwise ignored (such as extension parameters) might not be detected, and the field might subsequently be accepted and processed.

3. Structured Data Types

This section provides an overview of the abstract types that Structured Fields use and gives a brief description and examples of how each of those types are serialized into textual HTTP fields. Section 4 specifies the details of how they are parsed from and serialized into textual HTTP fields.

In summary:

  • There are three top-level types that an HTTP field can be defined as: Lists, Dictionaries, and Items.

  • Lists and Dictionaries are containers; their members can be Items or Inner Lists (which are themselves arrays of Items).

  • Both Items and Inner Lists can be Parameterized with key/value pairs.

3.1. Lists

Lists are arrays of zero or more members, each of which can be an Item (Section 3.3) or an Inner List (Section 3.1.1), both of which can be Parameterized (Section 3.1.2).

An empty List is denoted by not serializing the field at all. This implies that fields defined as Lists have a default empty value.

When serialized as a textual HTTP field, each member is separated by a comma and optional whitespace. For example, a field whose value is defined as a List of Tokens could look like:

Example-List: sugar, tea, rum

Note that Lists can have their members split across multiple lines of the same header or trailer section, as per Section 5.3 of []; for example, the following are equivalent:

Example-List: sugar, tea, rum

and

Example-List: sugar, tea
Example-List: rum

However, individual members of a List cannot be safely split between lines; see Section 4.2 for details.

Parsers MUST support Lists containing at least 1024 members. Field specifications can constrain the types and cardinality of individual List values as they require.

3.1.1. Inner Lists

An Inner List is an array of zero or more Items (Section 3.3). Both the individual Items and the Inner List itself can be Parameterized (Section 3.1.2).

When serialized in a textual HTTP field, Inner Lists are denoted by surrounding parenthesis, and their values are delimited by one or more spaces. A field whose value is defined as a List of Inner Lists of Strings could look like:

Example-List: ("foo" "bar"), ("baz"), ("bat" "one"), ()

Note that the last member in this example is an empty Inner List.

A header field whose value is defined as a List of Inner Lists with Parameters at both levels could look like:

Example-List: ("foo"; a=1;b=2);lvl=5, ("bar" "baz");lvl=1

Parsers MUST support Inner Lists containing at least 256 members. Field specifications can constrain the types and cardinality of individual Inner List members as they require.

3.1.2. Parameters

Parameters are an ordered map of key-value pairs that are associated with an Item (Section 3.3) or Inner List (Section 3.1.1). The keys are unique within the scope of the Parameters they occur within, and the values are bare items (i.e., they themselves cannot be parameterized; see Section 3.3).

Implementations MUST provide access to Parameters both by index and by key. Specifications MAY use either means of accessing them.

Note that parameters are ordered, and parameter keys cannot contain uppercase letters.

When serialized in a textual HTTP field, a Parameter is separated from its Item or Inner List and other Parameters by a semicolon. For example:

Example-List: abc;a=1;b=2; cde_456, (ghi;jk=4 l);q="9";r=w

Parameters whose value is Boolean (see Section 3.3.6) true MUST omit that value when serialized. For example, the "a" parameter here is true, while the "b" parameter is false:

Example-Integer: 1; a; b=?0

Note that this requirement is only on serialization; parsers are still required to correctly handle the true value when it appears in a parameter.

Parsers MUST support at least 256 parameters on an Item or Inner List, and support parameter keys with at least 64 characters. Field specifications can constrain the order of individual parameters, as well as their values' types as required.

3.2. Dictionaries

Dictionaries are ordered maps of key-value pairs, where the keys are short textual strings and the values are Items (Section 3.3) or arrays of Items, both of which can be Parameterized (Section 3.1.2). There can be zero or more members, and their keys are unique in the scope of the Dictionary they occur within.

Implementations MUST provide access to Dictionaries both by index and by key. Specifications MAY use either means of accessing the members.

As with Lists, an empty Dictionary is represented by omitting the entire field. This implies that fields defined as Dictionaries have a default empty value.

Typically, a field specification will define the semantics of Dictionaries by specifying the allowed type(s) for individual members by their keys, as well as whether their presence is required or optional. Recipients MUST ignore members whose keys are undefined or unknown, unless the field's specification specifically disallows them.

When serialized as a textual HTTP field, members are ordered as serialized and separated by a comma with optional whitespace. Member keys cannot contain uppercase characters. Keys and values are separated by "=" (without whitespace). For example:

Example-Dict: en="Applepie", da=:w4ZibGV0w6ZydGU=:

Note that in this example, the final "=" is due to the inclusion of a Byte Sequence; see Section 3.3.5.

Members whose value is Boolean (see Section 3.3.6) true MUST omit that value when serialized. For example, here both "b" and "c" are true:

Example-Dict: a=?0, b, c; foo=bar

Note that this requirement is only on serialization; parsers are still required to correctly handle the true Boolean value when it appears in Dictionary values.

A Dictionary with a member whose value is an Inner List of Tokens:

Example-Dict: rating=1.5, feelings=(joy sadness)

A Dictionary with a mix of Items and Inner Lists, some with parameters:

Example-Dict: a=(1 2), b=3, c=4;aa=bb, d=(5 6);valid

Note that Dictionaries can have their members split across multiple lines of the same header or trailer section; for example, the following are equivalent:

Example-Dict: foo=1, bar=2

and

Example-Dict: foo=1
Example-Dict: bar=2

However, individual members of a Dictionary cannot be safely split between lines; see Section 4.2 for details.

Parsers MUST support Dictionaries containing at least 1024 key/value pairs and keys with at least 64 characters. Field specifications can constrain the order of individual Dictionary members, as well as their values' types as required.

3.3. Items

An Item can be an Integer (Section 3.3.1), a Decimal (Section 3.3.2), a String (Section 3.3.3), a Token (Section 3.3.4), a Byte Sequence (Section 3.3.5), a Boolean (Section 3.3.6), or a Date (Section 3.3.7). It can have associated parameters (Section 3.1.2).

For example, a header field that is defined to be an Item that is an Integer might look like:

Example-Integer: 5

or with parameters:

Example-Integer: 5; foo=bar

3.3.1. Integers

Integers have a range of -999,999,999,999,999 to 999,999,999,999,999 inclusive (i.e., up to fifteen digits, signed), for IEEE 754 compatibility [IEEE754].

For example:

Example-Integer: 42

Integers larger than 15 digits can be supported in a variety of ways; for example, by using a String (Section 3.3.3), a Byte Sequence (Section 3.3.5), or a parameter on an Integer that acts as a scaling factor.

While it is possible to serialize Integers with leading zeros (e.g., "0002", "-01") and signed zero ("-0"), these distinctions may not be preserved by implementations.

Note that commas in Integers are used in this section's prose only for readability; they are not valid in the wire format.

3.3.2. Decimals

Decimals are numbers with an integer and a fractional component. The integer component has at most 12 digits; the fractional component has at most three digits.

For example, a header whose value is defined as a Decimal could look like:

Example-Decimal: 4.5

While it is possible to serialize Decimals with leading zeros (e.g., "0002.5", "-01.334"), trailing zeros (e.g., "5.230", "-0.40"), and signed zero (e.g., "-0.0"), these distinctions may not be preserved by implementations.

Note that the serialization algorithm (Section 4.1.5) rounds input with more than three digits of precision in the fractional component. If an alternative rounding strategy is desired, this should be specified by the field definition to occur before serialization.

3.3.3. Strings

Strings are zero or more printable ASCII [] characters (i.e., the range %x20 to %x7E). Note that this excludes tabs, newlines, carriage returns, etc.

Non-ASCII characters are not directly supported in Strings because they cause a number of interoperability issues, and -- with few exceptions -- field values do not require them.

When it is necessary for a field value to convey non-ASCII content, a Display String (Section 3.3.8) can be specified.

When serialized in a textual HTTP field, Strings are delimited with double quotes, using a backslash ("\") to escape double quotes and backslashes. For example:

Example-String: "hello world"

Note that Strings only use DQUOTE as a delimiter; single quotes do not delimit Strings. Furthermore, only DQUOTE and "\" can be escaped; other characters after "\" MUST cause parsing to fail.

Parsers MUST support Strings (after any decoding) with at least 1024 characters.

3.3.4. Tokens

Tokens are short textual words that begin with an alphabetic character or "*", followed by zero to many token characters, which are the same as those allowed by the "token" ABNF rule defined in [] plus the ":" and "/" characters.

For example:

Example-Token: foo123/456

Parsers MUST support Tokens with at least 512 characters.

Note that Tokens are defined largely for compatibility with the data model of existing HTTP fields and may require additional steps to use in some implementations. As a result, new fields are encouraged to use Strings.

3.3.5. Byte Sequences

Byte Sequences can be conveyed in Structured Fields.

When serialized in a textual HTTP field, a Byte Sequence is delimited with colons and encoded using base64 ([], Section 4). For example:

Example-ByteSequence: :cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==:

Parsers MUST support Byte Sequences with at least 16384 octets after decoding.

3.3.6. Booleans

Boolean values can be conveyed in Structured Fields.

When serialized in a textual HTTP field, a Boolean is indicated with a leading "?" character followed by a "1" for a true value or "0" for false. For example:

Example-Boolean: ?1

Note that in Dictionary (Section 3.2) and Parameter (Section 3.1.2) values, Boolean true is indicated by omitting the value.

3.3.7. Dates

Date values can be conveyed in Structured Fields.

Dates have a data model that is similar to Integers, representing a (possibly negative) delta in seconds from 1970-01-01T00:00:00Z, excluding leap seconds. Accordingly, their serialization in textual HTTP fields is similar to that of Integers, distinguished from them with a leading "@".

For example:

Example-Date: @1659578233

Parsers MUST support Dates whose values include all days in years 1 to 9999 (i.e., -62,135,596,800 to 253,402,214,400 delta seconds from 1970-01-01T00:00:00Z).

3.3.8. Display Strings

Display Strings are similar to Strings, in that they consist of zero or more characters, but they allow Unicode scalar values (i.e., all Unicode code points except for surrogates), unlike Strings.

Display Strings are intended for use in cases where a value is displayed to end users and therefore may need to carry non-ASCII content. It is NOT RECOMMENDED that they be used in situations where a String (Section 3.3.3) or Token (Section 3.3.4) would be adequate because Unicode has processing considerations (e.g., normalization) and security considerations (e.g., homograph attacks) that make it more difficult to handle correctly.

Note that Display Strings do not indicate the language used in the value; that can be done separately if necessary (e.g., with a parameter).

In textual HTTP fields, Display Strings are represented in a manner similar to Strings, except that non-ASCII characters are percent-encoded; there is a leading "%" to distinguish them from Strings.

For example:

Example-DisplayString: %"This is intended for display to %c3%bcsers."

See Section 6 for additional security considerations when handling Display Strings.

4. Working with Structured Fields in HTTP

This section defines how to serialize and parse the abstract types defined by Section 3 into textual HTTP field values and other encodings compatible with them (e.g., in HTTP/2 [] before compression with HPACK []).

4.1. Serializing Structured Fields

Given a structure defined in this specification, return an ASCII string suitable for use in an HTTP field value.

  1. If the structure is a Dictionary or List and its value is empty (i.e., it has no members), do not serialize the field at all (i.e., omit both the field-name and field-value).

  2. If the structure is a List, let output_string be the result of running Serializing a List (Section 4.1.1) with the structure.

  3. Else, if the structure is a Dictionary, let output_string be the result of running Serializing a Dictionary (Section 4.1.2) with the structure.

  4. Else, if the structure is an Item, let output_string be the result of running Serializing an Item (Section 4.1.3) with the structure.

  5. Else, fail serialization.

  6. Return output_string converted into an array of bytes, using ASCII encoding [].

4.1.1. Serializing a List

Given an array of (member_value, parameters) tuples as input_list, return an ASCII string suitable for use in an HTTP field value.

  1. Let output be an empty string.

  2. For each (member_value, parameters) of input_list:

    1. If member_value is an array, append the result of running Serializing an Inner List (Section 4.1.1.1) with (member_value, parameters) to output.

    2. Otherwise, append the result of running Serializing an Item (Section 4.1.3) with (member_value, parameters) to output.

    3. If more member_values remain in input_list:

      1. Append "," to output.

      2. Append a single SP to output.

  3. Return output.

4.1.1.1. Serializing an Inner List

Given an array of (member_value, parameters) tuples as inner_list, and parameters as list_parameters, return an ASCII string suitable for use in an HTTP field value.

  1. Let output be the string "(".

  2. For each (member_value, parameters) of inner_list:

    1. Append the result of running Serializing an Item (Section 4.1.3) with (member_value, parameters) to output.

    2. If more values remain in inner_list, append a single SP to output.

  3. Append ")" to output.

  4. Append the result of running Serializing Parameters (Section 4.1.1.2) with list_parameters to output.

  5. Return output.

4.1.1.2. Serializing Parameters

Given an ordered Dictionary as input_parameters (each member having a param_key and a param_value), return an ASCII string suitable for use in an HTTP field value.

  1. Let output be an empty string.

  2. For each param_key with a value of param_value in input_parameters:

    1. Append ";" to output.

    2. Append the result of running Serializing a Key (Section 4.1.1.3) with param_key to output.

    3. If param_value is not Boolean true:

      1. Append "=" to output.

      2. Append the result of running Serializing a bare Item (Section 4.1.3.1) with param_value to output.

  3. Return output.

4.1.1.3. Serializing a Key

Given a key as input_key, return an ASCII string suitable for use in an HTTP field value.

  1. Convert input_key into a sequence of ASCII characters; if conversion fails, fail serialization.

  2. If input_key contains characters not in lcalpha, DIGIT, "_", "-", ".", or "*", fail serialization.

  3. If the first character of input_key is not lcalpha or "*", fail serialization.

  4. Let output be an empty string.

  5. Append input_key to output.

  6. Return output.

4.1.2. Serializing a Dictionary

Given an ordered Dictionary as input_dictionary (each member having a member_key and a tuple value of (member_value, parameters)), return an ASCII string suitable for use in an HTTP field value.

  1. Let output be an empty string.

  2. For each member_key with a value of (member_value, parameters) in input_dictionary:

    1. Append the result of running Serializing a Key (Section 4.1.1.3) with member's member_key to output.

    2. If member_value is Boolean true:

      1. Append the result of running Serializing Parameters (Section 4.1.1.2) with parameters to output.

    3. Otherwise:

      1. Append "=" to output.

      2. If member_value is an array, append the result of running Serializing an Inner List (Section 4.1.1.1) with (member_value, parameters) to output.

      3. Otherwise, append the result of running Serializing an Item (Section 4.1.3) with (member_value, parameters) to output.

    4. If more members remain in input_dictionary:

      1. Append "," to output.

      2. Append a single SP to output.

  3. Return output.

4.1.3. Serializing an Item

Given an Item as bare_item and Parameters as item_parameters, return an ASCII string suitable for use in an HTTP field value.

  1. Let output be an empty string.

  2. Append the result of running Serializing a Bare Item (Section 4.1.3.1) with bare_item to output.

  3. Append the result of running Serializing Parameters (Section 4.1.1.2) with item_parameters to output.

  4. Return output.

4.1.3.1. Serializing a Bare Item

Given an Item as input_item, return an ASCII string suitable for use in an HTTP field value.

  1. If input_item is an Integer, return the result of running Serializing an Integer (Section 4.1.4) with input_item.

  2. If input_item is a Decimal, return the result of running Serializing a Decimal (Section 4.1.5) with input_item.

  3. If input_item is a String, return the result of running Serializing a String (Section 4.1.6) with input_item.

  4. If input_item is a Token, return the result of running Serializing a Token (Section 4.1.7) with input_item.

  5. If input_item is a Byte Sequence, return the result of running Serializing a Byte Sequence (Section 4.1.8) with input_item.

  6. If input_item is a Boolean, return the result of running Serializing a Boolean (Section 4.1.9) with input_item.

  7. If input_item is a Date, return the result of running Serializing a Date (Section 4.1.10) with input_item.

  8. If input_item is a Display String, return the result of running Serializing a Display String (Section 4.1.11) with input_item.

  9. Otherwise, fail serialization.

4.1.4. Serializing an Integer

Given an Integer as input_integer, return an ASCII string suitable for use in an HTTP field value.

  1. If input_integer is not an integer in the range of -999,999,999,999,999 to 999,999,999,999,999 inclusive, fail serialization.

  2. Let output be an empty string.

  3. If input_integer is less than (but not equal to) 0, append "-" to output.

  4. Append input_integer's numeric value represented in base 10 using only decimal digits to output.

  5. Return output.

4.1.5. Serializing a Decimal

Given a decimal number as input_decimal, return an ASCII string suitable for use in an HTTP field value.

  1. If input_decimal is not a decimal number, fail serialization.

  2. If input_decimal has more than three significant digits to the right of the decimal point, round it to three decimal places, rounding the final digit to the nearest value, or to the even value if it is equidistant.

  3. If input_decimal has more than 12 significant digits to the left of the decimal point after rounding, fail serialization.

  4. Let output be an empty string.

  5. If input_decimal is less than (but not equal to) 0, append "-" to output.

  6. Append input_decimal's integer component represented in base 10 (using only decimal digits) to output; if it is zero, append "0".

  7. Append "." to output.

  8. If input_decimal's fractional component is zero, append "0" to output.

  9. Otherwise, append the significant digits of input_decimal's fractional component represented in base 10 (using only decimal digits) to output.

  10. Return output.

4.1.6. Serializing a String

Given a String as input_string, return an ASCII string suitable for use in an HTTP field value.

  1. Convert input_string into a sequence of ASCII characters; if conversion fails, fail serialization.

  2. If input_string contains characters in the range %x00-1f or %x7f-ff (i.e., not in VCHAR or SP), fail serialization.

  3. Let output be the string DQUOTE.

  4. For each character char in input_string:

    1. If char is "\" or DQUOTE:

      1. Append "\" to output.

    2. Append char to output.

  5. Append DQUOTE to output.

  6. Return output.

4.1.7. Serializing a Token

Given a Token as input_token, return an ASCII string suitable for use in an HTTP field value.

  1. Convert input_token into a sequence of ASCII characters; if conversion fails, fail serialization.

  2. If the first character of input_token is not ALPHA or "*", or the remaining portion contains a character not in tchar, ":", or "/", fail serialization.

  3. Let output be an empty string.

  4. Append input_token to output.

  5. Return output.

4.1.8. Serializing a Byte Sequence

Given a Byte Sequence as input_bytes, return an ASCII string suitable for use in an HTTP field value.

  1. If input_bytes is not a sequence of bytes, fail serialization.

  2. Let output be an empty string.

  3. Append ":" to output.

  4. Append the result of base64-encoding input_bytes as per [], Section 4, taking account of the requirements below.

  5. Append ":" to output.

  6. Return output.

The encoded data is required to be padded with "=", as per [], Section 3.2.

Likewise, encoded data SHOULD have pad bits set to zero, as per [], Section 3.5, unless it is not possible to do so due to implementation constraints.

4.1.9. Serializing a Boolean

Given a Boolean as input_boolean, return an ASCII string suitable for use in an HTTP field value.

  1. If input_boolean is not a boolean, fail serialization.

  2. Let output be an empty string.

  3. Append "?" to output.

  4. If input_boolean is true, append "1" to output.

  5. If input_boolean is false, append "0" to output.

  6. Return output.

4.1.10. Serializing a Date

Given a Date as input_date, return an ASCII string suitable for use in an HTTP field value.

  1. Let output be "@".

  2. Append to output the result of running Serializing an Integer with input_date (Section 4.1.4).

  3. Return output.

4.1.11. Serializing a Display String

Given a sequence of Unicode code points as input_sequence, return an ASCII string suitable for use in an HTTP field value.

  1. If input_sequence is not a sequence of Unicode code points, fail serialization.

  2. Let byte_array be the result of applying UTF-8 encoding (Section 3 of []) to input_sequence. If encoding fails, fail serialization.

  3. Let encoded_string be a string containing "%" followed by DQUOTE.

  4. For each byte in byte_array:

    1. If byte is %x25 ("%"), %x22 (DQUOTE), or in the ranges %x00-1f or %x7f-ff:

      1. Append "%" to encoded_string.

      2. Let encoded_byte be the result of applying base16 encoding (