Discussion summary: Proposal for clarifying relationship between SOAP modules and features

Earlier this month, Henrik proposed some clarifications[1] 
between SOAP modules and features. Noah[2] and I[3,4] have 
proposed some (friendly) amendments. I have consolidated the 
proposed changes below, for easier reference.

David, could you please add this to next week's agenda?

Thank you,

Jean-Jacques.

[1] 
http://lists.w3.org/Archives/Public/xml-dist-app/2002Nov/0008.html
[2] 
http://lists.w3.org/Archives/Public/xml-dist-app/2002Nov/0023.html
[3] 
http://lists.w3.org/Archives/Public/xml-dist-app/2002Nov/0020.html
[4] 
http://lists.w3.org/Archives/Public/xml-dist-app/2002Nov/0021.html
--------


1) Part 1, section 3.1 "SOAP Features"
--------------------------------------

<current>
When a feature is expressed this way, the combined syntax
and semantics of such SOAP header blocks are known as a SOAP
Module, and are specified according to the rules in 3.2 SOAP
Modules.
</current>

<henrik>
The combined syntax and semantics of SOAP header blocks are
known as a SOAP module, and are specified according to the
rules in 3.2 SOAP Modules.
</henrik>

1) Part 1, section 3.1 "SOAP Features"
--------------------------------------

<current>
For the purpose of this specification, the term "feature" is
used to identify an extension of the SOAP messaging
framework typically associated with the exchange of messages
between communicating SOAP nodes. Although SOAP poses no
constraints on the potential scope of such features, example
features include "reliability", "security", "correlation",
and "routing". In addition, the communication might require
a variety of message exchange patterns (MEPs) such as one-
way messages, request/response interactions, and peer-to-
peer conversations. MEPs are considered to be a type of
feature, and unless otherwise stated, references in this
specification to the term "feature" apply also to MEPs. The
request-response MEP specified in [SOAP Part2] illustrates
the specification of a MEP feature.
</current>

<jjm-short>
A SOAP feature is an extension of the SOAP messaging
framework. Example of features are "reliability",
"security", "correlation", "routing" and also one-way
messages, request/response interactions and peer to peer
conversations.
</jjm-short>

<jjm-long>
*A SOAP feature is* an extension of the SOAP messaging
framework. *A SOAP feature is either associated with* the
*transfer and processing of individual* SOAP messages *or
with the exchange of related messages according to a given*
message exchange pattern (MEP). *Examples of the former type
of* features *are* "reliability", "security", "correlation"
and "routing". *Example of the second type of features
(MEPs) are* one-way messages, request/response interactions,
and peer-to-peer conversations.
</jjm-long>

2) Part 1, section 3.3 "MEPs"
-----------------------------

[Add the sentence about MEPs being a particular type of
feature, which was removed from proposal 1) above.]

<current>
A Message Exchnage Pattern (MEP) is a template that
establishes a pattern for the exchange of messages between
SOAP nodes. The specification of a message exchange pattern
MUST:
<current>

<jjm>
A Message Exchnage Pattern (MEP) is a template that
establishes a pattern for the exchange of messages between
SOAP nodes. *MEPs are a type of feature, and unless
otherwise stated, references in this specification to the
term "feature" apply also to MEPs. The request-response MEP
specified in [SOAP Part2] illustrates the specification of a
MEP feature.*

The specification of a message exchange pattern MUST:
</jjm>

2) Part 1, section 3.2 "SOAP Modules"
-------------------------------------

<current>
The term 'SOAP Module' refers to the set of syntax and
semantics associated with implementing a particular feature
(see 3.1 SOAP Features) as SOAP header blocks. A Module is
described in a Module Specification, which adheres to the
following rules. It:
</current>

<henrik>
The term 'SOAP module' refers to the specification of the
syntax and semantics of one or more SOAP header blocks. A
module specification adheres to the following rules. It:
</henrik>

<jjmFriendlyAmendment>
A SOAP Module *describes* the syntax and semantics of one or
more SOAP header blocks *used to implement* one or more SOAP
features. A module specification adheres to the following
rules. It:
</jjmFriendlyAmendment>

3) Part 1, Glossary
-------------------

<current>
None
</current>

<jjmNewGlossaryEntry>
A SOAP Module *describes* the syntax and semantics of one or
more SOAP header blocks *used to implement* one or more SOAP
features.
</jjmNewGlossaryEntry>

4) Part 1, section 3.2 "SOAP Modules", item 2
---------------------------------------------

<current>
MUST, if the Module implements a Feature which has already
been defined elsewhere, clearly refer to that Feature's URI.
Note that a Module may EITHER explicitly refer to a separate
Feature in this way OR may implicitly define a Feature
simply by describing the semantics of the Module.
</current>

<henrik>
MUST declare the features provided by a module.
</henrik>

<jjm>
MUST, if the module implements a feature which has already
been defined elsewhere, clearly *reference that feature
using the feature's URI*. Note that a module may EITHER
explicitly *reference an existing* feature in this way OR
may implicitly define a *new* feature simply by describing
the *module's semantics*.
</jjm>

5) Part 1, section 3.2 "SOAP Modules", item 5
---------------------------------------------

<current>
MUST clearly specify any known interactions with or changes
to the interpretation of the SOAP body. Furthermore, it MUST
clearly specify any known interactions with or changes to
the interpretation of other SOAP features (whether or not
those features are themselves modules). For example, we can
imagine a module which encrypts the SOAP body and inserts a
SOAP header block containing a checksum and an indication of
the encryption mechanism used. The specification for such a
module would indicate that the decryption algorithm on the
receiving side is to be run prior to any other modules which
rely on the contents of the SOAP body.
</current>

<henrik>
MUST clearly specify any known interactions with or changes
to the interpretation of the SOAP body. Furthermore, it MUST
clearly specify any known interactions with or changes to
the interpretation of other SOAP features *and SOAP
modules*. For example, we can imagine a module which
encrypts the SOAP body and inserts a SOAP header block
containing a checksum and an indication of the encryption
mechanism used. The specification for such a module would
indicate that the decryption algorithm on the receiving side
is to be run prior to any other modules which rely on the
contents of the SOAP body.
</henrik>

<noahFriendlyAmendment>
MUST clearly specify any known interactions with or changes
to the interpretation of the SOAP body. Furthermore, it MUST
clearly specify any known interactions with or changes to
the interpretation of other SOAP features *and SOAP
modules*. For example, we can imagine a module which
encrypts *and removes the SOAP body, inserting instead* a
SOAP header block containing the encrypted information and
an indication of the encryption mechanism used. The
specification for such a module would indicate that a
decryption algorithm on the receiving side is to be used to
reconstruct the body prior to invoking other modules that
rely on the contents of the SOAP body.
</noahFriendlyAmendment>

6) Part 1, TOC
--------------

<henrik>
Switch 3.2 "SOAP Modules" and 3.3 "SOAP Message Exchange
Patterns (MEPs)":

     3.1 SOAP Features
         3.1.1 Requirements on Features
     3.2 SOAP Message Exchange Patterns (MEPs)
     3.3 SOAP Modules
</henrik>

7) Module URI
-------------

<noah>
In JJM's other note he reiterates that a module can either
refer to a separate feature, or implicitly define the
feature inline with the module spec.  Fine, but what
concerns me is that we need a clean story on the URI naming
of these thinkgs:

- I very much want it to be the case that: every feature,
regardless of whether defined separately or in a module
spec, is to be named by a URI. This is very important so
that WSDL can evolve in a direction of defining services
that are supported iff the binding used supports some set of
features (typically not modules, as it is often the business
of the binding to decide whether to use a module or some
other means to implement the feature.)

- I am neutral on whether modules should also be named with
URIs, but I do want the rec to be clear.  If the answer is
yes, then we need to be clear that a module that defines its
own feature inline in its spec MUST provide URIs to name
each, and perhaps provide some guidance as to whether these
should in general be different or may be the same URI.
</noah>

Received on Thursday, 21 November 2002 10:40:59 UTC