RE: Extension mechanism proposal for 12/14 phone vote

["Adams, Robert" <robert.adams@intel.com>]

Some comments...

Moving ApplicationHeaders, Errors, and Acknowledgement to be top level
elements in ebXMLHeader is a good idea.  This is independent of the
extension mechanism, though.

I have problems with the "<xsd:anyAttribute namespace="##any"/>" and with
the more constrained "<xsd:anyAttribute
namespace="http://www.ebxml.org/namespaces/messageHeader"/>".  It doesn't
really help transport future extensions.  Say there are messages in the
world conforming to the version 1.0 spec.  Then we make a 2.0 spec with
additional elements in the ebXMLHeader.  Any 1.0 MHS will throw out the 2.0
message because of version or not understanding the new elements.  It will
have nothing to do with any acceptance by a schema validator.  We don't have
to put in placeholder elements for any of our own future extensions.

What about particular implementation extensions -- the ones those users of
our spec will be sure to make.  We could either allow implementers to be
ebXML transport validatable by giving them a place to extend things (adding
an "Extension" element) or let them add new elements anywhere they wish (in
a non-ebXML validatable fashion).

I think something like "mustUnderstand" must be included.  This is the
attribute used in the W3C specs so I don't like the idea of changing it when
we need the same semantics.  And it's another reason for having a new,
extending element ("<Extension>") since that's where the attribute will go.
Operationally, a sender can include extending information and be sure that
the client understands and has processed it.  The sender shouldn't just
assume that the receiver has handled the extra information.

The change to "Reference" from "Manifest" will not help any eventual
convergence with XMLDSig manifest because, since they use the same word to
describe them ("manifest"), the specified contents are very different --
ebXML specifies DocumentDescription (describing the things in the rest of
multi-part MIME) and XMLDSig specifies Reference's (describing the location
and digest and algorithm to the referenced item).  In other words, ebXML is
listing the manifest of the package contents and XMLDSig is listing the
referenced items that are signed.  And they are in different namespaces so
convergence can only consist of one spec saying they will use the namespace
qualified elements from the other specification.

If we include the <ds:Signature> element, we'll have to define some
processing rules.  For instance stuff like: "If the signature contains a
digest and signature over the <Header> element, the digest information must
(should/can?) be verified and, if it does not match, an error is returned."

So, to summarize:
I don't think we need to put in placeholders for elements that might be
added in future versions of this standard;
I think we should include a mechanism for implementation extensions;
I think the extension mechanism should enclose extensions in a new element;
I think the extension mechanism should have a "mustUnderstand" attribute so
the sender knows that a receiver understood the extension;
We should not throw around "any" specifications -- it will make the header
unreliable because there is no definitive definition of the contents and
schema validation will not catch errors;
Moving ApplicationHeaders, Errors, and Acknowledgement to be in ebXMLHeader
looks like a good idea and is orthogonal to the extension mechanism.

Hear you all on the phone tomorrow.

-- RA

-----Original Message-----
From: Christopher Ferris [mailto:chris.ferris@east.sun.com]
Sent: Wednesday, December 13, 2000 2:13 PM
To: 'ebxml-transport@lists.ebxml.org'
Subject: Re: Extension mechanism proposal for 12/14 phone vote


All,

Actually, I had something close to this in mind,
but have been working with David on some related
changes which incorporates a namespace qualified
extension capability into the ebXMLHeader document.
I had hoped to get this out sooner, but threw my back out
Monday and lost a day. 

Specifically, I have (as has Robert) used XMLSchema
and added:

<xsd:anyAttribute namespace="##any"/> 

to the list of attributes permitted in the 
ebXMLHeader element. This will permit us
to add any attributes necessary as we go forward.

We could restrict the namespace to:
	 http://www.ebxml.org/namespaces/messageHeader
if we wanted to preclude any other namespaced attributes
from being added.

I have also added three new elements as children of
ebXMLHeader:

<xsd:element ref = "ApplicationHeaders" minOccurs = "0" maxOccurs="1"/>
<xsd:element ref = "Errors" minOccurs = "0" maxOccurs="1"/>
<xsd:element ref = "Acknowledgment" minOccurs = "0" maxOccurs="1"/>
<xsd:element ref = "ds:Signature" minOccurs = "0"/>

Specifically, the ApplicationHeaders element is intended
to contain any APPLICATION-SPECIFIC extension headers.
It permits 0 or more namespace qualified extension elements
as children. The intent is to REQUIRE an MSH implementation
to make these available to the "application" via the MSH's
abstract service interface layer.

The Errors element essentially relocates the Error "payload"
information into the header document. I'm convinced... uncle...
Ralph and David have beaten me into submission;-) I now
agree that all MSH specific stuff must go in the header document.
Note that we're still discussing the form of the Error
element (which I carved out for this email).

The Acknowledgment element has been added to enable implicit
acks. David and I are still polishing up that aspect of
our combined proposal.

Finally, the ds:Signature element(s) are appended to enable
XMLDSig signing of the header (and optionally the payload
tbd based on my proposal before the ta-security group).

I haven't an explicit container element for header
extensions as has been proposed by Robert. Rather,
I have added:

<xsd:any namespace="##any" processContents="lax" minOccurs="0"/>

to the Header element, providing a place for namespace qualified
extension elements in the ebXMLHeader/Header element.

I have also provided the same capability for the Manifest/Reference
element (note the name change. I anticipate a *possible* convergence
with XMLDSig Manifest).

Note that the attached schema is still not finalized. It
represents a point in time of an exchange between David
and I which in all fairness he hasn't had a chance to
fully review and comment. Thus, I have carved out some of
the bits which we haven't come to full agreement on as yet.

Finally, I have, in the current draft of the CPP/CPA DTD
added a repeating element to the DeliveryChannel (or is it
DocExchange?) element which enumerates, for purposes
of interoperability, the list of namespace extensions
supported (or agreed to).

I haven't expressly added a mustUnderstand attribute, but
do agree that something of its ilk is needed. I was thinking
that to avoid any possible conflict, that we would choose
a name such as 'requiredExtension="true"' or possibly simply
'required="true"' be made available for use by an
extension element.

To be honest, I'm not sure how to define a "floating"
attribute such as this which is untethered to an element.

I think it is clear that we need to have a formal mechanism
in place to ensure that ebXML can add stuff as it needs
going forward. In that vein, it *may* also be necessary 
to add a wildcard element as a child of ebXMLHeader,
probably BEFORE ds:Signature which permits elements of
our namespace to be added in furure versions. This is
not reflected in the xsd attached, but deserves some
discussion.

Comments? 

Cheers,

Chris
"Adams, Robert" wrote:
> 
> Here is a description, text and schema for (what I believe) is the header
> extension mechanism we discussed last week.  This is for the vote that is
> scheduled for this Thursday's phone call.  This adds an <extension>
element
> to DocumentReference, Manifest and ebXMLHeader.  The contents of this
> element must be namespace qualified and it has a "mustUnderstand"
attribute
> that has a default value of "true".
> 
> == Add section 7.7.2.3 (missing?)
> == Add section 7.7.2.4
> 7.7.2.4 Extension
> The Extension element is optional and may occur multiple times within the
> ebXMLHeader element. It contains extra information pertaining to the
header
> or the document as a whole. Examples could be signature information on the
> Header or Manifest elements or extra routing or error information.
> The Extension element has an attribute "mustUnderstand" which can have the
> values "true" (or "1") and "false" (or "0"). A receiving agent who
receives
> a message with an Extension element who's "mustUnderstand" attribute's
value
> is "true", and the receiver does not know how to process the content, the
> receiver will return an error.  If the value of the "mustUnderstand"
element
> is "false", then the receiver may skip over the contents of this element
if
> the receiver does not know how to process the contents.
> If the "mustUnderstand" attribute is not present, the value is presumed to
> be "true".
> The elements in the body of the Extension element must be XML namespace
[XML
> Namespace] qualified.
> == Modify section 7.8
> "consisting of zero or more DocumentReference elements." becomes
"consisting
> of zero or more DocumentReference elements followed by zero or more
> extension elements".
> Append to paragraph: "The extension elements contain additional
information
> that pertains to the whole manifest.  Refer to section 7.7.2.4 for a
> detailed description of the Extension element.
> == Add in section 7.8.1 (added "Extension" to send of list)
> == Add section 7.8.1.4
> 7.8.1.4 Extension
> The <strong>Extension</strong> element is optional and may occur multiple
> times within the DocumentReference  element.  It contains extra
information
> pertaining to this particular document.  Examples could be signature or
> certificate information for the document or additional description or
> identification.  Refer to section 7.7.2.4 for a detailed explanation of
the
> Extension element.
> 
> ===================DTD Fragments======================
> <!ELEMENT xbXMLHeader (Manifest, Header, RoutingHeader, Extension*)>
> ...
> <!ELEMENT Manifest (DocumentReference+, Extension*)>
> ...
> <!ELEMENT DocumentReference (DocumentDescription?, DocumentLabel,
> DocumentID, Extension*)>
> ...
> <!-- this DTD does not enforce all of the constraints for "Extension".
The
> content of the Extension
>       element must be XML namespace qualified.  The default processing of
> the content is "skip". -->
> <!ELEMENT Extension (ANY)*>
> <!ATTLIST Extension mustUnderstand CDATA #IMPLIED "true">
> ===================Schema Fragments===================
> <element name="ebXMLHeader">
>     <complextype content="elementOnly">
>         <sequence>
>             <element ref="Manifest"/>
>             <element ref="Header"/>
>             <element ref="RoutingHeader"/>
>             <element ref="Extension" minOccurs="0" maxOccurs="unbounded"/>
>         </sequence>
>     </complextype>
> </element
> ...
> <element name="Manifest">
>     <complexType>
>         <sequence>
>             <element ref="DocumentReference"
>                     minOccurs="0" maxOccurs="unbounded"/>
>             <element ref="Extension"
>                     minOccurs="0" maxOccurs="unbounded/>
>         </sequence>
>     </complexType>
> </element>
> ...
> <element name="DocumentReference">
>     <complexType>
>         <sequence>
>             <element ref="DocumentDescription"
>                 minOccurs="0" />
>             <element ref="DocumentLabel" />
>             <element ref="DocumentID" />
>             <element ref="Extension"
>                     minOccurs="0" maxOccurs="unbounded"/>
>         </sequence>
>     </complexType>
> </element>
> ...
> <!-- Elements contained in Extension must be namespace
>     qualified.  If the namespace is not understood and the mustUnderstand
>     attribute is set to true, then the contents of the
>     DocumentReference should not be used. -->
> <element name="Extension">
>     <complexType>
>         <sequence>
>             <any namespace="##other" processContents="skip" />
>         </sequence>
>         <attribute name="mustUnderstand" type="boolean"
>                 use="optional" value="true" />
>     </complexType>
> </element>
> =========================end of Fragments =========================
> 
>         Robert Adams
>         mailto:Robert.Adams@intel.com
>         MS JF3-212
>         2111 NE 25th Ave
>         Hillsboro, OR   97124    USA
>         phone: +1.503.264.9424; cell: +1.503.709.3259; FAX:
+1.503.264.3375