├── .github ├── CONTRIBUTING.md └── ISSUE_TEMPLATE │ ├── modification-request.md │ └── registration-request.md └── README.md /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | ## Code of Conduct 2 | 3 | The [IETF Guidelines for Conduct](https://tools.ietf.org/html/rfc7154) apply 4 | to this repository. 5 | 6 | 7 | ## NOTE WELL 8 | 9 | Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor 10 | for publication as all or part of an IETF Internet-Draft or RFC and any 11 | statement made within the context of an IETF activity is considered an "IETF 12 | Contribution". Such statements include oral statements in IETF sessions, as 13 | well as written and electronic communications made at any time or place, which 14 | are addressed to: 15 | 16 | * The IETF plenary session 17 | * The IESG, or any member thereof on behalf of the IESG 18 | * Any IETF mailing list, including the IETF list itself, any working group 19 | or design team list, or any other list functioning under IETF auspices 20 | * Any IETF working group or portion thereof 21 | * Any Birds of a Feather (BOF) session 22 | * The IAB or any member thereof on behalf of the IAB 23 | * The RFC Editor or the Internet-Drafts function 24 | * All IETF Contributions are subject to the rules of 25 | [RFC 5378](https://tools.ietf.org/html/rfc5378) and 26 | [RFC 3979](https://tools.ietf.org/html/rfc3979) 27 | (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). 28 | 29 | Statements made outside of an IETF session, mailing list or other function, 30 | that are clearly not intended to be input to an IETF activity, group or 31 | function, are not IETF Contributions in the context of this notice. 32 | 33 | Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC 34 | 3979](https://tools.ietf.org/html/rfc3979) for details. 35 | 36 | A participant in any IETF activity is deemed to accept all IETF rules of 37 | process, as documented in Best Current Practices RFCs and IESG Statements. 38 | 39 | A participant in any IETF activity acknowledges that written, audio and video 40 | records of meetings may be made and may be available to the public. 41 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/modification-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Modification Request 3 | about: For requests to modify a registered HTTP Field Name 4 | title: '' 5 | labels: modification 6 | assignees: '' 7 | 8 | --- 9 | 10 | * Field name: 11 | * Status: 12 | * Specification document(s): 13 | * Comments: 14 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/registration-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Registration Request 3 | about: For requests to register a new HTTP Field Name 4 | title: '' 5 | labels: new registration 6 | assignees: '' 7 | 8 | --- 9 | 10 | Please confirm that: 11 | 12 | * [ ] You have read and understood the [requirements for registration](https://www.ietf.org/archive/id/draft-ietf-httpbis-semantics-19.html#name-field-extensibility). 13 | * [ ] You have checked [the registry](https://www.iana.org/assignments/http-fields/) and found no current value that meets your needs. 14 | * [ ] Your specification reference URL is stable; ideally, managed by a widely-recognised standards development organisation (e.g., published as an RFC). Otherwise, please give additional information below. 15 | 16 | If so, please provide the details of your request below. 17 | 18 | * Field name: 19 | * Status: 20 | * Structured Type: 21 | * Specification document(s): 22 | * Comments: 23 | 24 | Any additional information (this will not be included in the registry)? 25 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # HTTP Field Name Registration Requests 2 | 3 | This repository's issues list manages requests to add and change entries in the [HTTP Field Name Registry](https://www.iana.org/assignments/http-fields/). Please note our [contribution terms](.github/CONTRIBUTING.md). 4 | 5 | Your [Experts](https://tools.ietf.org/html/rfc8126#section-4.6) are currently [@mnot](https://github.com/royfielding) and [@royfielding](https://github.com/royfielding). 6 | 7 | See [the HTTP specification](https://www.ietf.org/archive/id/draft-ietf-httpbis-semantics-19.html#name-field-extensibility) for more information about the registration process and requirements for registration. 8 | 9 | ## When to Register 10 | 11 | Registration is intended to: 12 | 13 | 1. Avoid conflicting uses of a field name 14 | 2. Allow the documentation associated with a field to be discovered 15 | 3. Offer guidance regarding a field's definition during the process of registration 16 | 17 | It's not necessary to register fields that are only used in controlled deployments -- in particular, applications that don't need to interoperate with other implementations. This includes internal and private uses of HTTP, and HTTP APIs whose clients are specific to that service. However, these fields can still be registered (typically, as _provisional_) if you wish. 18 | 19 | Generally, a registration request should be made when your document is mature enough for wide review. If your reference is an Internet-Draft, that means when it's adopted by a stream (e.g., the IETF stream, the Independent stream), not beforehand. If your reference is in another standards body, a request can be made before the document is finalized. 20 | 21 | If your reference is from an Open Source project, community or commercial group, a request can be made once your document becomes public, but anticipatory requests are discouraged, and may be refused or delayed. 22 | 23 | ## Creating a Registration Request 24 | 25 | A registration request consists of the following template: 26 | 27 | * **Field name**: The requested field name. It must conform to the field-name syntax defined in [Section 5.1 of the HTTP specification](https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#fields.names), and should be restricted to just letters, digits, and hyphen (`-`) characters, with the first character being a letter. 28 | * **Status**: "permanent", "provisional", "deprecated", or "obsoleted" 29 | * **Structured Type**: If your field is a Structured Field, one of "Item", "Dictionary", or "List". See [RFC 9651](https://httpwg.org/specs/rfc9651.html) 30 | * **Specification document(s)**: Reference to the document that specifies the field, preferably including a URI that can be used to retrieve a copy of the document. Optional but encouraged for provisional registrations. An indication of the relevant section(s) can also be included, but is not required. 31 | * **Comments**: Additional information, such as about reserved entries (optional). 32 | 33 | ### Choosing Your Field Name 34 | 35 | [The HTTP specification](https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#considerations.for.new.field.names) advises authors of specifications defining new fields to choose a short but descriptive field name. Short names avoid needless data transmission; descriptive names avoid confusion and "squatting" on names that might have broader uses. 36 | 37 | To that end, limited-use fields (such as a header confined to a single application or use case) are encouraged to use a name that includes that use (or an abbreviation) as a prefix; for example, if the Foo Application needs a description field, it might use `Foo-Desc`; `Description` is too generic, and `Foo-Description-Field` is needlessly long. 38 | 39 | While the field-name syntax is defined to allow any token character, in practice some implementations place limits on the characters they accept in field-names. To be interoperable, new field names should constrain themselves to alphanumeric characters, `-`, and `.`, and should begin with a letter. For example, the underscore (`_`) character can be problematic when passed through non-HTTP gateway interfaces. 40 | 41 | Field names ought not be prefixed with `X-`; see [BCP178](https://www.rfc-editor.org/rfc/rfc6648.html) for further information. 42 | 43 | Other prefixes are sometimes used in HTTP field names; for example, `Accept-` is used in many content negotiation headers, and `Content-` is used as explained in [Section 6.4 of HTTP](https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#content). These prefixes are only an aid to recognizing the purpose of a field, and do not trigger automatic processing. 44 | 45 | ### Choosing the Right Status 46 | 47 | Fields defined by standards-defined specifications will have a status of "permanent"; most other fields will have a status of "provisional." See [the HTTP specification](https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#fields.registry) for details. Note that we use [this list](https://www.iana.org/assignments/iesg-recognized-organizations/iesg-recognized-organizations.xhtml#organizations) to determine what is a recognised standards organisation. 48 | 49 | As per [IANA guidelines](https://www.rfc-editor.org/rfc/rfc8126.html#section-9.6), field names that are no longer in use should be marked as "obsoleted", and those whose use is not recommended should have a status of "deprecated". 50 | 51 | ### Suitable Specification Documents 52 | 53 | Specification documents are required for permanent registration, and encouraged for provisional registrations. They need to be publicly available and reasonably stable. 54 | 55 | ### Defining Field Semantics and Other Considerations 56 | 57 | A checklist of important [considerations for new fields](https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#considerations.for.new.fields) is available in the HTTP specification. 58 | 59 | New fields are strongly encouraged to be [Structured Fields](https://httpwg.org/specs/rfc9651.html). 60 | 61 | ## Submitting Your Request 62 | 63 | The request can be made by: 64 | 65 | * [Filing an issue](https://github.com/protocol-registries/http-fields/issues/new/choose) (preferred), or 66 | * Sending e-mail to [the mailing list](ietf-http-wg@w3.org). 67 | 68 | Once approved, your request will be incorporated into the IANA registry, whereupon it will be officially registered. 69 | --------------------------------------------------------------------------------