INTERNET-DRAFT                                               Roger deBry
<draft-ietf-ipp-collection-00.txt>                  IBM Printing Company
<draft-ietf-ipp-collection-01.txt>             Utah Valley State College
                                                             T. Hastings
                                                       Xerox Corporation
                                                              R. Herriot
                                                       Xerox Corporation
                                                        December 8, 1999
                                                       February 22, 2000

                      Internet Printing Protocol/1.1: 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] and RFC2566], IPP/1.1 [ipp-mod, ipp-pro]. 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 C struct. PostScript dictionary
   or a Java Map.

                     [Expires:  August 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.

                     [Expires:  August 22, 2000]
                           Table of Contents

1  Problem Statement.................................................2 Statement.................................................4
2  Solution..........................................................2  Solution..........................................................4
3  Definition of a collection type...................................2 Collection Type...................................5
4  Unsupported Values................................................3  Order of Member Attributes........................................6
5  Encoding..........................................................3  New Operation Attribute...........................................6
 5.1collection-syntax-recognized (boolean)...........................6
6  Legacy issues.....................................................5  New Printer Attribute.............................................7
 6.1collection-syntax-recognized (boolean)...........................7
7  IANA Considerations...............................................6  New Out-of-band value.............................................7
 7.1'none'...........................................................7
8  Internationalization Considerations...............................6  Unsupported Values................................................7
9  Security Considerations...........................................6  Encoding..........................................................8
10 References........................................................6 Legacy issues.....................................................9
11 Author's Addresses................................................7 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...........................7
 12.1"job-notify" usage..........................12
 16.1"job-notify" Operation attribute...............................7
13 attribute..............................12
17 Appendix A: B: Full Copyright Statement..............................8 Statement.............................12

                     [Expires:  June 8,  August 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 C Java language uses the struct Map to solve this
problem.
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 allowed expected member attributes, as
does
the name a subclass of a C struct or Java class. Map. A collection value is similar to a group,
such as an operation group. They both consist of a series 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. 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, the
name of a member attribute client MUST be different from any indicate that it
"recognizes" collections by including the operation attribute
"collection-syntax-recognized" with the value of 'true' in an
operation or object unless its semantics 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 identical defined to those in
have values of collections and other attribute syntaxes.  For example,
if an attribute is defined to have the
operation or object. 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,
'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.

Note: if

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

                     [Expires:  August 22, 2000]

a collection can MAY either treat the collection as a bad value or ignore
all but one of the identically named members. member attributes.

3  Definition of a collection type Collection Type

When a specification defines an attribute "xxx" whose syntax type is
'collection' or '1setOf collection', it must define following aspects of
the collection.

1.the attribute.

  1. The name of the collection attribute "xxx"

  2. Its syntax type, whose characters are the same as
  those for a keyword.

2.the following information about each member attribute:

  a) its name, which is includes a keyword like all attributes. It must be unique
     within the collection type. It must also be unique with respect to
     operation 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 object attributes unless its semantics other values supported.

  5. the name of the collection type, whose characters are identical
     to the same as
     those in for a keyword.

  6. the operation or object.

                      [Expires:  June 8, 2000]
  b) its 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, include
     collection. including
       'collection'. If the attribute syntax type starts with "1setOf",
       the member 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

                     [Expires:  August 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?

                     [Expires:  August 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 is multi-valued.

  c) its allowed values, either enumerated explicitly or specified by syntax for
an attribute, a Printer MUST support the values use of a referenced attribute.

  d) whether it the "out-of-band" value
'none'.

A Printer MUST be or MAY be supplied by a client.

  e) its default support the "out-of-band" value if a client MAY supply it. The default 'none' as the value can
     be stated explicitly or can come from a specified attribute.

  f) whether it for
an attribute "xxx" if:

     @ the definition of the attribute specifies 'none' MUST be or
       supported AND

     @ the definition of the attribute specifies 'none' MAY be
       supported by and it is a value of the printer.

  g) its semantics

4 attribute "xxx-supported".

8  Unsupported Values

The rules for returning an unsupported collection attribute are an
extension to the current rules.

     1.If

   If a collection contains unrecognized, unsupported member attributes
   and/or conflicting value, 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. 'unsupported' (see the
   beginning of [ipp-mod] section 4.1). The unsupported member
   attributes and conflicting values have their unsupported values.

5

                     [Expires:  August 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.

sepCollection    0x38     Separate two collections of a multi-
                           valued attribute

 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, except that adjacent
endCollection and beginCollection values MUST be combined into a single

                      [Expires:  June 8, 2000]

sepCollection value. Its value field contains the collection type. In a
1setOf collection, the endCollection value marks the end of last
collection in the 1setOf collection. For legacy reasons, the  The name field for
the endCollection and sepCollection must be non-empty.  The name is
arbitrarily assigned to be "c". 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 job-notify attribute containing a set of 2
collections.

Octets             Symbolic       Protocol     comments
                   Value          field
0x34               beginCollecti  value-tag    Beginning of the collection
                   on                          collection
0x000a                          name-
                                length                            name-length
job-notify         job-notify     Name
0x000f                          Value-
                                length                            Value-length
job-notify-coll    job-notify-    Value        Collection type
                   coll
0x45               uri type       value-tag    "notify-recipients"
                                                attribute
0x0010                          name-
                                length
notify-                            name-length
notify-recipient   notify-        Name
                   recipient        recipient
0x0013                          value-
                                length                            value-length
ipp-                              Value
notify:port=700
0x44               keyword type   value-tag    "notify-event-groups"
                                                attribute
0x000d                          name-
                                length                            name-length
notify-events                     Name
0x0d                            value-
                                length                              value-length
job-completed                     Value
0x44               keyword type   value-tag    2nd "notify-event-groups" "notify-event-
                                                groups" attribute
0x0000                          name-                            name-length  0 length means next
                                length
                                                multiple value
0x0011                          value-
                                length
job-state-       job-           Value
changed          completion
0x38             sepCollection  value-tag  Separator between
                                           collection values
0x0001                          name-
                                length
c                               Name       Non-empty for legacy                            value-length

                     [Expires:  June 8,  August 22, 2000]

Octets             Symbolic       Protocol     comments
                   Value          field
job-state-changed  job-           Value
                   completion
0x37               endCollection  value-tag
0x0000                            name-length
0x000f                          value-
                                length                            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-                            name-length
notify-recipient                  Name
recipient
0x0014                          value-
                                length
mailto:smith@fo                            value-length
mailto:smith@foo.c                Value
o.com
om
0x44               keyword type   value-tag    "notify-event-groups"
                                                attribute
0x000d                          name-
                                length                            name-length
notify-events                     Name
0x0d                            value-
                                length                              value-length
job-completed                     Value
0x37               endCollection  value-tag    End of last collection
0x0001                          name-
                                length
c                               Name       Non-empty for legacy
0x0000                            name-length
0x000f                          value-
                                length                            value-length
job-notify-coll                   Value        Matches value of
                                           beginCollection

6  Legacy issues

The encoding has been designed
                                                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 work with IPP/1.0 and IPP/1.1
implementations. An IPP/1.0 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.

                     [Expires:  August 22, 2000]

Although a client or IPP/1.1 receiver Printer that doesn't recognize collections will treat
skip over the three new
syntax types, beginCollection, endCollection beginCollection and sepCollection endCollection tags as unrecognized
syntax types.  A legacy implementation is expected to
behave as follows.

A beginCollection value appears to be an attribute with an unsupported
value.

The member attributes that follow the beginCollection appear to be
normal attributes within their group (e.g. normal for the operation
attributes group). If an attribute has types, the same name as an attribute
allowed in client or Printer will mistakenly assume that the group, it as a recognized
member attributes are outside of the group (e.g. as a
normal operation attribute).

                      [Expires:  June 8, 2000]

An endCollection value appears to be an attribute with an unsupported
value and unrecognized name "c". The same collection.  Thus it
is true for a sepCollection
value.

7 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] and after IPP becomes a proposed
IETF standard.

8 [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.

9
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.

10 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-not]

[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-01.doc, draft-ietf-ipp-not-spec-02.txt, work in
     progress, October 10, 1999. 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.

[ISO-10175]
     ISO/IEC 10175 Document Printing Application (DPA), June 1996.

[RFC2565]
     Herriot, R., Butler, S., Moore, P., Tuner, R., "Internet Printing
     Protocol/1.0: Encoding and Transport", RFC 2565, April 1999.

                     [Expires:  June 8,  August 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.

11

[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

12

                     [Expires:  August 22, 2000]

16 APPENDIX A: Example of collection usage

This section describes one collection Job Template example.

12.1"job-notify"

16.1"job-notify" Operation attribute

The following example illustrates the definition of a collection
attribute for the "job-notify" operation attribute. attribute (see [ipp-ntfy]).
Each column of the table corresponds to information that is required for
member attributes.  Only the semantics have been omitted.

1.collection type: "job-notify-coll"

2.members of the collection

                      [Expires:  June 8, 2000]

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) <any octet     <empty         MUST
user-data                       string>        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 MAY to supply it.

13 the member attribute in a
request.

17 Appendix A: 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

                     [Expires:  August 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.

                     [Expires:  June 8, 2000]
                      [Expires:  June 8,  August 22, 2000]