mustUnderstand reformulation

Glen Daniels and I were asked to propose a reformulation for
"mustUnderstand".  What follows is a first cut for review and discussion by
the workgroup.  The reformulation also attempts to remove overlap between
section 4.2.3 and the processing model stuff.  We did this in parallel with
Mark Hadley's work on eliminating overlap, so we probably unintentionally
duplicated some of his effort.  Presumably, the two approaches can easily
be reconciled if the workgroup believes that our overall direction is
correct.

Also, in preparing this note, I noticed a potential issue which perhaps
should be added to our list for tracking: not just in these sections, but
in the specification overall, have we made the changes necessary to allow
for Boolean attributes such as mustUnderstand to take the value of "true"
as well as "1"?  I did not make that change below.

Thank you.

Section 4.2.3 (original:  unmodified from SOAP 1.2 July WD)
-----------------------------------------------------------

[EdNote: This section partially overlaps with section 2. We expect this to
be reconciled in a future revision of the specification.]

The SOAP mustUnderstand global attribute can be used to indicate whether
the processing of a SOAP header block is mandatory or optional at the
target SOAP node. The target SOAP node itself is defined by the SOAP actor
attribute (see section 4.2.2). The value of the SOAP mustUnderstand
attribute is either "1" or "0". The absence of this attribute is
semantically equivalent to its presence with the value "0", which means
processing the block is optional.

When a SOAP header block is tagged with a SOAP mustUnderstand attribute
with a value of "1", the targeted SOAP node MUST: either process the SOAP
block according to the semantics conveyed by the fully qualified name of
the outer-most element of that block; or not process the SOAP message at
all, and fail (see section 4.4).

The SOAP mustUnderstand attribute allows for robust evolution. Elements
tagged with the SOAP mustUnderstand attribute with a value of "1" MUST be
presumed to somehow modify the semantics of their parent or peer elements.
Tagging elements in this manner assures that this change in semantics will
not be silently (and, presumably, erroneously) ignored by those who may not
fully understand it.

This attribute MUST appear in the SOAP message itself in order to be
effective, and not in an eventual corresponding XML Schema (see section 3
and 4.2.1).

Section 4.2.3 (proposed revision: removes overlap, deals with mustHappen)
-------------------------------------------------------------------------

The SOAP mustUnderstand attribute allows for robust evolution of SOAP
itself, of related services such as security mechanisms, and of
applications using SOAP. Elements tagged with the SOAP mustUnderstand
attribute with a value of "1" MUST be presumed to somehow modify the
semantics of their parent or peer elements. Tagging elements in this manner
assures that this change in semantics will not be silently (and,
presumably, erroneously) ignored by those who may not fully understand it.
Specific rules for processing header entries with mustUnderstand attributes
are provided in sections 2.4 and 2.5 <<these should be links>>)  This
attribute MUST appear in the SOAP message itself in order to be effective;
default values which may be specified in an XML Schema or other description
language do not affect SOAP processing. (see section 3 and 4.2.1).

The SOAP mustUnderstand attribute is useful for detecting situations in
which required software is not available at a node which has been correctly
targeted; it is not intended as a mechanism for detecting errors in
routing, misidentification of nodes, failure of a node to serve in its
intended role(s), etc.  any of which may result in a failure to even
attempt processing of a given header entry.  For that reason reason, this
specification does not by default provide for any fault to be generated
based on the presence or value of the mustUnderstand attribute in a header
not targeted to the processing node.   In general, processors SHOULD NOT
generate such faults, and this specification includes no standard
representation for such a fault.    This rule applies to the endpoint as
well as to intermediaries;  it is not in general an error for a
mustUnderstand header entry targeted to a node other than the endpoint to
reach the endpoint without having been processed.

Note, however, that SOAP extensions can be defined for indicating the order
in which processing is to occur, and for generating faults when a header
entry is not processed in the appropriate order.  Specifically, it is
possible to create SOAP header entries which are themselves targeted to the
endpoint (or intermediaries) and labeled mustUnderstand="1", and which have
as their semantic a requirement to generate some particular fault if other
headers have  inadvertently survived past the intended point in the message
path message (presumably due to a failure to reach the intended processing
node earlier in the path).  Such extensions MAY depend on the presence or
value of the mustUnderstand attribute in the surviving headers when
determining whether an error has occurred.  In the absence of such explicit
extensions, SOAP processors SHOULD NOT generate faults based on the
presence or value of the mustUnderstand attribute in a header not targeted
to the processing node.

Noah Mendelsohn &
Glen Daniels

Received on Monday, 6 August 2001 17:18:44 UTC