= IPP Registry : PWG Policy = :author: Smith Kennedy :email: smith.kennedy@hp.com :revnumber: 1.1.0 :revdate: 2020-05-18 :toc: :homepage: https://www.pwg.org/ {revnumber} - {revdate} Copyright © 2020 IEEE ISTO Printer Working Group. All Rights Reserved. == Abstract == This policy document clarifies the documentation requirements and procedures for submitting registration requests to the PWG Internet Printing Protocol Workgroup (IPP WG) defined in "Internet Printing Protocol/1.1: Model & Semantics" <> to update the IANA IPP Registry <>. This policy document also defines actions necessary for deprecation and obsoletion of existing registrations in the IANA IPP Registry. This version is available in the following locations: * https://ftp.pwg.org/pub/pwg/general/process/ipp-registry-policy.txt * https://ftp.pwg.org/pub/pwg/general/process/ipp-registry-policy.pdf * https://ftp.pwg.org/pub/pwg/general/process/ipp-registry-policy-20200518.adoc :sectnums: == Overview == Section 7 of <> defines the original formal process for registering new or changed items in the IANA IPP registry. This document defines the current formal process. == Definitions == Capitalized terms, such as MUST, MUST NOT, RECOMMENDED, REQUIRED, SHOULD, SHOULD NOT, MAY, and OPTIONAL, have special meaning relating to conformance defined in "Key words for use in RFCs to Indicate Requirement Levels" <>. Addition:: A request to add one or more IPP Items to the IANA IPP Registry. Deletion:: A request to remove one or more existing IPP Items from the IANA IPP Registry. Deprecation:: A request to deprecate one or more existing IPP Items in the IANA IPP Registry, indicating that it SHOULD no longer be implemented or used. IPP Email Registration File:: A plain text document that records one or more email IPP Registration Request messages, along with the approval email message by the PWG IPP WG. IPP Item:: An IPP operation, attribute, keyword, enum, attribute group, out-of-band attribute value, syntax, or status code IPP Registration White Paper:: An Informational PWG White Paper that defines one or more IPP Registration Requests. IPP Registration Request:: A request to add, delete, modify, deprecate, or obsolete one or more IPP operations, attributes, values, groups, status codes, or attribute syntaxes. Modification:: A request to change one or more existing IPP Items in the IANA IPP Registry. Obsoletion:: A request to obsolete one or more existing IPP Items in the IANA IPP Registry, indicating that it MUST no longer be implemented or used. Standards-Track Document:: A PWG Candidate Standard or PWG Standard document <> that defines one or more IPP Registration Requests. == Registration Methods == The methods for submission and approval of IPP Registration Requests are defined below. All three methods start with the Email method. === Method of Email Registration Note === IPP registration begins with an email message to the "ipp@pwg.org" reflector containing an IPP Registration Request, with the subject line: "IPP Registration Request for : " where is one of {Addition, Change, Deletion, Deprecation, Obsoletion}. The body of the email message includes a justification for the registration and action, followed by the IANA Registration Request. After the PWG IPP WG reviews the request in a conference call or face-to-face meeting, the IPP WG takes one of the following actions: 1. Approve the request as submitted; 2. Approve the request with modifications; 3. Reject the request for a stated technical reason; 4. Direct that the request be made via an IPP Registration White Paper; or 5. Direct that the request be made via a PWG Standards-Track document. The PWG IPP WG secretary posts an email response to the PWG IPP WG mailing list stating the final disposition of the request. If the request was approved, the IPP WG Secretary creates and publishes the IPP Email Registration File containing the complete approval message with the final IPP Registration Request, for later reference in the IANA IPP Registry. === Method of IPP Registration White Paper === An IPP Registration White Paper can be approved only via IPP WG Last Call. At the successful conclusion of the IPP WG Last Call, the PWG IPP WG Secretary publishes the approved draft by setting the status on the title page to "IPP WG Approved", changing the prefix from "wd-" to "reg-", and uploading it and a PDF rendering to the "/pub/pwg/ipp/registrations" directory on the PWG FTP server. === Method of PWG Standards-Track Document === A PWG Standards-Track Document registration can be approved only with the rest of the document according to the current PWG Standards-Track Document approval process. == Registration Actions == === Actions for New or Changed Items === New or changed IPP Items can be defined as follows: * New attributes and new values for existing attributes using type2 enum or type2 keyword attribute syntax can be defined using the Registration Via Email process. * New operations and status codes with simple semantics can be defined in an IPP Registration document. * New operations, attribute syntaxes, group tags, and status codes with complex semantics can be defined only in either an IPP Registration White Paper or PWG Standards-Track Document. === Actions for Modification or Deletion of Existing Items === Existing IPP Items can be modified or deleted as follows: * The PWG IPP WG determines that specific IPP Item definitions currently in the IANA IPP Registry are defective. * The defective IPP Item definitions can be modified to correct the defects, or can be removed from the IANA IPP Registry. === Actions for Deprecation or Obsoletion of Existing Items === Existing IPP Items can be deprecated or obsoleted as follows: * The PWG IPP WG determines that specific IPP Items ought to be deprecated or obsoleted if: ** The IPP Item has demonstrated interoperability issues or side-effects that make its use problematic; or ** An alternative IPP Item has been registered that better serves the long-term goals of the PWG for the IPP Model and Semantics * Deprecations or obsoletions are approved through either a PWG Call for Objections or, at the discretion of the PWG Steering Committee, a PWG Formal Approval for the requested changes. Deprecations are equivalent to a SHOULD NOT conformance requirement for Printers. Obsoletions are equivalent to a MUST NOT conformance requirement for Printers. IPP Items that are deprecated can eventually be obsoleted. Printers can report deprecated attributes or values by returning them in the unsupported attributes group of the response and returning the 'successful-ok-ignored-or-substituted' status code. Printers can report obsoleted attributes or values by returning them in the unsupported attributes group of the response and returning the 'client-error-attributes-or-values-not-supported' status code. Deprecations and obsoletions of type1 attributes and type1 values (which include group tags and attribute syntaxes) MUST be registered in a Standards-Track Document <>. Deprecations and obsoletions for all other IPP Item types can be registered via any of the methods defined above. To deprecate or obsolete an IPP attribute, operation, or value in a PWG specification or Registration Document, the editor includes it in the IANA Considerations section, using the template defined later in this document. For deprecations, the editor MAY also provide an updated definition, specifying that it has been deprecated. For obsoletions, the editor removes the items' definitions in the sections defining other attributes, and instead adds a new top-level section "Obsolete Attributes", "Obsolete Attribute Values", "Obsolete Operations", etc. as needed, where justification for the obsoletion can be specified. Deprecations and obsoletions in a PWG IPP Specification are published in the IANA IPP Registry when that Specification has been approved by the PWG members. Deprecations and obsoletions take effect when they are published in the IANA IPP Registry. == IPP Registration White Paper == An IPP Registration White Paper is an Informational PWG White Paper that describes one or more IPP Registration Requests <>. == IPP Email Registration File == An IPP Email Registration File is a UTF-8 plain text file containing the complete approval message for the final IPP Registration Request. This file will be placed into the "/pub/pwg/ipp/registrations" directory on the PWG FTP site, to provide a durable definition for the IANA IPP Registry to reference. Other documents can reference this file in a similar fashion. The name of the file follows a "SOURCE-TOPIC[-STATUS]-DATE.txt" naming convention, where: * "SOURCE" is the originating individual or organization, in all lower case; * "TOPIC" is a unique word or short phrase hinting at the nature of the registration, using all lowercase letters or numbers, with a limited number of dashes if needed; * "DATE" is the approval date of the form "YYYYMMDD"; * "STATUS" is an optional "deprecated" or "obsolete" label to indicate attribute or attribute value state change * Each of the above is separated by a dash ("-") Approved updates to the registration SHALL be posted in a document with matching SOURCE and TOPIC, but with a new DATE specifying the new approval date. As an example, if "Acme Inc." proposed a registration of a postage stamp media size on April 1, 2012, it might be called "acme-postage-20120401.txt", and can be referenced at: https://ftp.pwg.org/pub/pwg/ipp/registrations/acme-postage-20120401.txt == IANA IPP Registration Request Templates == Below is a description of the structure and format that MUST be used for all IPP Registration Requests, whether via email, in an IPP Registration White Paper, or a PWG Standards Track Document. Deprecation and Obsoletion requests also include their corresponding rationales. Deprecated and obsoleted IPP attributes, operations, and values are shown in the registry using a second record below the one originally registering it, with either the "deprecated" or "obsolete" label appended in parenthesis to the name. For example, a deprecated Job Template attribute named "my-attribute" and an obsoleted Job Template attribute "another-attribute" would appear in the registry as: Collection Name Syntax Reference Job Template my-attribute type2 keyword [REFERENCE1] Job Template my-attribute(deprecated) type2 keyword [REFERENCE2] Job Template another-attribute type2 keyword [REFERENCE3] Job Template another-attribute(obsolete) type2 keyword [REFERENCE4] The REFERENCE1, REFERENCE2, REFERENCE3 and REFERENCE4 references provide durable links to the specification or a document containing the approving message from the PWG IPP WG mailing list (ipp@pwg.org) archive in which the deprecation occurred. ---- Attribute Registrations TEMPLATE Document Description attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Document Status attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Document Template attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Job Description attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Job Status attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Job Template attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Operation attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Printer Description attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Printer Status attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Subscription Description attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Subscription Status attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Subscription Template attributes: Reference -------------------------------------------------------- -------------- name (syntax) [REFERENCE] name (deprecated) (syntax) [REFERENCE] name (obsolete) (syntax) [REFERENCE] Attribute Keyword Value Registrations TEMPLATE Attributes (attribute syntax) Keyword Attribute Value Reference -------------------------------------------------------- -------------- name (type2 keyword) [REFERENCE] value-1 [REFERENCE] value-2 [REFERENCE] value-3(deprecated) [REFERENCE] value-4(obsolete) [REFERENCE] name-supported (1setOf type2 keyword) [REFERENCE] < all name values > [REFERENCE] Attribute Enum Value Registrations TEMPLATE Attributes (attribute syntax) Enum Value Enum Symbolic Name Reference ---------- ------------------ -------------- name (type2 enum) [REFERENCE] 3 value-3 [REFERENCE] 4 value-4 [REFERENCE] 5 (deprecated) value-5 [REFERENCE] 6 (obsolete) value-6 [REFERENCE] operations-supported (1setOf type2 enum) [STD92] 0xXXXX Operation-Name [REFERENCE] Attribute Group Tag Registrations TEMPLATE Value Attribute Group Name Reference -------- ---------------------------------------------- -------------- 0xXX new-attributes-tag [REFERENCE] Out-of-Band Attribute Value Tag Registrations TEMPLATE Value Out-of-Band Attribute Value Tag Name Reference -------- ---------------------------------------------- -------------- 0xXX new-out-of-band-attribute-value-tag-name [REFERENCE] Attribute Syntax Registrations TEMPLATE Value Attribute Syntax Tag Name Reference -------- ---------------------------------------------- -------------- 0xXX new-attribute-syntax-tag-name [REFERENCE] Operation Registrations TEMPLATE Note: Registering a new operation also requires registering a new enum for the "operations-supported" attribute <>. Operation Name Reference -------------------------------------------------------- -------------- Operation-Name [REFERENCE] Existing-Operation-Name (Extension) [REFERENCE] Status Code Registrations TEMPLATE Value Status Code Name Reference ------ --------------------------------------------- -------------- 0x0000:0x00FF - "successful" Status Code Class: 0x00XX successful-ok-but-not-that-happy [REFERENCE] 0x00XY successful-ok-but-a-bit-sleepy [REFERENCE] 0x0400:0x04FF - "client-error" Status Code Class: 0x04XX client-error-not-that-happy [REFERENCE] 0x04XY client-error-a-bit-sleepy [REFERENCE] 0x0500:0x05FF - "server-error" Status Code Class: 0x05XX server-error-not-that-happy [REFERENCE] 0x05XY server-error-a-bit-sleepy [REFERENCE] ---- == References == [bibliography] * [[[BCP14]]] S. Bradner, “Key words for use in RFCs to Indicate Requirement Levels", BCP 14 (RFC 2119 / RFC 8174), March 1997 and May 2017, https://tools.ietf.org/html/bcp14 * [[[IANA-IPP]]] IANA IPP Registry, https://www.iana.org/assignments/ipp-registrations/ * [[[PWGProcess3.0]]] D. Fullman, T. Hastings, "The Printer Working Group Definition of the Standards Development Process Version 3.0", January 2009, https://ftp.pwg.org/pub/pwg/general/pwg-process-30.pdf * [[[STD92]]] M. Sweet, I. McDonald, "Internet Printing Protocol/1.1: Model & Semantics", STD92 (RFC 8010 / RFC 8011), June 2018, https://tools.ietf.org/html/std92 * [[[WHITEPAPER]]] M. Sweet, "PWG White Paper Policy", https://ftp.pwg.org/pub/pwg/general/process/pwg-white-policy.txt