| 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. | ||||