INTERNET-DRAFT Roger deBry Utah Valley State College T. Hastings Xerox Corporation R. Herriot Xerox Corporation K. Ocke Xerox Corporation P. Zehler Xerox Corporation March 31, 2000 Internet Printing Protocol (IPP): 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. This document also specifies the conformance requirements for a definition document that defines a collection attribute. The 'none' out-of-band attribute value is also defined for use with the collection. deBry, Hastings, Herriot, Ocke, Zehler [page 1] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 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, Ocke, Zehler [page 2] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 Table of Contents 1 Problem Statement.................................................4 2 Solution..........................................................4 3 Definition of a Collection Attribute..............................5 3.1 Member Attribute Naming Rules..................................5 3.2 Remaining rules for a collection attribute definition..........6 3.3 Nested Collections.............................................8 3.4 Collection Attributes as Operation Attributes..................8 3.5 Collections as Job Template Attributes.........................8 3.6 Collections and Get-Printer-Attributes and Get-Job-Attributes operations.........................................................10 3.7 Client submission of collection attributes and collection attribute defaulting...............................................10 4 New Out-of-band attribute value..................................11 4.1 'none'........................................................11 4.1.1Encoding of the 'none' out-of-band attribute value..........12 5 Unsupported Values...............................................12 6 Example definition of a collection attribute....................12 6.1 media-col (collection)........................................12 6.1.1media-color (type3 keyword | name(MAX)......................13 6.1.2media-size (collection).....................................13 6.1.3media (type3 keyword | name)................................14 6.2 media-col-default (collection)................................14 6.3 media-col-ready (1setOf collection)...........................14 6.4 media-col-supported (1setOf type2 keyword)....................14 7 Encoding.........................................................15 7.1 Additional tags defined for representing a collection attribute value..............................................................15 7.2 Example encoding: "media-col" (1setOf collection).............16 8 Legacy issues....................................................21 9 IANA Considerations..............................................22 10 Internationalization Considerations..............................22 11 Security Considerations..........................................22 12 References.......................................................22 13 Author's Addresses...............................................23 14 Appendix A: Full Copyright Statement.............................24 Table of Tables Table 1 - "media-col" member attributes..............................13 Table 2 - "media-size" collection member attributes..................13 Table 3 - Tags defined for encoding the 'collection' attribute syntax15 Table 4 - Example Encoding of 1setOf collection with nested collection16 deBry, Hastings, Herriot, Ocke, Zehler [page 3] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 1 Problem Statement The IPP Model and Semantics [ipp-mod] supports most of the common data structures that are available in programming languages. It lacks a mechanism for grouping several attributes of different types. The Java language uses the Map to solve this problem and PostScript has a dictionary. The new mechanism for grouping attributes together must allow for optional members and subsequent extension of the collection. The mechanism must be encoded in a manner consistent with existing 1.0 and 1.1 parsing rules (see [ipp-pro]). Current 1.0 and 1.1 parsers that don't support collections will not confuse collections they receive with attributes that they do support. 2 Solution The new mechanism is a new IPP attribute syntax called a 'collection'. As such each collection value is a value of an attribute whose attribute syntax type is defined to be a 'collection'. Such an attribute is called a collection attribute. The name of the collection attribute serves to identify the collection value in an operation request or response, as with any attribute value. The 'collection' attribute syntax is a container holding one or more named values (i.e., attributes), which are called member attributes. Each collection attribute definition document lists the mandatory and optional member attributes of each collection value. A collection value is similar to an IPP attribute group in a request or a response, such as the operation attributes group. They both consist of a set of attributes. As with any attribute syntax, the collection attribute definition document specifies whether the attribute is single-value (collection) or multi-valued (1setOf collection). The name of each member attribute MUST be unique for a collection attribute, but MAY be the same as the name of a member attribute in another collection attribute and/or MAY be the same as the name of an attribute that is not a member of a collection. The rules for naming member attributes are given in section 3.1. 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 MAY be in any order in a request or response. When a client sends a collection attribute to the Printer, deBry, Hastings, Herriot, Ocke, Zehler [page 4] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 the order that the Printer stores the member attributes of the collection value and the order returned in a response MAY be different from the order sent by the client. A collection value MUST NOT contains two or more member attributes with the same attribute name. Such a collection is mal-formed. Clients MUST NOT submit such malformed requests and Printers MUST NOT return such malformed responses. If such a malformed request is submitted to a Printer, the Printer MUST reject the request with the 'client-error-bad- request' status code (see section 13.1.4.1) ISSUE 01: In attribute groups [ipp-mod] allows a Printer either (1) to reject a request with duplicate named attributes OR (2) to choose exactly one of the attributes as the one to be used. Should we REQUIRE the Printer to reject duplicate named attributes in a collection value as stated above or allow the Printer to choose one member attribute as a second alternative as we do with attribute groups? 3 Definition of a Collection Attribute This section describes the requirements for any collection attribute definition. 3.1 Member Attribute Naming Rules Each collection attribute MUST have a unique name within the scope in which the collection attribute occurs. If the collection attribute occurs as a member of a request or response attribute group, it MUST be unique within that group, same as for any other attribute. If a collection attribute occurs as a member attribute of another collection, the collection attribute MUST have a unique name within that collection value, same as for any other attribute. Each member attribute in a collection value MUST have unique name within that collection value. Member attribute names MAY be reused between different collection attributes. An example is the "media" attribute which MAY be used as a job template attribute (see [ipp-mod]) and in a collection (see section 6.1 for an example). All attribute names that are reused MUST have an identical syntax. All attribute names that are reused MUST have a similar semantics. The semantic difference MUST be limited to boundary conditions and constraints placed on the reused attributes. All attributes that are not reused from elsewhere in the IPP model MUST have a globally unique name. Assume that it is desirable to extend IPP by adding a Job Template attribute that allows the client to select the media by its properties, e.g., weight, color, size, etc., instead of by name as the "media (type3 keyword | name) Job Template attribute in IPP/1.1 (see [ipp-mod]). The first rule is that the existing attribute MUST NOT be extended by adding the 'collection' attribute syntax to the existing "media" attribute. That would cause too many interoperability problems and complicates the deBry, Hastings, Herriot, Ocke, Zehler [page 5] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 validation and defaulting rules as well. Instead, a new attribute will be defined with a suffix of "-col" (for collection), e.g., "media-col" (collection). For a second example, suppose it is desirable to extend IPP by allowing the client to select the media for the job start sheet. Again, this would not be done by adding the 'collection' attribute syntax to the existing "job-sheets" (type2 keyword | name) Job Template attribute. Instead, a new "job-sheet-col" (collection) Job Template attribute MUST be introduced. The member of the "job-sheet-col" collection might be: "job-sheet-type" (type3 keyword | name) "media" (type3 keyword | name) if any of the "media-supported" (1setOf (type3 keyword | name)) Printer attribute values could be specified for job sheets. The reason that the "job-sheet-type" member attribute isn't named simply, "job-sheet", is because its values only indicate the type, and don't imply any media, while the "job-sheets" (type2 keyword | name) Job Template attribute do imply a media. This example illustrates when a member attribute can be the same as another attribute (in this case a Job Template attribute) and when the member attribute MUST have a different name. If the definers of the "job-sheet-col" (collection) attribute intended that the System Administrator be allowed to have a different set of media values for job sheets than documents, then the definition document for the "job-sheet-col" collection attribute would have the following member attributes instead: "job-sheet-type" (type3 keyword | name) "job-sheet-media" (type3 keyword | name) Then the supported values would be included in a separate "job-sheet- media-supported" (1setOf (type3 keyword | name)) Printer attribute. 3.2 Remaining rules for a collection attribute definition When a specification document defines an "xxx" collection attribute, i.e., an attribute whose attribute syntax type is 'collection' or '1setOf collection'; the definition document MUST include the following aspects of the attribute semantics. Suppose the "xxx" collection attribute contains an "aaa" member attribute. A simplified example of a collection specification is given in section 6 that conforms to these rules. 1. The name of the collection attribute MUST be specified (e.g. "xxx"). 2. The collection attribute syntax MUST be of type 'collection' or '1setOf collection'. 3. The context of the collection attribute MUST be specified, i.e., whether the attribute is an operation attribute, a Job Template attribute, a Job Description attribute, a Printer Description deBry, Hastings, Herriot, Ocke, Zehler [page 6] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 attribute, a member attribute of a particular collection attribute, etc. 4. The member attributes MUST be defined. For each member attribute the definition document MUST provide the following information: a)The member attribute's name (e.g., "aaa") MUST either (1) reuse the attribute name of another attribute if the member attribute shares the syntax and semantics with the other attribute or (2) be unique across the entire IPP attribute name space b)Whether the member attribute is REQUIRED or OPTIONAL for the Printer to support c)Whether the member attribute is REQUIRED or OPTIONAL for the client to supply in a request d)The member attribute's syntax type, which can be any attribute syntax, including '1setOf X', 'collection', and '1setOf collection'. If this attribute name is the same as another attribute (case of option a-1 above), it MUST have the same attribute syntax, including cardinality (whether or not 1setOf). e)The semantics of the "aaa" member attribute. The semantic definition MUST include a description of any constraint or boundary conditions the member attribute places on the associated attribute, especially if the attribute is the same as another attribute used in a different context (case of option a- 1 above) f)the supported values for the "aaa" member attribute, either enumerated explicitly or specified by the values of a referenced attribute which may be specified by either: @ the attribute's definition @ a Printer attribute, such as "aaa-supported", which contains the explicit values supported. The "aaa-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. g)the default value of "aaa" member attribute if it is OPTIONAL for a client to supply the "aaa" member attribute in a request. The default value is specified by either: @ the attribute's definition @ a Printer attribute, such as "aaa-default", which may have a collection value deBry, Hastings, Herriot, Ocke, Zehler [page 7] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 @ or an implementation defined algorithm that takes into account the values of the other member attributes of the collection value and/or an "xxx-default" (collection) Printer attribute which specifies the default for the entire collection attribute h)Depending on the collection attributes context, it MUST follow the additional rules specified below for the various contexts. 3.3 Nested Collections A member attribute may have a syntax type of 'collection' or '1setOf collection', in which case it is called a nested collection attribute. The rules for a nested collection attribute are the same as for a collection attribute as specified in section 3.2. The following example assumes a "yyy" collection attribute is a member attribute of the preceding "xxx" collection attribute. The "yyy" collection attribute contains "bbb" member attribute. Therefore, in the rules in section 3.2, substitute "yyy" for "xxx" and "bbb" for "aaa". 3.4 Collection Attributes as Operation Attributes The definition documents that define a collection attribute for use as an operation attribute MUST follow these additional rules: a)Define in which operation requests the collection attribute is intended to be used. b)Define in which operation responses the collection attribute is intended to be used. 3.5 Collections as Job Template Attributes The definition documents for collection attributes that are specified to be Job Template attributes (see [ipp-mod] section 4.2) MUST have associated printer attributes with suffixes of "-supported" and "- default" (or indicate that there is no "-default"), just as for any Job Template attribute. Certain Job Template collection attributes also have an associated Printer attribute with "-ready" (for example, see the "media-ready" attribute in [ipp-mod]). Furthermore, member attributes of Job Template attributes are addressed using the same suffix convention. See also section 3.6 on the interaction of collections and the Get- Printer-Attributes and Get-Jobs-Attributes operations. For the following rules assume the "xxx" (collection) example from section 3.2 is a Job Template attribute. 1)There MUST be two associated printer attributes. The attributes are "xxx-supported" and "xxx-default" deBry, Hastings, Herriot, Ocke, Zehler [page 8] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 2)The "xxx-default" is a collection attribute with a syntax identical to the "xxx" specification in section 3.2 . @ Each member attribute has the same name as in the "xxx" definition. @ A Get-Printer-Attributes operation MUST return the "xxx-default" (collection) Printer attribute and all the member attributes. Any default values that have been set MUST be returned. Any default values that have not been set MUST return the member attribute with the 'no-value' out-of-band attribute value (see [ipp-mod] section 4.1). 3.If the definition of the collection attribute does not mention an "xxx-ready" attribute then it is assumed that one is not defined, though implementer's are free to support an "xxx-ready" as an extension. 4.The collection attribute definition document MUST define an "xxx- supported" attribute with either a syntax of '1setOf type2 keyword' or '1setOf collection': @ If the definition uses the '1setOf type2 keyword' attribute syntax, it MUST be the attribute keyword names of all of the member attributes that the Printer implementation supports in a Job Creation operation. Furthermore, the definition MUST include corresponding definitions of each of the "aaa-supported" attributes that correspond to each "aaa" member attribute. Then a client can determine the supported values of each member attribute in the Job Template collection attribute. See examle in section 6.4. @ If the definition uses the '1setOf collection' attribute syntax, then the values are the supported instances of the "xxx" (collection) attribute that a client can supply in a Job Creation operation. It is expected that this second approach will be used for small collections whether the number of possible collection values is small. For example, a "media-size" (collection) member attribute in which the member attributes are "x-dimension" (integer) and "y-dimension" (integer). The pairs of integers are just like keywords as far as the client localization is concerned, except that if the client doesn't recognize a size pair of numbers, it can display the numbers. See example in section 6.1.2. a) The keywords returned lists all the contained member attribute names. This example would return the "aaa" keyword. b) The list is recursive and lists all the member attributes of the contained collections. In section 3.3 the printer would return "aaa" and "bbb" for collection "xxx" c) The encoding convention allows the reconstruction of the collection structure. This rule will allow the client to reconstruct the deBry, Hastings, Herriot, Ocke, Zehler [page 9] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 collections. The client would know that "aaa" is a member of collection "xxx". It can also be derived that collection "bbb" is a member of collection "yyy". See section 7 for more information on encoding. d) To obtain the supported values for any member attribute a client performs a Get-Printer-Attributes operation explicitly requesting the member attribute name with the suffix "supported". If a member attribute is itself a collection rule 4 above applies to the member attribute. 3.6 Collections and Get-Printer-Attributes and Get-Job-Attributes operations The behavior of collection attributes for "job-templates", "job- description", and "printer-description" attribute group names is similar to any other attribute. Simple attributes return the attribute and its value. For a collection attribute, the collection and its entire set of member attributes and their values are returned. This includes any collection values containing collection attributes, its member attributes and their values. The same logic applies for the "-default" and "-ready" printer attribute associated with the "job-template" attribute group. The semantics for "-supported" is different for a collection (see section 3.2). Here the focus is on the member attributes that the collection supports. This solution allows for extension of collections and allowing the member attributes of a collection to vary (i.e., mandatory and optional member attributes). Once a client determines what member attributes are supported in a collection a subsequent request can be constructed to determine the supported values for the member attributes. Another advantage of that the behavior of the "-supported" printer collection attribute is limiting the amount of data that is returned on general queries. A Get-Printer-Attributes operation that returns all the attributes of a printer will not have to return what may turn out to be extensive lists of "-supported" attribute values. An example might be "media-col" that could be a representation for media using a collection that goes beyond the information currently provided by the job-template attribute "media". The "media-col" could now be used to represent a job's media, insert sheets and inserted tab sheets. An IPP Printer implementation would return the member attributes for each of the "-supported" collections. 3.7 Client submission of collection attributes and collection attribute defaulting When a client supplies a partially specified collection attribute, the Printer supplies the missing member attributes in an implementation- dependent manner (see section 3.2 item 4g) above. Therefore, a client SHOULD query the Printer's "xxx-default" (collection) attribute, display deBry, Hastings, Herriot, Ocke, Zehler [page 10] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 all of the member attributes that the client allows the user to change, allow the user to make any changes, and then submit the entire collection to the Printer. Then the variability in defaulting between different implementations will not cause the user to get unexpected results. 4 New Out-of-band attribute value This section defines out-of-band values (see the beginning of [ipp-mod] section 4.1) for use with attributes defined in this and other documents. As with all out-of-band values, a client MUST NOT supply and a Printer MUST NOT support an out-of-band attribute value in an operation request and/or response unless the definition document explicitly allows or requires such usage. As with all out-of-band values, the document that defines its usage MUST indicate with which operation requests and/or responses and with which attributes or attribute syntaxes the out-of-band value is allowed or required. 4.1 'none' 'none' The feature controlled by the Job Template attribute with the 'none' attribute value MUST NOT be applied to the job. Specifically, this value allows the client to override the Printer's "xxx-default" attribute value for the Job Template attribute, if one exists, and REQUIRES the Printer not to apply the feature to the job. In order for a client to be able to supply the 'none' out-of-band attribute value, the 'none' out-of-band attribute value MUST be one of the values in the corresponding "xxx-supported" Printer attribute. When returning a Job object in a Get-Job- Attributes or Get-Jobs response, the Printer MUST return in the response any requested attributes that had been supplied with the 'none' out-of-band value when the Job was created. This out-of-band attribute 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 MUST use the client- specified value and not the Printer's default value. This out-of-band value also allows the system administrator to explicitly configure certain "xxx-default" Printer attributes to indicate that there is no default. If a Printer supports the use of the 'collection' attribute syntax for an "xxx" attribute, a Printer MUST support the use of the "out-of-band" value 'none' in the "xxx", "xxx-default", and "xxx-supported" attributes, if supported. deBry, Hastings, Herriot, Ocke, Zehler [page 11] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 4.1.1Encoding of the 'none' out-of-band attribute value The encoding of the 'none' out-of-band attribute value is 0x14 (see [ipp-pro]). The value-length MUST be 0 and the value empty. 5 Unsupported Values The rules for returning an unsupported collection attribute are an extension to the current rules: 1. If the entire collection attribute is unsupported, then the Printer returns just the collection attribute name with the 'unsupported' out-of-band value (see the beginning of [ipp-mod] section 4.1) in the Unsupported Attributes Group. The encoding technique makes it easy for a Printer that doesn't support a particular collection attribute (or the collection attribute syntax at all) to simply skip over the entire collection value, since the entire contents of the collection value look like a single 1setOf (see section 7). 2. 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 or conflicting values. 6 Example definition of a collection attribute This example definition is for a collection attribute called "media- col". It meets the requirements for a definition document that defines a collection attribute given in section 3. The "media-col" collection attribute is a Job Template attribute. This collection attribute is simplified and fictitious and is used for illustrative purposes only. 6.1 media-col (collection) The "media-col" (collection) attribute augments the IPP/1.1 [ipp-mod] "media" attribute. This collection attribute enables a client end user to submit a list of media characteristics to the Printer as a way to specify the media more completely to be used by the Printer. When the client specifies media using the "media-col" collection attribute, the Printer object MUST match the requested media exactly. The 'collection' consists of the following member attributes: deBry, Hastings, Herriot, Ocke, Zehler [page 12] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 Table 1 - "media-col" member attributes Attribute name attribute syntax reque Printer st Support media-color type3 keyword | name (MAX) MAY MUST media-size type3 keyword | collection MAY MUST media-name type2 keyword | name MAY MAY The definitions for the member attributes is given in the following sub-sections: 6.1.1media-color (type3 keyword | name(MAX) This member attribute identifies the color of the media. Valid values are 'red', 'white' and 'blue' The "media-color-supported" (1setOf (type3 keyword | name(MAX))) Printer attribute identifies the values of this "media-color" member attribute that the Printer supports, i.e., the colors supported. 6.1.2media-size (collection) This member attribute identifies the size of the media. The 'collection' consists of the member attributes shown in Table 2: Table 2 - "media-size" collection member attributes Attribute attribute syntax reques Printer name t Support x-dimension integer (0:MAX) MUST MUST y-dimension integer (0:MAX) MUST MUST The definitions for the member attributes is given in the following sub-sections: 6.1.2.1 x-dimension (integer(0:MAX)) This attribute identifies the width of the media in inch units along the X axis. deBry, Hastings, Herriot, Ocke, Zehler [page 13] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 6.1.2.2 y-dimension (integer(0:MAX)) This attribute identifies the height of the media in inch units along the Y axis. The "media-size-supported" (1setOf collection) Printer attribute identifies the values of this "media-size" member attribute that the Printer supports, i.e., the size combinations supported. 6.1.3media (type3 keyword | name) See job template attribute "media". Additional restrictions on "media" in this collection are that the "media" member attribute value must be valid based on the size and color. When invalid names are given based on the size or color, the size or color value takes precedence. The "media-supported" (1setOf (type3 keyword | name(MAX))) Printer attribute identifies the values of this "media" member attribute that the Printer supports, i.e., the media keywords and names supported. 6.2 media-col-default (collection) The "media-col-default" Printer attributes specify the media that the Printer uses, if any, if the client omits the "media-col" Job Template attribute in the Job Creation operation (and the PDL doesn't include a media specification). The member attributes are defined in Table 1. A Printer MUST support the same member attributes for this default collection attribute as it supports for the corresponding "media-col" Job Template attribute. If the value of the "media-col-default" attribute is the 'no-value' out- of-band (see [ipp-mod] section 4.1) or the 'none' out-of-band value (see section ), the Printer does not apply a default value. 6.3 media-col-ready (1setOf collection) The "media-col-ready" Printer attribute identifies the media that are available for use without human intervention, i.e., the media that are ready to be used without human intervention. The collection value MUST have all of the member attributes that are supported in Table 1, plus the "media" (type3 keyword | name(MAX)) member attribute itself (see [ipp-mod] section 4.2.11), in order to indicate the unique keyword or name for each ready medium. 6.4 media-col-supported (1setOf type2 keyword) The "media-col-supported" Printer attribute identifies the keyword names of the member attributes supported in the "media-col" collection Job deBry, Hastings, Herriot, Ocke, Zehler [page 14] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 Template attribute, i.e., the keyword names of the member attributes in Table 1 that the Printer supports. 7 Encoding This section defines the additional encoding tags used according to [ipp-pro] and gives an example of their use. 7.1 Additional tags defined for representing a collection attribute value The 'collection' attribute syntax uses the tags defined in Table 3. Table 3 - Tags defined for encoding the 'collection' attribute syntax Tag name Tag Meaning value beginCollection 0x34 Begin the collection attribute value. endCollection 0x37 End the collection attribute value. memberAttrName 0x4A The value is the name of the collection member attribute When encoding a collection attribute "xxx" that contains an attribute "aaa", the encoding follows these rules: 1. The beginning of the collection is indicated with a value tag that MUST be syntax type 'begCollection' (0x34) with a name length and Name field that represent the name of the collection attribute ("xxx") as with any attribute, followed by a value length of 0 and no Value field, since the collection attribute's name doesn't have a value. 2. The member attributes are encoded as consecutive pairs of attributes as if they are a single multi-valued attribute i.e. 1setOf. The first value has the attribute syntax memberAttrName (0x4A) and its value holds the name of the member attribute ("aaa") and the second value holds the member attribute's value which can be of any attribute syntax, except memberAttrName. If the member attribute has multiple values, they are represented as any 1setOf values, namely, each Name field has a zero length and the rest represents the next value. 3. The end of the collection is indicated with a value tag that MUST be syntax type 'endCollection' (e.g. 0x37) and MUST have a zero name length and a zero value length. So even though it has a zero name length, it is the end of this collection value. deBry, Hastings, Herriot, Ocke, Zehler [page 15] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 4. It is valid to have a member attribute that is, itself, a collection attribute, i.e., collections can be nested within collections. This is represented by the occurrence of a member attribute which is of attribute syntax type 'begCollection'. It is terminated by a matching 'endCollection'. 5. It is valid for a collection attribute to be multi-valued, i.e., have more than one collection value. If the next attribute immediately following the 'endCollection' has a zero name length, then the collection attribute is multi-valued, as with any attribute. 7.2 Example encoding: "media-col" (1setOf collection) The collection specified in section 6.1 is used for the encoding example shown in Table 4, except that the syntax is changed from 'collection' to '1setOf collection' in order to show the encoding relationship between 1setOf and collection. The example also shows nested collections, since the "media-size" member attribute is a 'collection. The encoding example represents two 4x6-index cards, one blue and one white and takes 217 octets. The overall structure of the two collection values can be pictorially represented as: "media-col" = { "media-color" = 'blue'; "media-size" = { "x-dimension" = 6; "y-dimension" = 4 } }, { "media-color" = 'white'; "media-size" = { "x-dimension" = 6; "y-dimension" = 4 } }; Table 4 - Example Encoding of 1setOf collection with nested collection Octets Symbolic Protocol comments Value field 0x34 beginCollecti value-tag beginning of the "media- on col" collection attribute 0x0009 name- length of (collection) length attribute name media-col media-col name name of (collection) attribute 0x0000 value- defined to be 0 for this length type no value (since value- length was 0) deBry, Hastings, Herriot, Ocke, Zehler [page 16] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 Octets Symbolic Protocol comments Value field 0x4A memberAttrNam value-tag starts a new member e attribute: "media-color" 0x0000 name- defined to be 0 for this length type, so part of 1setOf no name (since name-length was 0) 0x000B value- length of "media-color" length keyword st media-color media-color value value is name of 1 member attribute 0x44 keyword type value-tag keyword type 0x0000 name- 0 indicates 1setOf length no name (since name-length was 0) 0x0004 value- length st blue blue value value of 1 member attribute 0x4A memberAttrNam value-tag starts a new member e attribute: "media-color" 0x0000 name- defined to be 0 for this length type, so part of 1setOf no name (since name-length was 0) 0x000A value- length of "media-size" length keyword nd media-size media-size value Name of 2 member attribute 0x34 beginCollecti value-tag Beginning of the "media- on size" collection attribute which is a sub-collection 0x0000 name- 0 indicates 1setOf length no name (since name-length was 0) 0x0000 value- collection attribute names length have no value no value (since value- length was 0) 0x4A memberAttrNam value-tag starts a new member e attribute: "x-dimension" deBry, Hastings, Herriot, Ocke, Zehler [page 17] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 Octets Symbolic Protocol comments Value field 0x0000 name- defined to be 0 for this length type, so part of 1setOf no name (since name-length was 0) 0x000B value- length of "x-dimension" length keyword st x-dimension x-dimension value name of 1 sub-collection member attribute 0x21 integer type value-tag attribute type 0x0000 name- 0 indicates 1setOf length no name (since name-length was 0) 0x0004 value- length of an integer = 4 length st 0x0006 value value of 1 sub- collection member attribute 0x4A memberAttrNam value-tag starts a new member e attribute: "y-dimension" 0x0000 name- defined to be 0 for this length type, so part of 1setOf no name (since name-length was 0) 0x000B value- length of the "y-dimension" length keyword nd y-dimension y-dimension value name of 2 sub-collection member attribute 0x21 integer type value-tag attribute type 0x0000 name- 0 indicates 1setOf length no name (since name-length was 0) 0x0004 value- length of an integer = 4 length nd 0x0004 value value of 2 sub- collection member attribute 0x37 endCollection value-tag end of the sub-collection 0x0000 name- defined to be 0 for this length type, so part of 1setOf no name (since name-length was 0) 0x0000 value- defined to be 0 for this length type deBry, Hastings, Herriot, Ocke, Zehler [page 18] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 Octets Symbolic Protocol comments Value field no value (since value- length was 0) Second collection value in set: 0x34 beginCollecti value-tag beginning of the collection on 0x0000 name- indicates still part of length 1setOf Note: name of member collection attribute is in the memberAttrName value no name (since name-length was 0) 0x0000 value- defined to be 0 for this length type no value 0x4A memberAttrNam value-tag starts a new member e attribute: "media-color" 0x0000 name- defined to be 0 for this length type, so part of 1setOf no name (since name-length was 0) 0x000B value- length of "media-color" length keyword st media-color media-color value name of 1 member attribute 0x44 keyword type value-tag keyword type 0x0000 name- 0 indicates 1setOf length no name (since name-length was 0) 0x0005 value- length of "white" keyword length st white white value of 1 member attribute 0x4A memberAttrNam value-tag starts a new member e attribute: "media-size" 0x0000 name- defined to be 0 for this length type, so part of 1setOf no name (since name-length was 0) deBry, Hastings, Herriot, Ocke, Zehler [page 19] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 Octets Symbolic Protocol comments Value field 0x000A value- length of "media-size" length keyword nd media-size media-size value name of 2 member attribute 0x34 beginCollecti value-tag beginning of the sub- on collection "media-size" is a sub- collection" 0x0000 name- 0 indicates 1setOf length no name (since name-length was 0) 0x0000 value- defined to be 0 for this length type no value (since value- length was 0) 0x4A memberAttrNam value-tag starts a new member e attribute: "x-dimension" 0x0000 name- defined to be 0 for this length type, so part of 1setOf no name (since name-length was 0) 0x000B value- length of "x-dimension" length keyword st x-dimension x-dimension value Name of 1 sub-collection member attribute 0x21 integer type value-tag attribute type 0x0000 name- 0 indicates 1setOf length no name (since name-length was 0) 0x0004 value- length of an integer = 4 length st 0x0006 value value of 1 sub- collection member attribute 0x4A memberAttrNam value-tag starts a new member e attribute: "y-dimension" 0x0000 name- defined to be 0 for this length type, so part of 1setOf no name (since name-length was 0) 0x000B value- length of the "y-dimension" length keyword deBry, Hastings, Herriot, Ocke, Zehler [page 20] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 Octets Symbolic Protocol comments Value field nd y-dimension y-dimension value name of 2 sub-collection member attribute 0x21 integer type value-tag attribute type 0x0000 name- 0 indicates 1setOf length no name (since name-length was 0) 0x0004 value- length of an integer = 4 length nd 0x0004 value value of 2 sub- collection member attribute 0x37 endCollection value-tag end of the sub-collection 0x0000 name- 0 indicates 1setOf length no name (since name-length was 0) 0x0000 value- defined to be 0 for this length type no value (since value- length was 0) 0x37 endCollection value-tag end of the set of collections 0x0000 name- defined to be 0 for this length type, so part of 1setOf no name (since name-length was 0) 0x0000 value- defined to be 0 for this length type no value (since value- length was 0) ISSUE 02 - The example contains a 1setOf collection and a nested collection, but does not contain a 1setOf member attribute. Should there be four separate examples that show a simple collection, a 1setOf member attribute, a 1setOf collection, and a nested collection? 8 Legacy issues IPP 1.x Printers and Clients will gracefully ignore collections and its member attributes if it does not understand the collection. The begCollection and endCollection elements each look like an attribute with an attribute syntax that the recipient doesn't support and so should ignore the entire attribute. The individual member attributes and their values will look like a 1setOf values of the collection attribute, so that the Printer simply ignores the entire attribute and all of its values. Returning unsupported attributes is also simple, deBry, Hastings, Herriot, Ocke, Zehler [page 21] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 since only the name of the collection attribute is returned with the 'unsupported' out-of-band value (see section 5). 9 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]. ISSUE 03 - Since this is intended to be a standards track document, do we also register the attribute syntax with IANA? 10 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]. 11 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]. 12 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-06.txt, March 1, 2000. [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- 05.txt, March 1, 2000. [RFC2565] Herriot, R., Butler, S., Moore, P., Tuner, R., "Internet Printing Protocol/1.0: Encoding and Transport", RFC 2565, April 1999. deBry, Hastings, Herriot, Ocke, Zehler [page 22] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 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. 13 Author's Addresses Roger deBry Utah Valley State College Orem, UT 84058 Phone: (801) 222-8000 EMail: debryro@uvsc.edu 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 Kirk Ocke Xerox Corp. 800 Phillips Rd M/S 139-05A Webster, NY 14580 deBry, Hastings, Herriot, Ocke, Zehler [page 23] [Expires: September 31, 2000] INTERNET-DRAFT IPP: The 'collection' attribute syntax March 31, 2000 Phone: (716) 442-4832 EMail: kirk.ocke@usa.xerox.com Peter Zehler Xerox Corp. 800 Phillips Rd M/S 139-05A Webster, NY 14580 Phone: (716) 265-8755 EMail: peter.zehler@usa.xerox.com 14 Appendix A: Full Copyright Statement Copyright (C) The Internet Society (1998,1999,2000). 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 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, Ocke, Zehler [page 24] [Expires: September 31, 2000]