rfc9651.original | rfc9651.txt | |||
---|---|---|---|---|
HTTP M. Nottingham | Internet Engineering Task Force (IETF) M. Nottingham | |||
Internet-Draft Cloudflare | Request for Comments: 9651 Cloudflare | |||
Obsoletes: 8941 (if approved) P.-H. Kamp | Obsoletes: 8941 P-H. Kamp | |||
Intended status: Standards Track The Varnish Cache Project | Category: Standards Track The Varnish Cache Project | |||
Expires: 23 October 2024 21 April 2024 | ISSN: 2070-1721 September 2024 | |||
Structured Field Values for HTTP | Structured Field Values for HTTP | |||
draft-ietf-httpbis-sfbis-06 | ||||
Abstract | Abstract | |||
This document describes a set of data types and associated algorithms | This document describes a set of data types and associated algorithms | |||
that are intended to make it easier and safer to define and handle | that are intended to make it easier and safer to define and handle | |||
HTTP header and trailer fields, known as "Structured Fields", | HTTP header and trailer fields, known as "Structured Fields", | |||
"Structured Headers", or "Structured Trailers". It is intended for | "Structured Headers", or "Structured Trailers". It is intended for | |||
use by specifications of new HTTP fields that wish to use a common | use by specifications of new HTTP fields. | |||
syntax that is more restrictive than traditional HTTP field values. | ||||
This document obsoletes RFC 8941. | This document obsoletes RFC 8941. | |||
About This Document | ||||
This note is to be removed before publishing as an RFC. | ||||
Status information for this document may be found at | ||||
https://datatracker.ietf.org/doc/draft-ietf-httpbis-sfbis/. | ||||
Discussion of this document takes place on the HTTP Working Group | ||||
mailing list (mailto:ietf-http-wg@w3.org), which is archived at | ||||
https://lists.w3.org/Archives/Public/ietf-http-wg/. Working Group | ||||
information can be found at https://httpwg.org/. | ||||
Source for this draft and an issue tracker can be found at | ||||
https://github.com/httpwg/http-extensions/labels/header-structure. | ||||
Status of This Memo | Status of This Memo | |||
This Internet-Draft is submitted in full conformance with the | This is an Internet Standards Track document. | |||
provisions of BCP 78 and BCP 79. | ||||
Internet-Drafts are working documents of the Internet Engineering | ||||
Task Force (IETF). Note that other groups may also distribute | ||||
working documents as Internet-Drafts. The list of current Internet- | ||||
Drafts is at https://datatracker.ietf.org/drafts/current/. | ||||
Internet-Drafts are draft documents valid for a maximum of six months | This document is a product of the Internet Engineering Task Force | |||
and may be updated, replaced, or obsoleted by other documents at any | (IETF). It represents the consensus of the IETF community. It has | |||
time. It is inappropriate to use Internet-Drafts as reference | received public review and has been approved for publication by the | |||
material or to cite them other than as "work in progress." | Internet Engineering Steering Group (IESG). Further information on | |||
Internet Standards is available in Section 2 of RFC 7841. | ||||
This Internet-Draft will expire on 23 October 2024. | Information about the current status of this document, any errata, | |||
and how to provide feedback on it may be obtained at | ||||
https://www.rfc-editor.org/info/rfc9651. | ||||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2024 IETF Trust and the persons identified as the | Copyright (c) 2024 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents (https://trustee.ietf.org/ | Provisions Relating to IETF Documents | |||
license-info) in effect on the date of publication of this document. | (https://trustee.ietf.org/license-info) in effect on the date of | |||
Please review these documents carefully, as they describe your rights | publication of this document. Please review these documents | |||
and restrictions with respect to this document. Code Components | carefully, as they describe your rights and restrictions with respect | |||
extracted from this document must include Revised BSD License text as | to this document. Code Components extracted from this document must | |||
described in Section 4.e of the Trust Legal Provisions and are | include Revised BSD License text as described in Section 4.e of the | |||
provided without warranty as described in the Revised BSD License. | Trust Legal Provisions and are provided without warranty as described | |||
in the Revised BSD License. | ||||
Table of Contents | Table of Contents | |||
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 | 1. Introduction | |||
1.1. Intentionally Strict Processing . . . . . . . . . . . . . 4 | 1.1. Intentionally Strict Processing | |||
1.2. Notational Conventions . . . . . . . . . . . . . . . . . 5 | 1.2. Notational Conventions | |||
2. Defining New Structured Fields . . . . . . . . . . . . . . . 5 | 2. Defining New Structured Fields | |||
2.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 6 | 2.1. Example | |||
2.2. Error Handling . . . . . . . . . . . . . . . . . . . . . 7 | 2.2. Error Handling | |||
2.3. Preserving Extensibility . . . . . . . . . . . . . . . . 7 | 2.3. Preserving Extensibility | |||
2.4. Using New Structured Types in Extensions . . . . . . . . 8 | 2.4. Using New Structured Types in Extensions | |||
3. Structured Data Types . . . . . . . . . . . . . . . . . . . . 9 | 3. Structured Data Types | |||
3.1. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 9 | 3.1. Lists | |||
3.1.1. Inner Lists . . . . . . . . . . . . . . . . . . . . . 10 | 3.1.1. Inner Lists | |||
3.1.2. Parameters . . . . . . . . . . . . . . . . . . . . . 10 | 3.1.2. Parameters | |||
3.2. Dictionaries . . . . . . . . . . . . . . . . . . . . . . 11 | 3.2. Dictionaries | |||
3.3. Items . . . . . . . . . . . . . . . . . . . . . . . . . . 13 | 3.3. Items | |||
3.3.1. Integers . . . . . . . . . . . . . . . . . . . . . . 13 | 3.3.1. Integers | |||
3.3.2. Decimals . . . . . . . . . . . . . . . . . . . . . . 13 | 3.3.2. Decimals | |||
3.3.3. Strings . . . . . . . . . . . . . . . . . . . . . . . 14 | 3.3.3. Strings | |||
3.3.4. Tokens . . . . . . . . . . . . . . . . . . . . . . . 14 | 3.3.4. Tokens | |||
3.3.5. Byte Sequences . . . . . . . . . . . . . . . . . . . 15 | 3.3.5. Byte Sequences | |||
3.3.6. Booleans . . . . . . . . . . . . . . . . . . . . . . 15 | 3.3.6. Booleans | |||
3.3.7. Dates . . . . . . . . . . . . . . . . . . . . . . . . 15 | 3.3.7. Dates | |||
3.3.8. Display Strings . . . . . . . . . . . . . . . . . . . 16 | 3.3.8. Display Strings | |||
4. Working with Structured Fields in HTTP . . . . . . . . . . . 16 | 4. Working with Structured Fields in HTTP | |||
4.1. Serializing Structured Fields . . . . . . . . . . . . . . 16 | 4.1. Serializing Structured Fields | |||
4.1.1. Serializing a List . . . . . . . . . . . . . . . . . 17 | 4.1.1. Serializing a List | |||
4.1.2. Serializing a Dictionary . . . . . . . . . . . . . . 19 | 4.1.2. Serializing a Dictionary | |||
4.1.3. Serializing an Item . . . . . . . . . . . . . . . . . 20 | 4.1.3. Serializing an Item | |||
4.1.4. Serializing an Integer . . . . . . . . . . . . . . . 21 | 4.1.4. Serializing an Integer | |||
4.1.5. Serializing a Decimal . . . . . . . . . . . . . . . . 21 | 4.1.5. Serializing a Decimal | |||
4.1.6. Serializing a String . . . . . . . . . . . . . . . . 22 | 4.1.6. Serializing a String | |||
4.1.7. Serializing a Token . . . . . . . . . . . . . . . . . 22 | 4.1.7. Serializing a Token | |||
4.1.8. Serializing a Byte Sequence . . . . . . . . . . . . . 23 | 4.1.8. Serializing a Byte Sequence | |||
4.1.9. Serializing a Boolean . . . . . . . . . . . . . . . . 23 | 4.1.9. Serializing a Boolean | |||
4.1.10. Serializing a Date . . . . . . . . . . . . . . . . . 23 | 4.1.10. Serializing a Date | |||
4.1.11. Serializing a Display String . . . . . . . . . . . . 24 | 4.1.11. Serializing a Display String | |||
4.2. Parsing Structured Fields . . . . . . . . . . . . . . . . 25 | 4.2. Parsing Structured Fields | |||
4.2.1. Parsing a List . . . . . . . . . . . . . . . . . . . 26 | 4.2.1. Parsing a List | |||
4.2.2. Parsing a Dictionary . . . . . . . . . . . . . . . . 28 | 4.2.2. Parsing a Dictionary | |||
4.2.3. Parsing an Item . . . . . . . . . . . . . . . . . . . 29 | 4.2.3. Parsing an Item | |||
4.2.4. Parsing an Integer or Decimal . . . . . . . . . . . . 31 | 4.2.4. Parsing an Integer or Decimal | |||
4.2.5. Parsing a String . . . . . . . . . . . . . . . . . . 33 | 4.2.5. Parsing a String | |||
4.2.6. Parsing a Token . . . . . . . . . . . . . . . . . . . 33 | 4.2.6. Parsing a Token | |||
4.2.7. Parsing a Byte Sequence . . . . . . . . . . . . . . . 34 | 4.2.7. Parsing a Byte Sequence | |||
4.2.8. Parsing a Boolean . . . . . . . . . . . . . . . . . . 35 | 4.2.8. Parsing a Boolean | |||
4.2.9. Parsing a Date . . . . . . . . . . . . . . . . . . . 35 | 4.2.9. Parsing a Date | |||
4.2.10. Parsing a Display String . . . . . . . . . . . . . . 35 | 4.2.10. Parsing a Display String | |||
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 | 5. IANA Considerations | |||
6. Security Considerations . . . . . . . . . . . . . . . . . . . 38 | 6. Security Considerations | |||
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 | 7. References | |||
7.1. Normative References . . . . . . . . . . . . . . . . . . 38 | 7.1. Normative References | |||
7.2. Informative References . . . . . . . . . . . . . . . . . 39 | 7.2. Informative References | |||
Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 39 | Appendix A. Frequently Asked Questions | |||
A.1. Why Not JSON? . . . . . . . . . . . . . . . . . . . . . . 40 | A.1. Why Not JSON? | |||
Appendix B. Implementation Notes . . . . . . . . . . . . . . . . 40 | Appendix B. Implementation Notes | |||
Appendix C. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 41 | Appendix C. ABNF | |||
Appendix D. Changes from RFC 8941 . . . . . . . . . . . . . . . 42 | Appendix D. Changes from RFC 8941 | |||
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 43 | Acknowledgements | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 | Authors' Addresses | |||
1. Introduction | 1. Introduction | |||
Specifying the syntax of new HTTP header (and trailer) fields is an | Specifying the syntax of new HTTP header (and trailer) fields is an | |||
onerous task; even with the guidance in Section 16.3.2 of [HTTP], | onerous task; even with the guidance in Section 16.3.2 of [HTTP], | |||
there are many decisions -- and pitfalls -- for a prospective HTTP | there are many decisions -- and pitfalls -- for a prospective HTTP | |||
field author. | field author. | |||
Once a field is defined, bespoke parsers and serializers often need | Once a field is defined, bespoke parsers and serializers often need | |||
to be written, because each field value has a slightly different | to be written, because each field value has a slightly different | |||
skipping to change at page 5, line 14 ¶ | skipping to change at line 176 ¶ | |||
Note that as a result of this strictness, if a field is appended to | Note that as a result of this strictness, if a field is appended to | |||
by multiple parties (e.g., intermediaries or different components in | by multiple parties (e.g., intermediaries or different components in | |||
the sender), an error in one party's value is likely to cause the | the sender), an error in one party's value is likely to cause the | |||
entire field value to fail parsing. | entire field value to fail parsing. | |||
1.2. Notational Conventions | 1.2. Notational Conventions | |||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | |||
"OPTIONAL" in this document are to be interpreted as described in BCP | "OPTIONAL" in this document are to be interpreted as described in | |||
14 [RFC2119] [RFC8174] when, and only when, they appear in all | BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all | |||
capitals, as shown here. | capitals, as shown here. | |||
This document uses the VCHAR, SP, DIGIT, ALPHA, and DQUOTE rules from | This document uses the VCHAR, SP, DIGIT, ALPHA, and DQUOTE rules from | |||
[RFC5234] to specify characters and/or their corresponding ASCII | [RFC5234] to specify characters and/or their corresponding ASCII | |||
bytes, depending on context. It uses the tchar and OWS rules from | bytes, depending on context. It uses the tchar and OWS rules from | |||
[HTTP] for the same purpose. | [HTTP] for the same purpose. | |||
This document uses algorithms to specify parsing and serialization | This document uses algorithms to specify parsing and serialization | |||
behaviors. When parsing from HTTP fields, implementations MUST have | behaviors. When parsing from HTTP fields, implementations MUST have | |||
behavior that is indistinguishable from following the algorithms. | behavior that is indistinguishable from following the algorithms. | |||
skipping to change at page 6, line 15 ¶ | skipping to change at line 225 ¶ | |||
Typically, this means that a field definition will specify the top- | Typically, this means that a field definition will specify the top- | |||
level type -- List, Dictionary, or Item -- and then define its | level type -- List, Dictionary, or Item -- and then define its | |||
allowable types and constraints upon them. For example, a header | allowable types and constraints upon them. For example, a header | |||
defined as a List might have all Integer members, or a mix of types; | 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 | a header defined as an Item might allow only Strings, and | |||
additionally only strings beginning with the letter "Q", or strings | additionally only strings beginning with the letter "Q", or strings | |||
in lowercase. Likewise, Inner Lists (Section 3.1.1) are only valid | in lowercase. Likewise, Inner Lists (Section 3.1.1) are only valid | |||
when a field definition explicitly allows them. | when a field definition explicitly allows them. | |||
Fields that use the Display String type are advised to carefully | Fields that use the Display String type are advised to carefully | |||
specify their allowable unicode code points; for example, specifying | specify their allowable Unicode code points; for example, specifying | |||
the use of a profile from [PRECIS]. | the use of a profile from [PRECIS]. | |||
Field definitions can only use this specification for the entire | Field definitions can only use this specification for the entire | |||
field value, not a portion thereof. | field value, not a portion thereof. | |||
Specifications can refer to a field name as a "structured header | Specifications can refer to a field name as a "Structured Header | |||
name", "structured trailer name", or "structured field name" as | name", "Structured Trailer name", or "Structured Field name" as | |||
appropriate. Likewise, they can refer its field value as a | appropriate. Likewise, they can refer its field value as a | |||
"structured header value", "structured trailer value", or "structured | "Structured Header value", "Structured Trailer value", or "Structured | |||
field value" as necessary. | Field value" as necessary. | |||
This specification defines minimums for the length or number of | This specification defines minimums for the length or number of | |||
various structures supported by implementations. It does not specify | various structures supported by implementations. It does not specify | |||
maximum sizes in most cases, but authors should be aware that HTTP | maximum sizes in most cases, but authors should be aware that HTTP | |||
implementations do impose various limits on the size of individual | implementations do impose various limits on the size of individual | |||
fields, the total number of fields, and/or the size of the entire | fields, the total number of fields, and/or the size of the entire | |||
header or trailer section. | header or trailer section. | |||
2.1. Example | 2.1. Example | |||
A fictitious Foo-Example header field might be specified as: | A fictitious Foo-Example header field might be specified as: | |||
| 42. Foo-Example Header Field | | 42. Foo-Example Header Field | |||
| | | | |||
| The Foo-Example HTTP header field conveys information about how | | The Foo-Example HTTP header field conveys information about how | |||
| much Foo the message has. | | much Foo the message has. | |||
| | | | |||
| Foo-Example is an Item Structured Header Field [RFCnnnn]. Its | | Foo-Example is an Item Structured Header Field [RFC9651]. Its | |||
| value MUST be an Integer (Section 3.3.1 of [RFCnnnn]). | | value MUST be an Integer (Section 3.3.1 of [RFC9651]). | |||
| | | | |||
| Its value indicates the amount of Foo in the message, and it MUST | | 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 | | be between 0 and 10, inclusive; other values MUST cause the entire | |||
| header field to be ignored. | | header field to be ignored. | |||
| | | | |||
| The following parameter is defined: | | The following parameter is defined: | |||
| | | | |||
| * A parameter whose key is "foourl", and whose value is a String | | * A parameter whose key is "foourl", and whose value is a String | |||
| (Section 3.3.3 of [RFCnnnn]), conveying the Foo URL for the | | (Section 3.3.3 of [RFC9651]), conveying the Foo URL for the | |||
| message. See below for processing requirements. | | message. See below for processing requirements. | |||
| | | | |||
| "foourl" contains a URI-reference (Section 4.1 of [RFC3986]). If | | "foourl" contains a URI-reference (Section 4.1 of [RFC3986]). If | |||
| its value is not a valid URI-reference, the entire header field | | its value is not a valid URI-reference, the entire header field | |||
| MUST be ignored. If its value is a relative reference | | MUST be ignored. If its value is a relative reference | |||
| (Section 4.2 of [RFC3986]), it MUST be resolved (Section 5 of | | (Section 4.2 of [RFC3986]), it MUST be resolved (Section 5 of | |||
| [RFC3986]) before being used. | | [RFC3986]) before being used. | |||
| | | | |||
| For example: | | For example: | |||
| | | | |||
| Foo-Example: 2; foourl="https://foo.example.com/" | | Foo-Example: 2; foourl="https://foo.example.com/" | |||
2.2. Error Handling | 2.2. Error Handling | |||
When parsing fails, the entire field is ignored (see Section 4.2). | When parsing fails, the entire field is ignored (see Section 4.2). | |||
Field definitions cannot override this, because doing so would | Field definitions cannot override this because doing so would | |||
preclude handling by generic software; they can only add additional | preclude handling by generic software; they can only add additional | |||
constraints (for example, on the numeric range of Integers and | constraints (for example, on the numeric range of Integers and | |||
Decimals, the format of Strings and Tokens, the types allowed in a | Decimals, the format of Strings and Tokens, the types allowed in a | |||
Dictionary's values, or the number of Items in a List). | Dictionary's values, or the number of Items in a List). | |||
When field-specific constraints are violated, the entire field is | When field-specific constraints are violated, the entire field is | |||
also ignored, unless the field definition defines other handling | also ignored, unless the field definition defines other handling | |||
requirements. For example, if a header field is defined as an Item | 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 | and required to be an Integer, but a String is received, it should be | |||
ignored unless that field's definition explicitly specifies | ignored unless that field's definition explicitly specifies | |||
otherwise. | otherwise. | |||
2.3. Preserving Extensibility | 2.3. Preserving Extensibility | |||
Structured Fields are designed to be extensible, because experience | Structured Fields are designed to be extensible because experience | |||
has shown that even when it is not foreseen, it is often necessary to | has shown that, even when it is not foreseen, it is often necessary | |||
modify and add to the allowable syntax and semantics of a field in a | to modify and add to the allowable syntax and semantics of a field in | |||
controlled fashion. | a controlled fashion. | |||
Both Items and Inner Lists allow Parameters as an extensibility | Both Items and Inner Lists allow Parameters as an extensibility | |||
mechanism; this means that their values can later be extended to | mechanism; this means that their values can later be extended to | |||
accommodate more information, if need be. To preserve forward | accommodate more information, if need be. To preserve forward | |||
compatibility, field specifications are discouraged from defining the | compatibility, field specifications are discouraged from defining the | |||
presence of an unrecognized parameter as an error condition. | presence of an unrecognized parameter as an error condition. | |||
Field specifications are required to be either an Item, List, or | Field specifications are required to be either an Item, List, or | |||
Dictionary to preserve extensibility. Fields that erroneously | Dictionary to preserve extensibility. Fields that erroneously | |||
defined as another type (e.g., Integer) are assumed to be Items | defined as another type (e.g., Integer) are assumed to be Items | |||
skipping to change at page 8, line 31 ¶ | skipping to change at line 336 ¶ | |||
field value be ignored by a recipient that understands the extension | field value be ignored by a recipient that understands the extension | |||
if constraints on the value it defines are not met. | if constraints on the value it defines are not met. | |||
2.4. Using New Structured Types in Extensions | 2.4. Using New Structured Types in Extensions | |||
Because a field definition needs to reference a specific RFC for | Because a field definition needs to reference a specific RFC for | |||
Structured Fields, the types available for use in its value are | Structured Fields, the types available for use in its value are | |||
limited to those defined in that RFC. For example, a field whose | limited to those defined in that RFC. For example, a field whose | |||
definition references this document can have a value that uses the | definition references this document can have a value that uses the | |||
Date type (Section 3.3.7), whereas a field whose definition | Date type (Section 3.3.7), whereas a field whose definition | |||
references RFC 8941 cannot, because it will be treated as invalid | references RFC 8941 cannot because it will be treated as invalid (and | |||
(and therefore discarded) by implementations of that specification. | therefore discarded) by implementations of that specification. | |||
This limitation also applies to future extensions to a field; for | This limitation also applies to future extensions to a field; for | |||
example, a field that is defined with reference to RFC 8941 cannot | example, a field that is defined with a reference to RFC 8941 cannot | |||
use the Date type, because some recipients might still be using an | use the Date type because some recipients might still be using a | |||
RFC 8941 parser to process it. | parser based on RFC 8941 to process it. | |||
However, this document is designed to be backwards-compatible with | However, this document is designed to be backward compatible with RFC | |||
RFC 8941; a parser that implements the requirements here can also | 8941; a parser that implements the requirements here can also parse | |||
parse valid Structured Fields whose definitions reference RFC 8941. | valid Structured Fields whose definitions reference RFC 8941. | |||
Upgrading a Structured Fields implementation to support a newer | Upgrading a Structured Fields implementation to support a newer | |||
revision of the specification (such as this document) brings the | revision of the specification (such as this document) brings the | |||
possibility that some field values that were invalid according to the | possibility that some field values that were invalid according to the | |||
earlier RFC might become valid when processed. | earlier RFC might become valid when processed. | |||
For example, field instance might contain a syntactically valid Date | For example, a field instance might contain a syntactically valid | |||
(Section 3.3.7), even though that field's definition does not | Date (Section 3.3.7), even though that field's definition does not | |||
accommodate Dates. An RFC8941 implementation would fail parsing such | accommodate Dates. An implementation based on RFC 8941 would fail | |||
a field instance, because they are not defined in that specification. | parsing such a field instance because it is not defined in that | |||
If that implementation were upgraded to this specification, parsing | specification. If that implementation were upgraded to this | |||
would now succeed. In some cases, the resulting Date value will be | specification, parsing would now succeed. In some cases, the | |||
rejected by field-specific logic, but values in fields that are | resulting Date value will be rejected by field-specific logic, but | |||
otherwise ignored (such as extension parameters) might not be | values in fields that are otherwise ignored (such as extension | |||
detected and the field might subsequently be accepted and processed. | parameters) might not be detected, and the field might subsequently | |||
be accepted and processed. | ||||
3. Structured Data Types | 3. Structured Data Types | |||
This section provides an overview of the abstract types that | This section provides an overview of the abstract types that | |||
Structured Fields use, and gives a brief description and examples of | Structured Fields use and gives a brief description and examples of | |||
how each of those types are serialized into textual HTTP fields. | how each of those types are serialized into textual HTTP fields. | |||
Section 4 specifies the details of how they are parsed from and | Section 4 specifies the details of how they are parsed from and | |||
serialized into textual HTTP fields. | serialized into textual HTTP fields. | |||
In summary: | In summary: | |||
* There are three top-level types that an HTTP field can be defined | * There are three top-level types that an HTTP field can be defined | |||
as: Lists, Dictionaries, and Items. | as: Lists, Dictionaries, and Items. | |||
* Lists and Dictionaries are containers; their members can be Items | * Lists and Dictionaries are containers; their members can be Items | |||
skipping to change at page 11, line 49 ¶ | skipping to change at line 498 ¶ | |||
entire field. This implies that fields defined as Dictionaries have | entire field. This implies that fields defined as Dictionaries have | |||
a default empty value. | a default empty value. | |||
Typically, a field specification will define the semantics of | Typically, a field specification will define the semantics of | |||
Dictionaries by specifying the allowed type(s) for individual members | Dictionaries by specifying the allowed type(s) for individual members | |||
by their keys, as well as whether their presence is required or | by their keys, as well as whether their presence is required or | |||
optional. Recipients MUST ignore members whose keys are undefined or | optional. Recipients MUST ignore members whose keys are undefined or | |||
unknown, unless the field's specification specifically disallows | unknown, unless the field's specification specifically disallows | |||
them. | them. | |||
When serialized as a textual HTTP field, Members are ordered as | When serialized as a textual HTTP field, members are ordered as | |||
serialized and separated by a comma with optional whitespace. Member | serialized and separated by a comma with optional whitespace. Member | |||
keys cannot contain uppercase characters. Keys and values are | keys cannot contain uppercase characters. Keys and values are | |||
separated by "=" (without whitespace). For example: | separated by "=" (without whitespace). For example: | |||
Example-Dict: en="Applepie", da=:w4ZibGV0w6ZydGU=: | Example-Dict: en="Applepie", da=:w4ZibGV0w6ZydGU=: | |||
Note that in this example, the final "=" is due to the inclusion of a | Note that in this example, the final "=" is due to the inclusion of a | |||
Byte Sequence; see Section 3.3.5. | Byte Sequence; see Section 3.3.5. | |||
Members whose value is Boolean (see Section 3.3.6) true MUST omit | Members whose value is Boolean (see Section 3.3.6) true MUST omit | |||
skipping to change at page 14, line 4 ¶ | skipping to change at line 594 ¶ | |||
3.3.2. Decimals | 3.3.2. Decimals | |||
Decimals are numbers with an integer and a fractional component. The | Decimals are numbers with an integer and a fractional component. The | |||
integer component has at most 12 digits; the fractional component has | integer component has at most 12 digits; the fractional component has | |||
at most three digits. | at most three digits. | |||
For example, a header whose value is defined as a Decimal could look | For example, a header whose value is defined as a Decimal could look | |||
like: | like: | |||
Example-Decimal: 4.5 | Example-Decimal: 4.5 | |||
While it is possible to serialize Decimals with leading zeros (e.g., | 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 | "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 | signed zero (e.g., "-0.0"), these distinctions may not be preserved | |||
by implementations. | by implementations. | |||
Note that the serialization algorithm (Section 4.1.5) rounds input | Note that the serialization algorithm (Section 4.1.5) rounds input | |||
with more than three digits of precision in the fractional component. | with more than three digits of precision in the fractional component. | |||
If an alternative rounding strategy is desired, this should be | If an alternative rounding strategy is desired, this should be | |||
specified by the field definition to occur before serialization. | specified by the field definition to occur before serialization. | |||
3.3.3. Strings | 3.3.3. Strings | |||
Strings are zero or more printable ASCII [RFC0020] characters (i.e., | Strings are zero or more printable ASCII [RFC0020] characters (i.e., | |||
the range %x20 to %x7E). Note that this excludes tabs, newlines, | the range %x20 to %x7E). Note that this excludes tabs, newlines, | |||
carriage returns, etc. | carriage returns, etc. | |||
Non-ASCII characters are not directly supported in Strings, because | Non-ASCII characters are not directly supported in Strings because | |||
they cause a number of interoperability issues, and -- with few | they cause a number of interoperability issues, and -- with few | |||
exceptions -- field values do not require them. | exceptions -- field values do not require them. | |||
When it is necessary for a field value to convey non-ASCII content, a | When it is necessary for a field value to convey non-ASCII content, a | |||
Display String (Section 3.3.8) can be specified. | Display String (Section 3.3.8) can be specified. | |||
When serialized in a textual HTTP field, Strings are delimited with | When serialized in a textual HTTP field, Strings are delimited with | |||
double quotes, using a backslash ("\") to escape double quotes and | double quotes, using a backslash ("\") to escape double quotes and | |||
backslashes. For example: | backslashes. For example: | |||
skipping to change at page 14, line 45 ¶ | skipping to change at line 636 ¶ | |||
escaped; other characters after "\" MUST cause parsing to fail. | escaped; other characters after "\" MUST cause parsing to fail. | |||
Parsers MUST support Strings (after any decoding) with at least 1024 | Parsers MUST support Strings (after any decoding) with at least 1024 | |||
characters. | characters. | |||
3.3.4. Tokens | 3.3.4. Tokens | |||
Tokens are short textual words that begin with an alphabetic | Tokens are short textual words that begin with an alphabetic | |||
character or "*", followed by zero to many token characters, which | character or "*", followed by zero to many token characters, which | |||
are the same as those allowed by the "token" ABNF rule defined in | are the same as those allowed by the "token" ABNF rule defined in | |||
[HTTP], plus the ":" and "/" characters. | [HTTP] plus the ":" and "/" characters. | |||
For example: | For example: | |||
Example-Token: foo123/456 | Example-Token: foo123/456 | |||
Parsers MUST support Tokens with at least 512 characters. | Parsers MUST support Tokens with at least 512 characters. | |||
Note that Tokens are defined largely for compatibility with the data | Note that Tokens are defined largely for compatibility with the data | |||
model of existing HTTP fields, and may require additional steps to | model of existing HTTP fields and may require additional steps to use | |||
use in some implementations. As a result, new fields are encouraged | in some implementations. As a result, new fields are encouraged to | |||
to use Strings. | use Strings. | |||
3.3.5. Byte Sequences | 3.3.5. Byte Sequences | |||
Byte Sequences can be conveyed in Structured Fields. | Byte Sequences can be conveyed in Structured Fields. | |||
When serialized in a textual HTTP field, a Byte Sequence is delimited | When serialized in a textual HTTP field, a Byte Sequence is delimited | |||
with colons and encoded using base64 ([RFC4648], Section 4). For | with colons and encoded using base64 ([RFC4648], Section 4). For | |||
example: | example: | |||
Example-ByteSequence: :cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==: | Example-ByteSequence: :cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==: | |||
skipping to change at page 16, line 12 ¶ | skipping to change at line 700 ¶ | |||
to 9999 (i.e., -62,135,596,800 to 253,402,214,400 delta seconds from | to 9999 (i.e., -62,135,596,800 to 253,402,214,400 delta seconds from | |||
1970-01-01T00:00:00Z). | 1970-01-01T00:00:00Z). | |||
3.3.8. Display Strings | 3.3.8. Display Strings | |||
Display Strings are similar to Strings, in that they consist of zero | Display Strings are similar to Strings, in that they consist of zero | |||
or more characters, but they allow Unicode scalar values (i.e., all | or more characters, but they allow Unicode scalar values (i.e., all | |||
Unicode code points except for surrogates), unlike Strings. | Unicode code points except for surrogates), unlike Strings. | |||
Display Strings are intended for use in cases where a value is | Display Strings are intended for use in cases where a value is | |||
displayed to end users, and therefore may need to carry non-ASCII | displayed to end users and therefore may need to carry non-ASCII | |||
content. It is NOT RECOMMENDED that they be used in situations where | 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, | a String (Section 3.3.3) or Token (Section 3.3.4) would be adequate | |||
because Unicode has processing considerations (e.g., normalization) | because Unicode has processing considerations (e.g., normalization) | |||
and security considerations (e.g., homograph attacks) that make it | and security considerations (e.g., homograph attacks) that make it | |||
more difficult to handle correctly. | more difficult to handle correctly. | |||
Note that Display Strings do not indicate the language used in the | Note that Display Strings do not indicate the language used in the | |||
value; that can be done separately if necessary (e.g., with a | value; that can be done separately if necessary (e.g., with a | |||
parameter). | parameter). | |||
In textual HTTP fields, Display Strings are represented in a manner | In textual HTTP fields, Display Strings are represented in a manner | |||
similar to Strings, except that non-ASCII characters are percent- | similar to Strings, except that non-ASCII characters are percent- | |||
skipping to change at page 24, line 12 ¶ | skipping to change at line 1084 ¶ | |||
1. Let output be "@". | 1. Let output be "@". | |||
2. Append to output the result of running Serializing an Integer | 2. Append to output the result of running Serializing an Integer | |||
with input_date (Section 4.1.4). | with input_date (Section 4.1.4). | |||
3. Return output. | 3. Return output. | |||
4.1.11. Serializing a Display String | 4.1.11. Serializing a Display String | |||
Given a sequence of Unicode codepoints as input_sequence, return an | Given a sequence of Unicode code points as input_sequence, return an | |||
ASCII string suitable for use in an HTTP field value. | ASCII string suitable for use in an HTTP field value. | |||
1. If input_sequence is not a sequence of Unicode codepoints, fail | 1. If input_sequence is not a sequence of Unicode code points, fail | |||
serialization. | serialization. | |||
2. Let byte_array be the result of applying UTF-8 encoding | 2. Let byte_array be the result of applying UTF-8 encoding | |||
(Section 3 of [UTF8]) to input_sequence. If encoding fails, fail | (Section 3 of [UTF8]) to input_sequence. If encoding fails, fail | |||
serialization. | serialization. | |||
3. Let encoded_string be a string containing "%" followed by DQUOTE. | 3. Let encoded_string be a string containing "%" followed by DQUOTE. | |||
4. For each byte in byte_array: | 4. For each byte in byte_array: | |||
skipping to change at page 24, line 44 ¶ | skipping to change at line 1116 ¶ | |||
3. Append encoded_byte to encoded_string. | 3. Append encoded_byte to encoded_string. | |||
2. Otherwise, decode byte as an ASCII character and append the | 2. Otherwise, decode byte as an ASCII character and append the | |||
result to encoded_string. | result to encoded_string. | |||
5. Append DQUOTE to encoded_string. | 5. Append DQUOTE to encoded_string. | |||
6. Return encoded_string. | 6. Return encoded_string. | |||
Note that [UTF8] prohibits the encoding of codepoints between U+D800 | Note that [UTF8] prohibits the encoding of code points between U+D800 | |||
and U+DFFF (surrogates); if they occur in input_sequence, | and U+DFFF (surrogates); if they occur in input_sequence, | |||
serialization will fail. | serialization will fail. | |||
4.2. Parsing Structured Fields | 4.2. Parsing Structured Fields | |||
When a receiving implementation parses HTTP fields that are known to | When a receiving implementation parses HTTP fields that are known to | |||
be Structured Fields, it is important that care be taken, as there | be Structured Fields, it is important that care be taken, as there | |||
are a number of edge cases that can cause interoperability or even | are a number of edge cases that can cause interoperability or even | |||
security problems. This section specifies the algorithm for doing | security problems. This section specifies the algorithm for doing | |||
so. | so. | |||
skipping to change at page 35, line 50 ¶ | skipping to change at line 1641 ¶ | |||
3. Let output_date be the result of running Parsing an Integer or | 3. Let output_date be the result of running Parsing an Integer or | |||
Decimal (Section 4.2.4) with input_string. | Decimal (Section 4.2.4) with input_string. | |||
4. If output_date is a Decimal, fail parsing. | 4. If output_date is a Decimal, fail parsing. | |||
5. Return output_date. | 5. Return output_date. | |||
4.2.10. Parsing a Display String | 4.2.10. Parsing a Display String | |||
Given an ASCII string as input_string, return a sequence of Unicode | Given an ASCII string as input_string, return a sequence of Unicode | |||
codepoints. input_string is modified to remove the parsed value. | code points. input_string is modified to remove the parsed value. | |||
1. If the first two characters of input_string are not "%" followed | 1. If the first two characters of input_string are not "%" followed | |||
by DQUOTE, fail parsing. | by DQUOTE, fail parsing. | |||
2. Discard the first two characters of input_string. | 2. Discard the first two characters of input_string. | |||
3. Let byte_array be an empty byte array. | 3. Let byte_array be an empty byte array. | |||
4. While input_string is not empty: | 4. While input_string is not empty: | |||
skipping to change at page 37, line 7 ¶ | skipping to change at line 1693 ¶ | |||
1. Let byte be the result of applying ASCII encoding to | 1. Let byte be the result of applying ASCII encoding to | |||
char. | char. | |||
2. Append byte to byte_array. | 2. Append byte to byte_array. | |||
5. Reached the end of input_string without finding a closing DQUOTE; | 5. Reached the end of input_string without finding a closing DQUOTE; | |||
fail parsing. | fail parsing. | |||
5. IANA Considerations | 5. IANA Considerations | |||
Please add the following note to the "Hypertext Transfer Protocol | IANA has added the following note to the "Hypertext Transfer Protocol | |||
(HTTP) Field Name Registry": | (HTTP) Field Name Registry": | |||
The "Structured Type" column indicates the type of the field (per | | The "Structured Type" column indicates the type of the field (per | |||
RFC nnnn), if any, and may be "Dictionary", "List" or "Item". | | RFC 9651), if any, and may be "Dictionary", "List", or "Item". | |||
| | ||||
Note that field names beginning with characters other than ALPHA | | Note that field names beginning with characters other than ALPHA | |||
or "*" will not be able to be represented as a Structured Fields | | or "*" will not be able to be represented as a Structured Fields | |||
Token, and therefore may be incompatible with being mapped into | | Token and therefore may be incompatible with being mapped into | |||
field values that refer to it. | | field values that refer to it. | |||
Then, add a new column, "Structured Type". | A new column, "Structured Type", has been added to the registry. | |||
Then, add the indicated Structured Type for each existing registry | The indicated Structured Type for each existing registry entry listed | |||
entry listed in Table 1. | in Table 1 has also been added. | |||
+==========================================+=================+ | +==========================================+=================+ | |||
| Field Name | Structured Type | | | Field Name | Structured Type | | |||
+==========================================+=================+ | +==========================================+=================+ | |||
| Accept-CH | List | | | Accept-CH | List | | |||
+------------------------------------------+-----------------+ | +------------------------------------------+-----------------+ | |||
| Cache-Status | List | | | Cache-Status | List | | |||
+------------------------------------------+-----------------+ | +------------------------------------------+-----------------+ | |||
| CDN-Cache-Control | Dictionary | | | CDN-Cache-Control | Dictionary | | |||
+------------------------------------------+-----------------+ | +------------------------------------------+-----------------+ | |||
skipping to change at page 38, line 32 ¶ | skipping to change at line 1762 ¶ | |||
such as filtering or escaping untrusted content before displaying it. | such as filtering or escaping untrusted content before displaying it. | |||
See [PRECIS] and [UNICODE-SECURITY]. | See [PRECIS] and [UNICODE-SECURITY]. | |||
7. References | 7. References | |||
7.1. Normative References | 7.1. Normative References | |||
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | |||
Ed., "HTTP Semantics", STD 97, RFC 9110, | Ed., "HTTP Semantics", STD 97, RFC 9110, | |||
DOI 10.17487/RFC9110, June 2022, | DOI 10.17487/RFC9110, June 2022, | |||
<https://www.rfc-editor.org/rfc/rfc9110>. | <https://www.rfc-editor.org/info/rfc9110>. | |||
[RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, | [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, | |||
RFC 20, DOI 10.17487/RFC0020, October 1969, | RFC 20, DOI 10.17487/RFC0020, October 1969, | |||
<https://www.rfc-editor.org/rfc/rfc20>. | <https://www.rfc-editor.org/info/rfc20>. | |||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
Requirement Levels", BCP 14, RFC 2119, | Requirement Levels", BCP 14, RFC 2119, | |||
DOI 10.17487/RFC2119, March 1997, | DOI 10.17487/RFC2119, March 1997, | |||
<https://www.rfc-editor.org/rfc/rfc2119>. | <https://www.rfc-editor.org/info/rfc2119>. | |||
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data | [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data | |||
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, | Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, | |||
<https://www.rfc-editor.org/rfc/rfc4648>. | <https://www.rfc-editor.org/info/rfc4648>. | |||
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | |||
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | |||
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>. | May 2017, <https://www.rfc-editor.org/info/rfc8174>. | |||
[UTF8] Yergeau, F., "UTF-8, a transformation format of ISO | [UTF8] Yergeau, F., "UTF-8, a transformation format of ISO | |||
10646", STD 63, RFC 3629, November 2003, | 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November | |||
<http://www.rfc-editor.org/info/std63>. | 2003, <https://www.rfc-editor.org/info/rfc3629>. | |||
7.2. Informative References | 7.2. Informative References | |||
[HPACK] Peon, R. and H. Ruellan, "HPACK: Header Compression for | [HPACK] Peon, R. and H. Ruellan, "HPACK: Header Compression for | |||
HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, | HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, | |||
<https://www.rfc-editor.org/rfc/rfc7541>. | <https://www.rfc-editor.org/info/rfc7541>. | |||
[HTTP/2] Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113, | [HTTP/2] Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113, | |||
DOI 10.17487/RFC9113, June 2022, | DOI 10.17487/RFC9113, June 2022, | |||
<https://www.rfc-editor.org/rfc/rfc9113>. | <https://www.rfc-editor.org/info/rfc9113>. | |||
[IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", | [IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", IEEE | |||
IEEE 754-2019, DOI 10.1109/IEEESTD.2019.8766229, | Std 754-2019, DOI 10.1109/IEEESTD.2019.8766229, | |||
ISBN 978-1-5044-5924-2, July 2019, | ISBN 978-1-5044-5924-2, July 2019, | |||
<https://ieeexplore.ieee.org/document/8766229>. | <https://ieeexplore.ieee.org/document/8766229>. | |||
[PRECIS] Saint-Andre, P. and M. Blanchet, "PRECIS Framework: | [PRECIS] Saint-Andre, P. and M. Blanchet, "PRECIS Framework: | |||
Preparation, Enforcement, and Comparison of | Preparation, Enforcement, and Comparison of | |||
Internationalized Strings in Application Protocols", | Internationalized Strings in Application Protocols", | |||
RFC 8264, DOI 10.17487/RFC8264, October 2017, | RFC 8264, DOI 10.17487/RFC8264, October 2017, | |||
<https://www.rfc-editor.org/rfc/rfc8264>. | <https://www.rfc-editor.org/info/rfc8264>. | |||
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax | [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax | |||
Specifications: ABNF", STD 68, RFC 5234, | Specifications: ABNF", STD 68, RFC 5234, | |||
DOI 10.17487/RFC5234, January 2008, | DOI 10.17487/RFC5234, January 2008, | |||
<https://www.rfc-editor.org/rfc/rfc5234>. | <https://www.rfc-editor.org/info/rfc5234>. | |||
[RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, | [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, | |||
DOI 10.17487/RFC7493, March 2015, | DOI 10.17487/RFC7493, March 2015, | |||
<https://www.rfc-editor.org/rfc/rfc7493>. | <https://www.rfc-editor.org/info/rfc7493>. | |||
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data | [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data | |||
Interchange Format", STD 90, RFC 8259, | Interchange Format", STD 90, RFC 8259, | |||
DOI 10.17487/RFC8259, December 2017, | DOI 10.17487/RFC8259, December 2017, | |||
<https://www.rfc-editor.org/rfc/rfc8259>. | <https://www.rfc-editor.org/info/rfc8259>. | |||
[UNICODE-SECURITY] | [UNICODE-SECURITY] | |||
Davis, M. and M. Suignard, "Unicode Security | Davis, M. and M. Suignard, "Unicode Security | |||
Considerations", Unicode Technical Report #16, 19 | Considerations", Unicode Technical Report #36, 19 | |||
September 2014, <http://www.unicode.org/reports/tr36/>. | September 2014, | |||
<https://www.unicode.org/reports/tr36/tr36-15.html>. | ||||
Latest version available at | ||||
<https://www.unicode.org/reports/tr36/>. | ||||
Appendix A. Frequently Asked Questions | Appendix A. Frequently Asked Questions | |||
A.1. Why Not JSON? | A.1. Why Not JSON? | |||
Earlier proposals for Structured Fields were based upon JSON | Earlier proposals for Structured Fields were based upon JSON | |||
[RFC8259]. However, constraining its use to make it suitable for | [RFC8259]. However, constraining its use to make it suitable for | |||
HTTP fields required senders and recipients to implement specific | HTTP fields required senders and recipients to implement specific | |||
additional handling. | additional handling. | |||
For example, JSON has specification issues around large numbers and | For example, JSON has specification issues around large numbers and | |||
objects with duplicate members. Although advice for avoiding these | objects with duplicate members. Although advice for avoiding these | |||
issues is available (e.g., [RFC7493]), it cannot be relied upon. | issues is available (e.g., [RFC7493]), it cannot be relied upon. | |||
skipping to change at page 41, line 12 ¶ | skipping to change at line 1886 ¶ | |||
this, a common test suite is being maintained by the community at | this, a common test suite is being maintained by the community at | |||
<https://github.com/httpwg/structured-field-tests>. | <https://github.com/httpwg/structured-field-tests>. | |||
Implementers should note that Dictionaries and Parameters are order- | Implementers should note that Dictionaries and Parameters are order- | |||
preserving maps. Some fields may not convey meaning in the ordering | preserving maps. Some fields may not convey meaning in the ordering | |||
of these data types, but it should still be exposed so that it will | of these data types, but it should still be exposed so that it will | |||
be available to applications that need to use it. | be available to applications that need to use it. | |||
Likewise, implementations should note that it's important to preserve | Likewise, implementations should note that it's important to preserve | |||
the distinction between Tokens and Strings. While most programming | the distinction between Tokens and Strings. While most programming | |||
languages have native types that map to the other types well, it may | languages have built-in types that map to the other types well, it | |||
be necessary to create a wrapper "token" object or use a parameter on | may be necessary to create a wrapper "token" object or use a | |||
functions to assure that these types remain separate. | parameter on functions to assure that these types remain separate. | |||
The serialization algorithm is defined in a way that it is not | The serialization algorithm is defined in a way that it is not | |||
strictly limited to the data types defined in Section 3 in every | strictly limited to the data types defined in Section 3 in every | |||
case. For example, Decimals are designed to take broader input and | case. For example, Decimals are designed to take broader input and | |||
round to allowed values. | round to allowed values. | |||
Implementations are allowed to limit the size of different | Implementations are allowed to limit the size of different | |||
structures, subject to the minimums defined for each type. When a | structures, subject to the minimums defined for each type. When a | |||
structure exceeds an implementation limit, that structure fails | structure exceeds an implementation limit, that structure fails | |||
parsing or serialization. | parsing or serialization. | |||
Appendix C. ABNF | Appendix C. ABNF | |||
This section uses the Augmented Backus-Naur Form (ABNF) notation | This section uses the Augmented Backus-Naur Form (ABNF) notation | |||
[RFC5234] to illustrate expected syntax of Structured Fields. | [RFC5234] to illustrate the expected syntax of Structured Fields. | |||
However, it cannot be used to validate their syntax, because it does | However, it cannot be used to validate their syntax because it does | |||
not capture all requirements. | not capture all requirements. | |||
This section is non-normative. If there is disagreement between the | This section is non-normative. If there is disagreement between the | |||
parsing algorithms and ABNF, the specified algorithms take | parsing algorithms and ABNF, the specified algorithms take | |||
precedence. | precedence. | |||
sf-list = list-member *( OWS "," OWS list-member ) | sf-list = list-member *( OWS "," OWS list-member ) | |||
list-member = sf-item / inner-list | list-member = sf-item / inner-list | |||
inner-list = "(" *SP [ sf-item *( 1*SP sf-item ) *SP ] ")" | inner-list = "(" *SP [ sf-item *( 1*SP sf-item ) *SP ] ")" | |||
skipping to change at page 42, line 48 ¶ | skipping to change at line 1954 ¶ | |||
base64 = *( ALPHA / DIGIT / "+" / "/" ) *"=" | base64 = *( ALPHA / DIGIT / "+" / "/" ) *"=" | |||
unescaped = %x20-21 / %x23-24 / %x26-5B / %x5D-7E | unescaped = %x20-21 / %x23-24 / %x26-5B / %x5D-7E | |||
bs-escaped = "\" ( DQUOTE / "\" ) | bs-escaped = "\" ( DQUOTE / "\" ) | |||
pct-encoded = "%" lc-hexdig lc-hexdig | pct-encoded = "%" lc-hexdig lc-hexdig | |||
lc-hexdig = DIGIT / %x61-66 ; 0-9, a-f | lc-hexdig = DIGIT / %x61-66 ; 0-9, a-f | |||
Appendix D. Changes from RFC 8941 | Appendix D. Changes from RFC 8941 | |||
This revision of the Structured Field Values for HTTP specification | This revision of the "Structured Field Values for HTTP" specification | |||
has made the following changes: | has made the following changes: | |||
* Added the Date structured type. (Section 3.3.7) | * Added the Date Structured Type. (Section 3.3.7) | |||
* Stopped encouraging use of ABNF in definitions of new structured | ||||
fields. (Section 2) | * Stopped encouraging use of ABNF in definitions of new Structured | |||
Fields. (Section 2) | ||||
* Moved ABNF to an informative appendix. (Appendix C) | * Moved ABNF to an informative appendix. (Appendix C) | |||
* Added a "Structured Type" column to the HTTP Field Name Registry. | * Added a "Structured Type" column to the "Hypertext Transfer | |||
(Section 5) | Protocol (HTTP) Field Name Registry". (Section 5) | |||
* Refined parse failure handling. (Section 4.2) | * Refined parse failure handling. (Section 4.2) | |||
* Added the Display String structured type. (Section 3.3.8) | * Added the Display String Structured Type. (Section 3.3.8) | |||
Acknowledgements | Acknowledgements | |||
Many thanks to Matthew Kerwin for his detailed feedback and careful | Many thanks to Matthew Kerwin for his detailed feedback and careful | |||
consideration during the development of this specification. | consideration during the development of this specification. | |||
Thanks also to Ian Clelland, Roy Fielding, Anne van Kesteren, Kazuho | Thanks also to Ian Clelland, Roy Fielding, Anne van Kesteren, Kazuho | |||
Oku, Evert Pot, Julian Reschke, Martin Thomson, Mike West, and | Oku, Evert Pot, Julian Reschke, Martin Thomson, Mike West, and | |||
Jeffrey Yasskin for their contributions. | Jeffrey Yasskin for their contributions. | |||
End of changes. 58 change blocks. | ||||
185 lines changed or deleted | 173 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. |