PWG DRAFT Roger deBry File: ipp-collection-attr-syntax-v096.doc IBM Printing Company T. Hastings Xerox Corporation R. Herriot Sun Microsystems August 6, 1998 Proposed Internet Printing Protocol/1.0 Extension 'collection' attribute syntax Status of this Memo: This document is a PWG Working Draft. It proposes an OPTIONAL extension to the IPP/1.0 Model and Semantics document [ipp-mod]. There are some issues in Sections 4.1, 5, and 7. This attribute syntax will be registered with IANA after approval by the WG and after IPP/1.0 has been published as RFCs. We may want to publish it as an RFC as well. This attribute syntax had originally been named 'dictionary'. We agreed to change its name to 'collection' in [ipp-pro], since the member attributes are not ordered, typically. [ipp-pro] has reserved the tag value code 0x34 for 'collection'. Some future extensions, both registered and private, will make use of this new attribute syntax. Abstract This document specifies a new attribute syntax called 'collection'. A 'collection' value is itself a set of attributes, called "member" attributes, that are grouped together as the value of an attribute. The member attributes may be SINGLE-VALUED or MULTI-VALUED (1setOf). An attribute that uses the 'collection' attribute syntax may be SINGLE-VALUED ('collection) or MULTI-VALUED ('1setOf collection') as well. DeBry, Hastings, Herriot [page 1] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 Table of Contents 1 Problem Statement.................................................3 2 Summary of the attribute syntax alternative.......................3 3 Requirements for and properties of the suggested collection mechanism.............................................................3 4 Examples of collection usage......................................5 4.1 Example a: "printer-resolution" Job Template attribute.........5 4.1.1 "printer-resolution-default" example........................6 4.1.2 "printer-resolution-supported" example and validation of collections.......................................................6 4.2 Example b: "job-notify" Operation attribute....................6 4.3 Example c: Start page fields supplied by the end-user..........7 4.4 Example d: Postal mailing address..............................8 5 Detailed description 'collection' attribute syntax................8 6 Encoding..........................................................9 7 Rejected alternatives for a collection mechanism.................11 8 IANA Considerations..............................................13 9 Internationalization Considerations..............................13 10 Security Considerations..........................................13 11 References.......................................................13 DeBry, Hastings, Herriot [page 2] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 1 Problem Statement There is no good way to add attributes that contain several fields, whether the fields are mandatory or optional. Instead of each new attribute that needs more than one field (struct), requiring a new ad hoc attribute syntax, such as we have done for the 'resolution' attribute syntax for use in the "printer-resolution" attribute, it would be desirable to have a simple, general mechanism for representing multi- field values. (ISO DPA [ISO-10175] also had many ad hoc syntaxes for structure data types using ASN.1) It would also be desirable to allow fields to be omitted, when the attribute specification allows that. This mechanism would be useful for both new attributes that we might register as extensions to be used with the IPP standard, or that implementers might implement as private extensions. 2 Summary of the attribute syntax alternative A number of other alternatives were considered. See the last section for a list and the reasons for their rejection. The proposal is to add a new attribute syntax, called 'collection'. Any attribute of type 'collection' ha a value that is a set of attributes, called "member" attributes. Each member attribute MAY be single-valued or multi-valued (1setOf collection) as specified for the attribute that has the 'collection' attribute syntax. Since each attribute value has a length like any other attribute value, IPP objects not supporting the attribute can easily skip over the entire attribute value, i.e., skip over the entire set of attributes that make up a collection value. 3 Requirements for and properties of the suggested collection mechanism The collection mechanism for use with IPP needs to have the following semantic properties: 1. The collection mechanism provides a way to supply and query a set of attributes as a logical unit. Then each 'field' that is present in the collection would be self-identifying by its attribute name. 2. The attributes in a collection are unordered. Therefore, an IPP object MUST be able to accept attributes in a collection in any order. In order to improve processing efficiency, one or more member attributes of the collection may be specified as being REQUIRED to be first, just as for operation attributes in an IPP request. 3. The semantics of a collection attribute specifies which attributes in a collection instance are REQUIRED for the IPP object to support and which are OPTIONAL for the IPP object to support when the IPP object supports that collection attribute. 4. The semantics of a collection attribute specifies which attributes in a collection instance are required for the requester to supply and which the requester may omit. DeBry, Hastings, Herriot [page 3] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 5. A collection attribute could be single valued, i.e., with one collection value consisting of a set of attributes, or could be multi-valued, i.e., with multiple collection values, each consisting of a set of attributes. 6. An attribute in a collection value can be single valued or multi- valued as well according to the specification of the collection attribute. 7. As with all attribute values, if an IPP object does not support a collection attribute, it must be easy for the IPP object to ignore each collection attribute value, including returning whatever is required in the Ignored Attributes group in the response. 8. The syntax of each collection value is the same as a group of attributes in a request or response, so each attribute in a collection value instance has its keyword name, its attribute syntax code, and its value. 9. An implementer MAY support additional registered or private attributes in a collection. In other words, a collection is extensible, just like an attribute group in an operation or response. 10.S ince support of all possible combinations of values for all attributes in a collection value may not be supported by some implementations, there should be a way for the IPP object to indicate which combinations of values are supported. For example, 300x300, 600x300, and 600x600, but not 300x600 dpi. 11.F inally, an attribute in a collection value can be itself a collection, so that nesting could be allowed, if the specification of a collection attribute allowed a collection attribute to be contained in its collection. DeBry, Hastings, Herriot [page 4] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 4 Examples of collection usage This section describes four collection Job Template examples: "printer- resolution", "job-notify", "job-start-page-contents", and "postal-mail- disposition" attributes. The "printer-resolution" and "job-notify" attributes only contain single-valued member attributes, while the "job- start-page-contents" and "postal-mail-disposition" attributes contain multi-valued member attributes. 4.1 Example a: "printer-resolution" Job Template attribute For example, the new "printer-resolution" attribute was defined using a very ad hoc 'resolution' attribute syntax. Had we had the collection attribute syntax, we might have chosen to use it here, though we wouldn't have had to either. If we did use the 'collection' attribute syntax for the "resolution", the attribute value would contain the following attributes: "resolution", "cross-feed-resolution", and "resolution-units". We could have also specified that the "cross-feed- resolution" attribute is OPTIONAL and when omitted, the cross-feed resolution is the same as the "resolution" attribute, since most resolutions are the same in both directions. We could have also specified that the "resolution-units" attribute is OPTIONAL and when omitted, the resolution units are dots per inch. For the resolution, the "resolution" member attribute may be supplied by the client by itself when the value is the same for feed and cross-feed and the units are dots per inch. This would allow simple clients to provide most of the resolution capability in a simple way. The specification for the "printer-resolution" collection attribute is that its collection value is made up of the following attributes: Attribute name syntax in request -------------- ------ ---------- "resolution" integer required "cross-feed-resolution" integer optional "resolution-units" enum optional For a simplified collection attribute notation, lets use: "collection attribute" = { set of attributes and values } where a set of {} is used to group a single collection value. For example, a client supplying a resolution of 600 x 300 would be indicated in examples using the following notation: "printer-resolution" = { "resolution" = '600', "cross-feed- resolution" = '300' } DeBry, Hastings, Herriot [page 5] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 4.1.1 "printer-resolution-default" example The Printer object could represent the "printer-resolution-default" default values as a single collection value. For example, a system administrator (or the printer vendor) could specify the default as: "printer-resolution-default" = { "resolution" = '300' } 4.1.2" printer-resolution-supported" example and validation of collections The Printer object could indicate the combinations of resolutions that are supported by three sets of collection values which represent 300x300, 600x300, and 600x600 dpi, respectively (300x600, say, is not supported). Such a configured situation could be represented in examples as: "printer-resolution-supported" = { { "resolution" = '300' }, { "resolution" = '600', "cross-feed-resolution" = '300' }, { "resolution" = '600' } } 4.2 Example b: "job-notify" Operation attribute NOTE: The current proposal for notification does not use the collection mechanism [ipp-not]. This example just shows how we could use the collection attribute syntax, if it is necessary to be able to group events and methods, rather than saying that the mail method ignores most of the events, so that other methods can be specified in the same job subscription. Because the 'collection' attribute syntax is itself multi-valued, the member attributes do not need to be, thus simplifying the syntax However, the same recipient can be in more than one collection value, and the same event group can be in more than one collection value. In order to allow a client to supply different event groups for different recipients/methods, the requester must be able to supply one or more notification collection values, where each collection value consists of one "notify-event" attribute and one "notify-recipient" attribute. Additional registered or private attributes may be included in the future. There might be a similar multi-valued "printer-notify" Printer object collection attribute that is supplied by a new Subscribe operation, but is independent of jobs. Both the "job-notify" and the "printer-notify" collection attributes are MULTI-VALUED but contain attributes that themselves are only SINGLE-VALUED. The "job-notify" Operation collection attribute would have collection values with the following syntax: Attribute name syntax in request ----------------- ------- ------------ "notify-event-group" type2 keyword OPTIONAL "notify-recipient" uri REQUIRED DeBry, Hastings, Herriot [page 6] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 A Print-Job request could supply the collection attribute values in order to send immediate 'job-error' events to Smith (himself) and e-mail 'job-completion' to Jones and White. "job-notify" = { "notify-event-group" = 'job-errors' "notify-recipient" = "ipp-tcpip-socket:13.240.120.138/port=6000' }, { "notify-event-group" = 'job-completion' "notify-recipient" = 'mailto:Jones' } { "notify-event-group" = 'job-completion' "notify-recipient" = 'mailto:White' } 4.3 Example c: Start page fields supplied by the end-user As a third example of a collection, an attribute could represent the fields that the submitter wishes to be printed on the job-start page. The name of the attribute might be: "job-start-page-contents". The collection value might include: "job-name", "user-name", "job-comment", "account-name", "job-disposition", "job-delivery", etc. where the values of the attributes in the collection are printed after each attribute name on the job-start-page. Attribute name syntax in request ----------------- ------- ------------ "job-name" name required "user-name" name required "job-comment" text optional "account-name" name optional "job-disposition" keyword optional "job-delivery" 1setOf keyword optional DeBry, Hastings, Herriot [page 7] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 4.4 Example d: Postal mailing address As a final example of a collection, an attribute could represent a postal mailing address for the output. The name of the attribute might be "postal-mail-disposition" and it would be multi-valued, i.e., 1setOf collection. The collection attribute might have the following specification and support requirements if the "postal-mail-disposition" collection attribute is supported at all: Attribute name syntax in request IPP object support -------------- ------- ---------- ------------------- "addressee-name" text required REQUIRED "company-name" text optional OPTIONAL "internal-mail-stop" text optional OPTIONAL "apartment-number text optional REQUIRED "street-address" text required REQUIRED "city-or-town text required REQUIRED "state" text required REQUIRED "postal-zone text required REQUIRED "country" text optional OPTIONAL "phone-numbers 1setOf text optional OPTIONAL 5 Detailed description 'collection' attribute syntax Register the following attribute syntax, written in the style of section 4.1 Attribute Syntaxes of the IPP Model specification: 4.1.n 'collection' A set of unordered attributes called member attributes, where each member attribute MAY be single-valued or multi-valued as specified for the collection attribute. The length of each collection value MUST be less than 1024 octets. As in the attribute sets that are passed in an operation group, an IPP object MUST accept the attributes in a collection value in any order. The specification of an attribute whose attribute syntax is 'collection' MAY specify one or more member attributes that MUST be first in each collection value, in order to simplify processing, just as in the Operation attributes. If an attribute that is specified to be first is not in its required position, the IPP object MUST reject the operation and return the 'client-error-bad syntax' error status code. See [ipp- mod] Section 16.3.4.1. No attribute SHALL occur more than once in a collection value. As in operation requests, if the same attribute does occur more than once in a collection value by error, the IPP object MUST reject the operation and MUST return the 'client-error-bad syntax' error status code. See [ipp- mod] Section 16.3.4.3. The specification of the attribute that uses the 'collection' attribute syntax specifies: DeBry, Hastings, Herriot [page 8] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 1. as with any attribute, whether the attribute is single-valued (attribute syntax = 'collection') or multi-valued (attribute-syntax = '1setOf collection'). 2. for each member attribute in the collection value, whether the IPP object MUST support the attribute (REQUIRED) or MAY support the attribute (OPTIONAL). 3. for each member attribute in the collection value, whether the client MUST supply or MAY omit the member attribute in a request and whether the IPP object MUST supply or MAY omit the member attribute in a response. 4. for each member attribute permitted in the collection value, the completed specification of that member attribute is included or inferred by reference to the specification of that attribute elsewhere, including its keyword name, its attribute syntax, including '1setOf, if it is multi-valued, and the semantics of the values. The specification for a collection may include attributes that have already been defined for use by themselves and/or for use in other collections. 5. for each member attribute defined in the collection, whether that attribute may also be used separately by itself. For example, in the "job-notify" example, could the "job-notify-events" and "job-notify- recipients" attributes occur by themselves in a create operation, say, when the client is only specifying a single collection or must they always occur within a collection value. 6. for each member attribute defined in the collection, whether that attribute MAY occur anywhere in the collection value (the default case) or MUST be first or after some other attribute that MUST be first (must be explicitly specified). A collection may contain another collection, i.e., may include a member attribute whose attribute syntax is, itself, a 'collection', if the specification of the (outer) collection attribute allows. Additional attributes may be registered for use in a collection attribute. Implementers MAY support additional private attributes in a collection value. 6 Encoding This section shows the encoding for the alternative of representing a collection as a new attribute syntax. The new 'collection' attribute syntax will use the 0x34 tag value that has been reserved in the IPP/1.0: Protocol Specification [ipp-pro] for this purpose. The following example is written in the style of the IPP/1.0 "Encoding and Transport" (nee "Protocol") document [ipp-pro]. In order to show a member attribute with multiple values, the member attributes are DeBry, Hastings, Herriot [page 9] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 specified as 1setOf, unlike the "job-notify" example b above (see section 4.2). Octets Symbolic Protocol comments Value field 0x34 collection value-tag "job-notify" type attribute 0x000a name- length Job-notify job-notify Name 0x0064 value- 100 octets in length 1st dict value 0x45 uri type value-tag "notify- recipients" attribute 0x0011 name- length notify- notify- Name recipients recipients 0x0019 value- length ipp-tcpip- ipp-tcpip- Value socket:port socket:port= =700 700 0x44 keyword type value-tag "notify-event- groups" attribute 0x0013 name- length notify- notify- Name event- event-groups groups 0x0b value- length job-errors job-errors Value group 0x44 keyword type value-tag start of 2nd job-notify- event-groups value 0x0000 name- 0 length means length next multiple value 0x000e value- length job- job- Value completion completion 0x34 collection- value-tag start of 2nd type collection value 0x0000 name- 0 length mean length next multiple value 0xnnnn 0xnnnn value- nnnn octets in length 2nd dict value DeBry, Hastings, Herriot [page 10] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 Octets Symbolic Protocol comments Value field 0x45 uri type value-tag "notify- recipients" attribute 0x0015 name- length notify- notify- Name recipients recipients 0x000c value- length mailto:smit mailto:smith Value h ... nnnn octets of the next dict value 7 Rejected alternatives for a collection mechanism This section lists the alternatives we considered for adding a new attribute syntax to represent a collection value. 1. Increase the maximum somewhat above the current maximum (1023), say, 2047 octets. Reason for rejection: Not completely compatible with current parsers that have a fixed buffer size for entities of around 1023 octets, the current IPP data type maximum. ISSUE: Is this rejection argument correct, because current parsers really do have a fixed buffer size? What about the case when the attribute syntax type is one that the implementation doesn't support and are going to ignore? They wouldn't need to return the value in the Ignored Attributes group, since we could clarify that a supported attribute that has an unsupported attribute syntax, is treated as an unsupported attribute, rather than as an unsupported value. Then the IPP object returns the attribute with the 'unsupported' out-of-band value, rather than the potentially longer than their buffer collection value. Or would it be a problem to current parsers to specify the maximum as 2047 octets for the 'collection' attribute syntax? 2. No maximum length for the new attribute syntax: 'collection'. If an IPP object supports collection it has to read a piece at a time. If it doesn't it has to be able to ignore an arbitrarily long data value. See the encoding example in the next section. Reason for rejection: Not compatible with current parsers that have a fixed butter size for entities of around 1023 octets, the current IPP data type maximum. ISSUE: Is this rejection argument correct, because current parsers have a fixed buffer size, even for attribute syntax types that they don't support and are going to ignore? They wouldn't need to return the value in the Ignored Attributes group, since we could clarify that a supported DeBry, Hastings, Herriot [page 11] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 attribute that has an unsupported attribute syntax, is treated as an unsupported attribute, rather than as an unsupported value. Then the IPP object returns the attribute with the 'unsupported' out-of-band value, rather than the potentially longer than their buffer collection value. 3. Have a 1023 octet max length, continueCollection as a second attribute syntax and endCollection so that dictionaries can nest. Reason for rejection: More complexity. 4. Have a 1023 octet max length but allow repeated instances of an attribute to append additional collection values. Reason for rejection: Not the current procedure for duplicate attributes; the IPP Object is to return an error. See [ipp-mod] section 16.3.4.3. 5. Add a new group tag to represent a collection value somehow. Groups do NOT have lengths and existing parsers are supposed to ignore group tags they don't understand. Reason for rejection: Not completely compatible with existing parsers. 6. Add an out-of-band value that indicates that this attribute was the beginning of a collection and add an attribute that marked the end of the collection value. Reason for rejection: Not completely compatible with existing parsers. Existing parser would try to interpret the contents of the collection as regular attributes. 7. Extend the attribute naming mechanism to include a collection name and a collection index for use with multi-valued dictionaries. Use the colon (":") to separate component names. Thus if foo is a set of dictionaries, then "foo:1:x" is the name that accesses field x of the nd 2 collection of attribute foo (indexing is 0 based). Leaving off the syntax after either colon, is interpreted as a wild card meaning all values with the prefix up to the colon. Reason for rejection: Changing the naming is more of a change than is necessary with the current proposal, which simply adds an attribute syntax. 8. Use the semantics of parallel multi-valued attributes that we have in IPP/1.0, such as we already have for the "printer-uri-supported" and "uri-security-supported" Printer attributes, in order to achieve the effect of multi-valued dictionaries containing single values attributes. In order to represent the effect of a collection which contains attributes that are multi-valued, we only need to introduce the model semantics of: 1setOf 1setOf X as an attribute syntax. Reason for rejection: Implementation experience with DPA [ISO-10175] parallel attributes has shown that it is too difficult for clients and DeBry, Hastings, Herriot [page 12] IPP 'collection' attribute syntax Version 0.96 Aug 6, 1998 servers to deal with parallel values. It is much better if the values in a collection value are all bound together. Also what if the number of values isn't the same in the parallel attributes? 9. Add a numeric instance number to the end of parallel attributes, i.e., "notify-method-supported-1". Reason for rejection: Parallel attributes have proven as problematic in DPA implementations (see previous reason). Also we don't need the capability to be able to address a particular instance of a particular collection value. 8 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.0 Model and Semantics [ipp-mod]. 9 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. 10 Security Considerations This attribute syntax causes no more security concerns than any 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. 11 References [ipp-mod] Herriot , S., deBry, R., Hastings, T., Herriot, R., Powell, P., “Internet Printing Protocol/1.0: Model and Semantics” draft-ietf- ipp-mod-10.txt, June, 1998. [ipp-not] Isaacson, S., Martin, J., deBry, R., Hastings, T., “IPP Event Notifications (Very Short)” , work in progress, July 1, 1998. [ipp-pro] Herriot, R., Butler, S., Moore, P., Tuner, R., "Internet Printing Protocol/1.0: Encoding and Transport", draft-ietf-ipp-pro-06.txt, June, 1998. [ISO-10175] ISO/IEC 10175 Document Printing Application (DPA), June 1996. DeBry, Hastings, Herriot [page 13]