New issue: support for multiple fault codes

As an offspring of the discussion on hierarchical fault codes [2] (see
thread [3], issue was closed by removing the dot notation), the issue of
how to support multiple fault codes was brought up but not resolved.

The assumption is that we want a homogeneous mechanism for conveying
multiple levels of fault codes: a base fault code which can be
understood by all SOAP 1.2 nodes and one or more fault codes that are
"application specific". This is likely to make life easier for general
SOAP nodes and intermediaries.

Note that over time, the "application specific" codes may themselves
become well-known as SOAP extensions are standardized. In many ways this
can be seen as a decentralized version of the commonly used 2 or 3-level
fault code mechanisms used in protocols like SMTP, HTTP etc. but where
we have QNames instead of using centrally registered status codes such
as 204, 251, and 401.

The proposal does not in any way change the SOAP 1.2 processing model or
SOAP Faults in general.

There has been some corridor discussion on whether we need one or more
such application fault codes. Personally I would lean towards not
limiting the number, but I wanted to bring up the point for discussion
so that it is not lost.

The proposed resolution is pretty much what Rich Salz and Martin Gudgin
proposed in the thread [3] but summarized here for convenience. Their
proposal also deals with issue 143 [1] which proposes that we change
"Client" to "Sender" and "Server" to "Receiver".

1) We split the existing SOAP fault code (not the fault reason)
information item into two parts. The schema definition for the split
faultcode will look like this

  <xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema'
             xmlns:tns='http://www.w3.org/2001/09/soap-envelope'
             targetNamespace='http://www.w3.org/2001/09/soap-envelope' >

    ...

    <xs:simpleType name='faultcodeenum'>
      <xs:restriction base='xs:QName'>
        <xs:enumeration value='tns:DataEncodingUnknown' />
        <xs:enumeration value='tns:MustUnderstand' />
        <xs:enumeration value='tns:VersionMismatch' />
        <xs:enumeration value='tns:Sender' />
        <xs:enumeration value='tns:Receiver' />
      </xs:restriction>
    </xs:simpleType>

    <xs:complexType name='faultcodeType' >
      <xs:sequence>
        <xs:element name='value' type='tns:faultcodeenum' />
        <xs:element name='sub' type='xsd:QName' minOccurs='0'
minOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>

  </xs:schema>

An example Fault element part of a SOAP envelope is:

    <S:Fault xmlns:S="http://www.w3.org/2001/09/soap-envelope"
             xmlns:rpc="http://www.w3.org/2001/09/soap-rpc">
	<faultcode>
	  <value>S:Client</value>
	  <sub>rpc:BadArguments</sub>
	<faultcode>
      <faultstring>Bad Arguments</faultstring>
    </S:Fault>

2) We enforce that the first (value) fault code is defined by the SOAP
1.2 part 1 specification; that is, it contains one of the status codes
defined by the faultcodeenum above.

3) Given that the encodingStyle attribute is defined in SOAP 1.2 part 1,
the proposal is to leave the DataEncodingUnknown faultcode in part 1
(there was some discussion about this point).

4) The "sub" fault code(s) are optional and if specified is defined by
the application using any namespace *other* than the namespace
containing the SOAP part 1 fault codes.

5) The "sub" fault code(s) can be used to carry both body fault codes
*and* header fault codes - it is *not* limited to body faults.

6) The faultreason is still a "human readable string" not intended for
automatic processing. There is only one such element.

7) No other parts of the SOAP Fault is changed.

Comments?

Henrik Frystyk Nielsen 
mailto:henrikn@microsoft.com 

[1] http://www.w3.org/2000/xp/Group/xmlp-issues.html#x143
[2] http://www.w3.org/2000/xp/Group/xmlp-issues.html#x130
[3] http://lists.w3.org/Archives/Public/xml-dist-app/2001Nov/0017.html

Received on Saturday, 1 December 2001 20:06:14 UTC