Subject: IPP> Comments on Operation attributes and operation validation

From: Tom Hastings <[email-masked]>
Date: Wed, 19 Nov 1997 00:00:54 PST

I have posted as .doc  .pdf   and  .txt  some comments on the
Operation attributes and operation validation from Bob, Scott, and myself.

The file is in:
ftp://ftp.pwg.org/pub/pwg/ipp/new_MOD/ipp-operation-attributes-and-validatio
n.doc  .pdf   .txt

I've also embedded the .txt file in this mail message.

We'd like to discuss this paper at the IPP telecon, Wed, 11/19/97 1-3 pm PST.
Send any comments as usual.  Many of the ideas in these comments came from
writing code to parse and validate operations according to the
algorithms in Section 15.3 of the Model document.

Thanks,
Tom

Subj:  Notes on Operation attributes and operation
validation
From: Tom Hastings, Bob Herriot, Scott Isaacson
Date:  11/18/97
File:   ipp-operation-attributes-and-validation

One goal of the validation is to maximize consistent
behavior between clients and servers of different vendors,
including different minor version numbers.  It is a goal to
try not to need a major version number change.  Major
version number changes are for changes that a client
implementing one major version cannot interwork with an IPP
object implementing another major version number (higher or
lower).  These comments on the IPP Model move us closer to
that goal, especially with respect to Operation attributes.
But first some comments on the Operation attributes:

1.   Comments on Operation Attributes

Here are some comments on the current draft of the Model
document which will create Operation attributes that are
OPTIONAL for a Printer object to support:

1.   The following four Job Template attributes should move
  to become Operation attributes and Job Description
  attributes: "compression", "job-k-octets", "job-
  impressions", and "job-media-sheets".  These attributes are
  describing the job, not requesting some type of processing.
  The corresponding "compression-supported", "job-k-octets-
  supported", "job-impressions-supported", and "job-media-
  sheets-supported" become Printer Description attributes.
  Also none of these four attributes had "xxx-default"
  attributes, further indicating that they are different from
  Job Template attributes.

2.   These four Operation attributes are OPTIONAL for
Printers to support, so some Operation attributes are
OPTIONAL for a Printer to support and some are MANDATORY.
Clients NEED NOT supply these Operation attributes, just as
when they were Job Template attributes.

2.   Validation of Operations

Given the above here are some more steps for validating
Operation attributes in all operations that should be added
to section 15.3 in order to meet the interworking goal:

1.   The validation of all Operation attributes is
  independent of the "ipp-attribute-fidelity" attribute.  The
  "ipp-attribute-fidelity" only applies to Job Template
  attributes in create and Validate-Job requests.

2.   For all operations:  An IPP object SHALL validate that
the length of each keyword and each attribute value meet the
requirements in the Model document.  If they don't, the IPP
object SHALL reject the request and return either the (new)
'client-error-keyword-or-value-too-long' or the (new)
'client-error-wrong-length-value' status codes as
appropriate.  For example: a keyword that is 256 or more
octets, or an integer that is not 4 octets long,
respectively.

3.   For all operations:  Client requests and IPP object
responses SHALL contain attribute groups in the order
specified by the model.  An IPP object SHALL verify that the
attribute groups are in the correct order. If an IPP object
receives a request with the attributes groups out of order,
the IPP object SHALL reject the request and return the (new)
'client-error-attribute-groups-out-of-order' status code.

4.   For all operations:  If the client fails to supply an
Operation attribute that clients MUST supply, the IPP object
SHALL return the (new) 'client-error-missing-required-
operation-attributes' status code with no indication of
which attribute.  This error is a development time error or
a major version number mismatch, not an end-user run-time
error and so a client SHOULD not display the status code to
a user.  Examples: "attribute-charset" and "attribute-
natural-language" MUST be supplied in all operations.

5.   For all operations:  an IPP object SHALL ignore all
unsupported Operation attributes, independent of the value
of the "ipp-attribute-fidelity" attribute.  An unsupported
attribute is either one that is not in the Model document or
that is in the Model document, but is not required to be
supported.  When the operation is otherwise successful, the
IPP object SHALL return the (existing) 'successful-ok-
ignored-or-substituted-attributes' status code.  In order to
inform the client of an unsupported Operation attribute, an
IPP object SHALL return such an Operation attribute with the
out-of-band 'unsupported' value copied to the (new)
delimited group in the response, called 'unsupported-
operation-attributes' (new delimiter tag in the Protocol
document).  This treatment of unsupported Operation
attributes in all operations is analogous to the handling of
unsupported Job Template attributes in the create and
Validate-Job operations.

     Rationale:  This rule is so that we can add OPTIONAL
  Operation attributes to future versions of IPP without
  affecting older clients.

6.   For all operations:  For supported Operation
  attributes, an IPP object SHALL validate that each supplied
  attribute value is among the set of supported values for
  that attribute. Such validation depends on the specification
  of the Operation attribute, not on the operation, and not on
  the value of the supplied "ipp-attribute-fidelity"
  attribute.  Some Operation attribute specifications indicate
  that the IPP object SHALL ignore any unsupported values,
  while other attribute specifications indicate that the IPP
  object SHALL reject the operation for any unsupported
  values.  See the tables in the next section for each
  Operation attribute.  For example, the IPP object SHALL
  ignore any unsupported values of "attribute-natural-
  language", "attributes-requested" and "which-jobs" and SHALL
  reject the operation for any unsupported values of
  "attribute-charset", "compression", and "document-format".

  Such validation includes checking to see (1) that the
  attribute syntax tag is correct for the attribute, (2)
  that the value is in the range specified for that
  attribute syntax in the Model document, (3) the multiple
  values are not supplied for attributes that are single-
  valued (not 1setOf), and (4) that the value is one of the
  set of values that are supported by the IPP object.  For
  some Operation attributes the set of supported values is
  specified by an "xxx-supported" Printer description
  attribute, such as "document-format-supported".  For
  other Operation attributes, the supported values are hard
  coded into the implementation.

  If the Model document requires unsupported values to be
  ignored for the particular Operation attribute, the IPP
  object SHALL return the (existing) 'successful-ok-ignored-
  or-substituted-attributes' status code.  If the Model
  document requires that unsupported values to be rejected
  for the particular Operation attribute, the IPP object
  SHALL return the (renamed) 'client-error-attributes-or-
  values-not-supported' status code.  See the tables below
  for each attribute.  In either case, the IPP object SHALL
  copy the attribute and value to the (new) 'unsupported-
  operation-attributes' delimited group in the response.

  Rationale: The reason for checking that the supplied
  values are supported and ignoring or rejecting, depending
  on the attribute, is so that a future version of IPP
  could extend the set of values without affecting older
  clients.

3.   Summary of new syntax for the Model and Protocol

Summary of new syntax to be added to the Model and Protocol:

1.   New delimited group in responses: 'unsupported-
  operation-attributes'
2.   New 'client-error-keyword-or-value-too-long' status
code
3.   New 'client-error-wrong-length-value' status code
4.   New 'client-error-attribute-groups-out-of-order' status
code
5.   New 'client-error-missing-required-operation-
attributes' status code
6.   Rename 'client-error-attribute-not-supported' status
code to 'client-error-attributes-or-values-not-supported',
since it may include both unsupported attributes and
unsupported attribute values.

4.   Validation of Job Template and Operation Attributes

This section contains a summary table of the validation of
Job Template and Operation attributes for all operations.
We propose that these tables be added to the Model document.

4.1  Validation of Job Template Attributes

The table below lists the Job Template attributes and shows
what the Printer SHALL do if a value is unsupported. All are
OPTIONAL for a Printer to support.  Each "xxx" attribute
that the Printer recognizes is checked against a printer
attribute with the name "xxx-supported" (after "copies-
collated-supported" gets removed) to determine if the value
is supported. If the Printer doesn't recognize/support an
attribute, the Printer treats the attribute as an unknown
attribute (see the unknown rows in the table below). Note
that when a Job Template attribute is not supported, the
value of the "ipp-attribute-fidelity" Operation attribute
determines whether to reject the job (true) or accept it and
ignore the attribute (false).

Job Template Attribute  value is supported if xxx- accept or
xxx                     supported exists and if    reject if
                        the value is:              value is
                                                   unsupported
                                                   
job-priority            the value is of the        based on
(integer(1:100))        correct type (value        fidelity
                        mapped to new priority
                        value)
                                                   
job-hold-until          the value is a member of   based on
(type4 keyword | name)  the set                    fidelity
                                                   
job-sheets              the value is a member of   based on
(type4 keyword | name)  the set                    fidelity
                                                   
multiple-document-      the value is a member of   based on
handling                the set                    fidelity
(type2 keyword)
                                                   
copies                  the value is  xxx-         based on
(integer(1:MAX))        supported value            fidelity
                                                   
finishings              the value is a member of   based on
(1setOf type2 enum)     the set                    fidelity
                                                   
page-ranges             the boolean value is true  based on
(1setOf                                            fidelity
rangeOfInteger(1:MAX))
                                                   
sides                   the value is a member of   based on
(type2 keyword)         the set                    fidelity
                                                   
number-up               the value is a member of   based on
(integer(0:MAX))        the set consisting of int  fidelity
                        and intRanges
                                                   
orientation             the value is a member of   based on
(type2 enum)            the set                    fidelity
                                                   
media                   the value is a member of   based on
(type4 keyword | name)  the set                    fidelity
                                                   
printer-resolution      the value is a member of   based on
(resolution)            the set                    fidelity
                                                   
print-quality           the value is a member of   based on
(type2 enum)            the set                    fidelity
                                                   
unknown attribute       the value is not           based on
                        supported                  fidelity

4.2

Validation of MANDATORY Operation Attributes

The table below contains abbreviations for operations:
                                           
Abbr Operation   Abb  Operation      Abbr  Operation
                 r
                                           
pj   Print-Job   sd   Send-Document  gap   Get-Attribute
                                           (Printer)
                                           
cj   Create-     su   Send-URI       gaj   Get-Attribute
     Job                                   (Job)
                                           
vj   Validate-   caj  Cancel-Job     gj    Get-Jobs
     Job
                                           
pu   Print-URI                             

The table below lists operation attributes that are
MANDATORY for a Printer to support, and shows what the
Printer SHALL do if a value is unsupported.  Each xxx
attribute is checked against some public or private printer
attribute which must exist because the attribute is
MANDATORY.  The check fails if its value is not among those
supported.
                                                  
Operation      Operatio  value is supported if    accept or
Attributes     ns        the value is:            reject if
xxx                                               value is
                                                  unsupported
                                                  
attributes-    all       a member of the set in   reject
charset                  Printer's "charset-      (client MUST
(charset)                supported", which is     send)
                         MANDATORY
                                                  
attributes-    all       any value of the         accept always
natural-                 correct type             (client MUST
language                                          send)
(naturalLangu
age)
document-uri                                      
(uri)          pu, su    a member of the set in   reject
                         the Printer's            (client MUST
                         "reference-uri-schemes-  send)
                         supported"
                                                  
job-id         sd, su,   a member of the set of   reject
(integer(1:MA  caj, gaj  jobIds                   (client MUST
X))                                               send)
                                                  
document-      pj, cj    a member of the set in   reject
format                   Printer's "document-     (client MAY
(mimeMediaTyp            format-supported"        send)
e)                       
                         ISSUE: this doesn't
                         seem to be MANDATORY
                         for a printer to
                         support. Is that an
                         oversight?
                                                  
last-document  sd, su    any value of the         reject
(boolean)                correct type             (client MAY
                                                  send)
                                                  
requested-     gap,      any value of the         reject
attributes     gaj, gj   correct type             (client MAY
(1setOf                                           send)
keyword)
                                                  
job-name       pj, cj,   any value of the         reject
(name)         vj, pu    correct type             (client MAY
                                                  send)
                                                  
document-name  pj, sd,   any value of the         reject
(name)         su        correct type             (client MAY
                                                  send)
                                                  
ipp-attribute- pj, cj,   any value of the         reject
fidelity       pu        correct type             (client MAY
(type 2                                           send)
keyword)
                                                  
limit          gj        any value of the         reject
(integer(1:MA            correct type             (client MAY
X))                                               send)

4.3

Validation of OPTIONAL Operation Attributes

The table below lists the operation attributes that are
OPTIONAL for a Printer to support and shows what the Printer
SHALL do if a value is unsupported. Each xxx attribute that
the Printer recognizes is checked against some public or
private printer attribute. If  the Printer doesn't
recognize/support an attribute, the Printer treats the
attribute as an unknown attribute (see the unknown rows in
the table below). For example, if a printer doesn't support
job-k-octets (because of the implementation or because of
some administrator's choice), the Printer treats job-k-
octets as an unknown attribute.

Operation      Operation value is supported if    accept or
Attributes     s         the value is:            reject if
xxx                                               value is
                                                  unsupported
                                                  
document-      pj, pu,   any value of the         accept always
natural-       sd, su    correct type
language
(naturalLangu
age)
                                                  
compression    pj, cj,   a member of the set in   reject
(type3         vj, pu    Printer's "compression-  (client MAY
keyword)                 supported"               send)
                                                  
job-k-octets   pj, cj,   a member of the          reject
(integer(0:MA  vj, pu    rangeOfInteger in the    (client MAY
X))                      Printer's "job-k-        send)
                         octets-supported"
                                                  
job-           pj, cj,   a member of the          reject
impressions    vj, pu    rangeOfInteger in the    (client MAY
(integer(0:MA            Printer's "job-          send)
X))                      impressions-supported"
                                                  
job-media-     pj, cj,   a member of the          reject
sheets         vj, pu    rangeOfInteger in the    (client MAY
(integer(0:MA            Printer's "job-media-    send)
X))                      sheets-supported"
                                                  
message        caj       any value of the         accept always
(text)                   correct type             (client MAY
                                                  send)
                                                  
which-         gap       a member of the set in   accept and
document-                Printer's "document-     ignore
format                   format-supported" and    attribute
(type2                   the Printer supports     (client MAY
keyword)                 this Operation           send)
                         attribute
                         
                         Note: a printer may
                         support several
                         document-formats for
                         printing but not
                         support this operation
                         attribute for Get-
                         Attributes.
                                                  
which-jobs     gj        a member of the set of   accept and
(type2                   values supported by      ignore
keyword)                 the operation (no        attribute
                         Printer attribute)       (client MAY
                                                  send)
                                                  
my-jobs        gj        a member of the set of   accept and
(boolean)                values supported by      ignore
                         the operation (no        attribute
                         Printer attribute)       (client MAY
                                                  send)
                                                  
unknown        all       not applicable           accept and
attribute                                         ignore
                                                  attribute
                                                  (client MAY
                                                  send)

ISSUE: the "document-format" Operation attribute is proposed
to be changed to "which-document-format" in the Get
Attributes (from Printer) operation, so that it isn't
confused with the "document-format" Operation attribute that
is used in pj, cj, vj, pu, sd, and su to identify the
document format of the document being submitted.