Subject: IPP> MOD/PRO - Proposal to add 'dictionary' attribute syntax

From: Tom Hastings <[email-masked]>
Date: Tue, 2 Sep 1997 23:57:55 PDT

Here is the action item that Roger and I had from the last meeting to
propose explicit text for a 'dictionary' attribute to be added to the
model and protocol documents.

I've posted the .pdf and .doc files in:

ftp://ftp.pwg.org/pub/pwg/new_MOD/
-rw-r--r--   1 pwg      pwg        24576 Sep  3 06:55 ipp-dict.doc
-rw-r--r--   1 pwg      pwg        18152 Sep  3 06:56 ipp-dict.pdf
-rw-r--r--   1 pwg      pwg        11511 Sep  3 06:56 ipp-dict.txt

Attached is the .txt file as well (but the .pdf file is much easier to read,
especially the long example).  Also the .pdf file has line numbers and is four
pages long.

If possible, I'd like to discuss this proposal at the Wed, 9/3, IPP telecon.

Tom

Subj:  Proposal for adding a 'dictionary' attribute syntax
to IPP Model
From: Tom Hastings and Roger deBry
Date:  9/02/97, version 0.5
File:  ipp-dict.doc

1.   Problem Statement

There is no good way to add attribute syntaxes that contain
several fields, whether the fields are mandatory or
optional.  Instead of each new attribute that needs more
than one field (struct), requiring an 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.  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 add to IPP standard,
that might be registered, or that implementors might
implement as private extensions.

2.   Suggested solution

Add a 'dictionary' attribute syntax, in which the attribute
value is a set of attributes.  Then each 'field' that is
present in the attribute value would be self identifying by
its attribute name.  An attribute with an attribute syntax
could be single valued ('dictionary'), i.e., with one
dictionary value, or could be multi-valued ('1SetOf
dictionary').  As with all attribute values, the dictionary
value has a length of the entire value.  If the dictionary
attribute is multi-valued, as with any multi-valued
attribute, each dictionary value has a length.  Thus
implementations that did not support the specified attribute
could skip over the entire value to get to the next
attribute (or to the next dictionary value, if the
dictionary attribute is multi-valued).  The syntax of each
dictionary value is the same as a set of attributes, so each
attribute has its keyword name, its attribute syntax code,
and its value.  An attribute in a dictionary can be single
valued or multi-valued as well.

For example, the new "printer-resolution" attribute was
defined using a very ad hoc 'resolution' attribute syntax.
Had we had the dictionary attribute syntax, we might have
chosen to use it here, though we wouldn't have had to
either.  If we did use the 'dictionary' attribute syntax for
the "printer-resolution", the attribute value would contain
the following attributes:  "cross-feed-resolution", "feed-
resolution", "units".  However, we can also keep resolution
as it is, even if we add the 'dictionary' attribute syntax.
As a second example, 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 dictionary value might include: "job-name",
"user-name", "job-comment", "account-name", etc. where the
values of the attributes in the dictionary are printed after
each attribute name on the job-start-page.

As a third example, an attribute could represent a person's
address using a dictionary that contains the following
attributes where each attribute has a simple 'text'
attribute syntax:

     "addressee-name"    required
     "company-name" optional
     "internal-mail-stop"     optional
     "apartment-number   optional
     "street-address"    required
     "city-or-town       required
     "state"             required
     "postal-zone        required
     "country"      optional
     "phone-numbers optional

The "address" attribute could be specified to be single-
valued ('dictionary'), or could be multi-valued ('1setOf
dictionary').  Also the specification for the "address"
attribute could require that the constituent attributes be
in the above order or that they could be in any order.  For
this example, it would make sense for the specification of
the "address" attribute to require that the dictionary be
ordered, with only the optional attributes being permitted
to be omitted.  It seems unnecessary to consider ordered and
unordered dictionaries as separate attribute syntaxes.

Some attribute specifications might allow additional
attributes to be included (open-ended) and other attribute
specifications might specify that only the attributes
specified in the standard or registration may be used in the
dictionary value (closed-ended).

As a fourth example, a dictionary attribute syntax would be
a much better way for the Printer to represent its
capabilities, rather than the ad hoc naming conventions:
"xxx" Printer attribute to represent default and the "xxx-
supported" Printer attribute to represent the supported
values.  So the client would request the "xxx" attribute of
the Printer and get back the "xxx" attribute whose
dictionary values would be the "default" and "supported-
values" attributes whose values would indicate the default
and supported values, respectively of the "xxx" job template
attribute.  Adding additional attributes to indicate future
capabilities, such as "ready-values", "multi-valued", etc.
could be done by adding additional attributes in the
dictionary value that is returned.

3.   Suggested Text

Add to section 4.1 Attribute Syntaxes of the IPP Model
specification:

dictionary:  a set or sequence of attributes, where each
attribute MAY be single-valued or multi-valued as specified
for the dictionary attribute.  As in the attribute sets that
are passed in operations, no attribute SHALL occur more than
once in a dictionary.  However, if the same attribute does
occur more than once  in a dictionary, the recipient SHALL
use the later occuring one, ignoring any earlier occurrences
of the same attribute.

The specification of the attribute that uses the
'dictionary' attribute syntax SHALL specify:

1.   as with any attribute, whether the attribute is single-
  valued (attribute syntax = 'dictionary) or multi-valued
  (attribute-syntax = '1SetOf dictionary').

2.   whether the attributes in the dictionary value are
ordered or unordered.

3.   for each attribute in the dictionary value, whether the
  attribute's presence is required or optional.

4.   for each attribute permitted in the dictionary value,
  the completed specification of that attribute shall be
  included or inferred by reference to the specification of
  that attribute elsewhere.

5.   whether additional attributes not specified with the
  dictionary attribute specification may be included (open-
  ended) in a dictionary value or not (closed-ended).  For
  open-ended dictionary attributes, there MAY be some
  requirements on what kind of attributes may be included,
  including restrictions on attribute syntaxes.

A dictionary may contain another dictionary, if the
specification of the dictionary attribute allows.

Add to section 9, Appendix A: Protocol Examples of the IPP
Protocol specification

9.2 Print-Job Request with an "address"  dictionary
attribute, including two address dictionary values and two
phone numbers in the first address dictionary value.
Octets       Symbolic     Protocol    comments
             Value        field
0x0100       1.0          version     
0x0002       PrintJob     operation   
0x02         start        attribute   
             attributes   tag
0x42         name type    value-tag   "job-name"
                                      attribute
0x0008                    name-       
                          length
job-name     job-name     name        
0x0006                    value-      
                          length
foobar       foobar       value       
0x??         dictionary   value-tag   "addresses"
             type                     attribute
0x0007                    name-       
                          length
address      address      name        
0x009c                    value-      156 octets in 1st
                          length      dict value
0x41         text type    value-tag   start of 1st
                                      dictionary value
0x000e                    name-       
                          length
addressee-   addressee-   name          "addresses-name"
name         name                       attribute
0x0009                    value-      
                          length
Tom Jones    Tom Jones    value       
0x41         text type    value-tag     "street-address"
                                        attribute
0x000e                    name-       
                          length
street-      street-      name        
address      address
0x000c                    value-      
                          length
100 Main St. 100 Main     value       
             St.
0x41         text type    value-tag     "city-or-town"
                                        attribute
0x000c                    name-       
                          length
city-or-town city-or-     name        
             town
0x0008                    value-      
                          length
New York     New York     value       
0x41         text type    value-tag     "state" attribute
0x0005                    name-       
                          length
state        state        name        
0x0002                    value-      
                          length
NY           NY           value       
0x41         text type    value-tag     "postal-zone"
                                        attribute
0x000b                    name-       
                          length
postal-zone  postal-zone  name        
0x0005                    value-      
                          length
10200        10200        value       
0x41         text type    value-tag     "phone-numbers"
                                        attribute
0x000d                    name-       
                          length
phone-       phone-       name        
numbers      numbers
0x08                      value-      
                          length
312-1234     312-1234     value       
0x41         text type    value-tag     start of 2nd
                                        phone-numbers
                                        value
0x0000                    name-         0 length means
                          length        next multiple
                                        value
0x0008                    value-      
                          length
372-8432     372-8432     value         end of 1st
                                        dictionary value
0x??         dictionary-  value-tag   start of 2nd
             type                     dictionary value
0x0000                    name-         0 length mean
                          length        next multple
                                        value
0xnnnn       0xnnnn       value-      nnnn octets in 2nd
                          length      dict value
0x41         text type    value-tag   start of 2nd
                                      dictionary value
0x000e                    name-       
                          length
addressee-   addressee-   name          "addresses-name"
name         name                       attribute
0x000a                    value-      
                          length
Bill Smith   Bill Smith   value       
...                                   nnnn octets of the
                                      next dict value
0x03         start-data   data-tag    
%!PS...      <PostScript  data

---

From: Scott Isaacson <[email-masked]>
Date: Thu, 04 Sep 1997 15:58:07 -0600

I have read through Tom's proposal, and I like it.  I plan to add it to the
model document as is.  I would also like to propose that "resolution" be
modified to be of syntax type "dictionary".  I am sure that there will be
more comments, but I don't see why we can't do that just a component of
the document itself, rather than a stand alone email message.

I know this is on the agenda for next week, but I expect it to eventually
go in the model doc.

Scott

>>> Tom Hastings <[email-masked]> 09/03 12:57 AM >>>

Attached is the .txt file as well (but the .pdf file is much easier to read,
especially the long example).  Also the .pdf file has line numbers and is
four
pages long.

Tom

1.   Problem Statement

2.   Suggested solution

3.   Suggested Text