Proposal for clarifying relationship between SOAP modules and features

Another action item that I volunteered to assist with is clarifying the
relationship between SOAP features and SOAP modules. This was discussed
at the Bedford f2f which resulted in the action item in the first place.

Current Situation
-----------------

I could find two pieces of text that address the relationship. In part
1, section 3.1 "SOAP Features", it says:

"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."

and in part 1, section 3.2 "SOAP Modules" it says:

"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:..."

The problem with both these paragraphs is that they imply that there is
a 1:1 relationship between a feature and a module and that a module is a
kind of feature. However, it seems reasonable that a SOAP module can
contain zero or more SOAP features and a SOAP feature can be referenced
by zero or more SOAP modules. This would also make it more consistent
with bindings that can contain zero or more features.

Proposal
--------

The proposal is to shorten the first paragraph to say

"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."

And to shorten the second paragraph as follows:

"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:..."

In addition, I suggest replacing list item 2 in section 3.2 with

"2. MUST declare the features provided by a module."

And in list item 5 replace "(whether or not those features are
themselves modules)" with
"and SOAP modules" so that the item reads:

"5. 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."

As an editorial nit, if we go with this proposal then I think it makes
sense to swap section 3.2 "SOAP Modules" and 3.3 "SOAP Message Exchange
Patterns (MEPs)" as an MEP indeed is a kind of feature. That is, I think
the ToC should look like this:

    3.1 SOAP Features
        3.1.1 Requirements on Features
    3.2 SOAP Message Exchange Patterns (MEPs)
    3.3 SOAP Modules

Comments?

Henrik Frystyk Nielsen 
mailto:henrikn@microsoft.com 

[1] http://www.w3.org/2000/xp/Group/2/06/LC/soap12-part1.xml#soapfeature
[2] http://www.w3.org/2000/xp/Group/2/06/LC/soap12-part1.xml#soapmodules

Received on Wednesday, 6 November 2002 11:19:55 UTC