INTERNET-DRAFT Roger deBry Utah Valley State College T. Hastings Xerox Corporation R. Herriot Xerox Corporation February 22, 2000 Internet Printing Protocol: The 'collection' attribute syntax Copyright (C) The Internet Society (2000). All Rights Reserved. Status of this Memo: This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of [RFC2026]. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress". The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed as http://www.ietf.org/shadow.html. Abstract This document specifies an OPTIONAL attribute syntax called 'collection' for use with the Internet Printing Protocol/1.0 (IPP) [RFC2565, RFC2566], IPP/1.1 [ipp-mod, ipp-pro], and subsequent versions. A 'collection' is a container holding one or more named values, which are called "member" attributes. A collection allows data to be grouped like a PostScript dictionary or a Java Map. deBry, Hastings, Herriot [page 1] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 The full set of IPP documents includes: Design Goals for an Internet Printing Protocol [RFC2567] Rationale for the Structure and Model and Protocol for the Internet Printing Protocol [RFC2568] Internet Printing Protocol/1.1: Model and Semantics (this document) Internet Printing Protocol/1.1: Encoding and Transport [IPP-PRO] Internet Printing Protocol/1.1: Implementer's Guide [IPP-IIG] Mapping between LPD and IPP Protocols [RFC2569] The "Design Goals for an Internet Printing Protocol" document takes a broad look at distributed printing functionality, and it enumerates real-life scenarios that help to clarify the features that need to be included in a printing protocol for the Internet. It identifies requirements for three types of users: end users, operators, and administrators. It calls out a subset of end user requirements that are satisfied in IPP/1.0. A few OPTIONAL operator operations have been added to IPP/1.1. The "Rationale for the Structure and Model and Protocol for the Internet Printing Protocol" document describes IPP from a high level view, defines a roadmap for the various documents that form the suite of IPP specification documents, and gives background and rationale for the IETF working group's major decisions. The "Internet Printing Protocol/1.1: Encoding and Transport" document is a formal mapping of the abstract operations and attributes defined in the model document onto HTTP/1.1 [RFC2616]. It defines the encoding rules for a new Internet MIME media type called "application/ipp". This document also defines the rules for transporting over HTTP a message body whose Content-Type is "application/ipp". This document defines a new scheme named 'ipp' for identifying IPP printers and jobs. The "Internet Printing Protocol/1.1: Implementer's Guide" document gives insight and advice to implementers of IPP clients and IPP objects. It is intended to help them understand IPP/1.1 and some of the considerations that may assist them in the design of their client and/or IPP object implementations. For example, a typical order of processing requests is given, including error checking. Motivation for some of the specification decisions is also included. The "Mapping between LPD and IPP Protocols" document gives some advice to implementers of gateways between IPP and LPD (Line Printer Daemon) implementations. deBry, Hastings, Herriot [page 2] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 Table of Contents 1 Problem Statement.................................................4 2 Solution..........................................................4 3 Definition of a Collection Type...................................5 4 Order of Member Attributes........................................6 5 New Operation Attribute...........................................6 5.1collection-syntax-recognized (boolean)...........................6 6 New Printer Attribute.............................................7 6.1collection-syntax-recognized (boolean)...........................7 7 New Out-of-band value.............................................7 7.1'none'...........................................................7 8 Unsupported Values................................................7 9 Encoding..........................................................8 10 Legacy issues.....................................................9 11 IANA Considerations..............................................10 12 Internationalization Considerations..............................10 13 Security Considerations..........................................10 14 References.......................................................10 15 Author's Addresses...............................................11 16 APPENDIX A: Example of collection usage..........................12 16.1"job-notify" Operation attribute..............................12 17 Appendix B: Full Copyright Statement.............................12 deBry, Hastings, Herriot [page 3] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 1 Problem Statement IPP supports most of the common data structures that are available in programming languages. It lacks a mechanism for grouping several values of different types. The Java language uses the Map to solve this problem and PostScript has a dictionary. 2 Solution The IPP 'collection' is a container holding one or more named values (i.e. attributes), which are called member attributes. A collection also has a type name, which identifies the expected member attributes, as does a subclass of a Java Map. A collection value is similar to a group, such as an operation group. They both consist of a set of attributes. The name of each member attribute MUST be unique within a collection, but MAY be the same as the name of a member attribute in another collection type and/or MAY be the same as the name of an attribute that is not a member of a collection. A client or Printer is said to "recognize" collections as a single attribute value if it can determine the beginning and end of a collection value and if it can distinguish attributes within the collection from attributes outside of the collection. In order to support legacy IPP implementations, a client MUST indicate that it "recognizes" collections by including the operation attribute "collection-syntax-recognized" with the value of 'true' in each request. A printer MUST indicate that it "recognizes" collections by supporting the attribute "collection-syntax-recognized" with the value of 'true'. The fact that a Printer recognizes collections does not require the printer to support collection values of attributes that are defined to have values of collections and other attribute syntaxes. For example, if an attribute is defined to have the attribute syntax: (type3 keyword | name | collection), a Printer that recognizes collections MAY support only keyword values of such an attribute. Each member attribute can have any attribute syntax type, including 'collection', and can be either single-valued or multi-valued. The length of a collection value is not limited. However, the length of each member attribute MUST NOT exceed the limit of its attribute syntax. The member attributes in a collection can be in any order. When a client sends the Printer a collection, the order that the Printer stores the value and the order returned in a response MAY be different from the order sent by the client. If a collection contains two or more member attributes with the same attribute name, the collection is not well formed. The receiver of such deBry, Hastings, Herriot [page 4] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 a collection MAY either treat the collection as a bad value or ignore all but one of the identically named member attributes. 3 Definition of a Collection Type When a specification defines an attribute "xxx" whose syntax type is 'collection' or '1setOf collection', it must define following aspects of the attribute. 1. The name of the attribute "xxx" 2. Its syntax type, which includes a collection syntax-type 3. Its default-value is specified by a)the attribute's definition b)an attribute, such as "xxx-default", which may have a collection value 4. Its supported values, which may be specified by one of: a)the attribute's definition b)a boolean attribute, such as "xxx-supported", which is true if the attribute is supported. The supported values are specified by the attribute's definition which specifies the supported values for each member of a collection or the "yyy-supported" that specifies the value supported for the "yyy" member attribute. c)an attribute, such as "xxx-supported", which contains the explicit collection values and other values supported. 5. the name of the collection type, whose characters are the same as those for a keyword. 6. the following information about each "yyy" member attribute: a)its name, which is a keyword like all attributes. It must be unique within the collection type. b)its syntax type, which may be any IPP syntax type, including 'collection'. If the attribute syntax type starts with "1setOf", the member attribute is multi-valued. c)its supported values, either enumerated explicitly or specified by the values of a referenced attribute which may be specified by either: @ the attribute's definition deBry, Hastings, Herriot [page 5] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 @ an attribute, such as "yyy-supported", which contains the explicit values supported. The "yyy-supported" attribute is a Printer attribute and not in a collection. For example, if a collection contains the "media" attribute and its supported values are specified by the "media-supported" attribute, the "media-supported" attribute is the same Printer attribute that the "media" attribute uses. d)whether "yyy" MUST be or MAY be supplied by a client in a request. e)the default value of "yyy" if it is OPTIONAL for a client to supply the "yyy" attribute in a request. The default value is specified by either: @ the attribute's definition @ an attribute, such as "yyy-default", which may have a collection value f)whether "yyy" MUST be or MAY be supported by the printer. g)the semantics of "yyy". 4 Order of Member Attributes The member attributes of a collection value are unordered. A Printer and a client MUST accept member attributes of a collection in any order. Therefore, a Printer and a client MAY send the member attributes of a collection value in any order. A Printer NEED NOT return member attributes to a client in the order received from a client. 5 New Operation Attribute 5.1 collection-syntax-recognized (boolean) A client MUST include this operation attribute with a value of 'true' in each request if it recognizes the collection-syntax. If a client does not include this operation attribute or its value is not 'true' in a request, then a Printer MUST NOT return a collection in a response. ISSUE 01: If a Printer creates a notification subscription [ipp-ntfy] with a request that does not include "collection-syntax-recognized" (boolean) operation attribute with a value of 'true', then a Printer MUST NOT send a collection in a Notification to a Notification Recipient? deBry, Hastings, Herriot [page 6] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 6 New Printer Attribute 6.1 collection-syntax-recognized (boolean) A Printer MUST support this attribute with a value of 'true' if it recognizes the collection-syntax. If a Printer does not support this attribute or its value is not 'true', then a client MUST NOT send a collection in a request. 7 New Out-of-band value 7.1 'none' 'none' The specified Job Template attribute in the request MUST NOT be applied to the job. Specifically, this value overrides the Printer's "xxx-default" attribute value for the Job Template attribute, if one exists. This "out-of-band" value allows a client to specify "turn-off" a feature that is specified by an attribute whose value is a collection. Because a client specifies a value, the Printer uses the client-specified value and not the Printer's default value. If a Printer supports the use of the 'collection' attribute syntax for an attribute, a Printer MUST support the use of the "out-of-band" value 'none'. A Printer MUST support the "out-of-band" value 'none' as the value for an attribute "xxx" if: @ the definition of the attribute specifies 'none' MUST be supported AND @ the definition of the attribute specifies 'none' MAY be supported and it is a value of the attribute "xxx-supported". 8 Unsupported Values The rules for returning an unsupported collection attribute are an extension to the current rules. If a collection contains unrecognized, unsupported member attributes and/or conflicting values, the attribute returned in the Unsupported Group is a collection containing the unrecognized, unsupported member attributes, and/or conflicting values. The unrecognized member attributes have an out-of-band value of 'unsupported' (see the beginning of [ipp-mod] section 4.1). The unsupported member attributes and conflicting values have their unsupported values. deBry, Hastings, Herriot [page 7] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 9 Encoding This section defines the encoding of a collection syntax type. A collection is encoded by using three new tags: Tag name Tag Meaning value beginCollection 0x34 Begin the named collection. endCollection 0x37 End the named collection. A collection value is encoded as a sequence of attribute values preceded by a beginCollection value and followed by an endCollection value. The value field of a beginCollection and an endCollection both contain the name of the collection type, which is a string of ASCII characters. These values allow a receiver to optionally match an endCollection value with a beginCollection. A 1setOf collection is encoded using the rules for 1setOf and collection. The name field for the endCollection must be empty. The following example is written in the style of the IPP/1.1 "Encoding and Transport" document [ipp-pro]. The following example is for a job-notify attribute containing a set of 2 collections. Octets Symbolic Protocol comments Value field 0x34 beginCollecti value-tag Beginning of the on collection 0x000a name-length job-notify job-notify Name 0x000f Value-length job-notify-coll job-notify- Value Collection type coll 0x45 uri type value-tag "notify-recipients" attribute 0x0010 name-length notify-recipient notify- Name recipient 0x0013 value-length ipp- Value notify:port=700 0x44 keyword type value-tag "notify-event-groups" attribute 0x000d name-length notify-events Name 0x0d value-length job-completed Value 0x44 keyword type value-tag 2nd "notify-event- groups" attribute 0x0000 name-length 0 length means next multiple value 0x0011 value-length deBry, Hastings, Herriot [page 8] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 Octets Symbolic Protocol comments Value field job-state-changed job- Value completion 0x37 endCollection value-tag 0x0000 name-length 0x000f value-length job-notify-coll Value Matches value of beginCollection 0x34 beginCollecti value-tag Separator between on collection values 0x0000 name-length 0x000f value-length job-notify-coll Value Matches value of beginCollection 0x45 uri type value-tag "notify-recipients" attribute 0x0010 name-length notify-recipient Name 0x0014 value-length mailto:smith@foo.c Value om 0x44 keyword type value-tag "notify-event-groups" attribute 0x000d name-length notify-events Name 0x0d value-length job-completed Value 0x37 endCollection value-tag End of last collection 0x0000 name-length 0x000f value-length job-notify-coll Value Matches value of beginCollection 10 Legacy issues If a client recognizes collections in responses, it MUST include the "collection-syntax-recognized" operation attribute with the value of 'true' in each operation whether or not the request contains a collection. If a Printer recognizes collections in requests, it MUST support the "collection-syntax-recognized" Printer Description attribute with the value of 'true'. A client that supports collections MUST NOT send collections in a request to a Printer that does not recognize collections. A Printer that supports collections MUST NOT return collections in a response to a client that does not recognize collections. deBry, Hastings, Herriot [page 9] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 Although a client or Printer that doesn't recognize collections will skip over the beginCollection and endCollection tags as unrecognized syntax types, the client or Printer will mistakenly assume that the member attributes are outside of the unrecognized collection. Thus it is important that clients and Printers that don't recognize collections not receive them. 11 IANA Considerations This attribute syntax will be registered with IANA after the WG approves its specification according to the procedures for extension of the IPP/1.1 Model and Semantics [ipp-mod]. 12 Internationalization Considerations This attribute syntax by itself has no impact on internationalization. However, the member attributes that are subsequently defined for use in a collection may have internationalization considerations, as may any attribute, according to [ipp-mod]. 13 Security Considerations This attribute syntax causes no more security concerns than any other attribute syntax. It is only the attributes that are subsequently defined to use this or any other attribute syntax that may have security concerns, depending on the semantics of the attribute, according to [ipp-mod]. 14 References [ipp-mod] Isaacson, S., deBry, R., Hastings, T., Herriot, R., Powell, P., "Internet Printing Protocol/1.1: Model and Semantics" draft-ietf- ipp-model-v11-04.txt, June 23, 1999. [ipp-ntfy] Isaacson, S., Martin, J., deBry, R., Hastings, T., Shepherd, M., Bergman, R. " Internet Printing Protocol/1.0 & 1.1: IPP Event Notification Specification" draft-ietf-ipp-not-spec-02.txt, work in progress, February 2, 2000. [ipp-pro] Herriot, R., Butler, S., Moore, P., Turner, R., "Internet Printing Protocol/1.1: Encoding and Transport", draft-ietf-ipp-protocol-v11- 03.txt, June 23, 1999. [RFC2565] Herriot, R., Butler, S., Moore, P., Tuner, R., "Internet Printing Protocol/1.0: Encoding and Transport", RFC 2565, April 1999. deBry, Hastings, Herriot [page 10] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 [RFC2566] R. deBry, T. Hastings, R. Herriot, S. Isaacson, P. Powell, "Internet Printing Protocol/1.0: Model and Semantics", RFC 2566, April 1999. [RFC2567] Wright, D., "Design Goals for an Internet Printing Protocol", RFC 2567, April 1999. [RFC2568] Zilles, S., "Rationale for the Structure and Model and Protocol for the Internet Printing Protocol", RFC 2568, April 1999. [RFC2569] Herriot, R., Hastings, T., Jacobs, N., Martin, J., "Mapping between LPD and IPP Protocols", RFC 2569, April 1999. [RFC2616] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, "Hypertext Transfer Protocol - HTTP/1.1", RFC 2616, June 1999. 15 Author's Addresses Tom Hastings Xerox Corporation 737 Hawaii St. ESAE 231 El Segundo, CA 90245 Phone: 310-333-6413 Fax: 310-333-5514 e-mail: hastings@cp10.es.xerox.com Robert Herriot Xerox Corp. 3400 Hill View Ave, Building 1 Palo Alto, CA 94304 Phone: 650-813-7696 Fax: 650-813-6860 e-mail: robert.herriot@pahv.xerox.com Roger deBry Utah Valley State College Orem, UT 84058 Phone: (801) 222-8000 EMail: debryro@uvsc.edu deBry, Hastings, Herriot [page 11] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 16 APPENDIX A: Example of collection usage This section describes one collection Job Template example. 16.1"job-notify" Operation attribute The following example illustrates the definition of a collection attribute for the "job-notify" operation attribute (see [ipp-ntfy]). Each column of the table corresponds to information that is required for member attributes. Only the semantics have been omitted. Member name Member type Supported- Client Printer values supplied/ support default notify- uri notify- MUST MUST recipient recipient- schemes- supported notify-events 1setOf type2 notify-events- notify-events- MUST keyword supported default subscriber- octetString(63) octetString> notify- charset charset- attributes- MAY attributes- supported charset in charset operation group notify- naturalLanguage generated- attributes- MAY attributes- natural- natural- natural- language- language in language supported operation group Note: for the "client supplied/default" column, the default is specified if it is OPTIONAL for the client to supply the member attribute in a request. 17 Appendix B: Full Copyright Statement Copyright (C) The Internet Society (1998,1999). All Rights Reserved This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice deBry, Hastings, Herriot [page 12] [Expires: August 22, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntaxFebruary 22, 2000 or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. deBry, Hastings, Herriot [page 13] [Expires: August 22, 2000]