Use of SOAP Fault FW: [SOAP] Question about MIME type

["Burdett, David" <david.burdett@commerceone.com>]

This email from Henri Frystyk Nelson of Microsoft, from the SOAP list,
provides more background on how to use SOAP fault.

David

-----Original Message-----
From: Henrik Frystyk Nielsen [mailto:frystyk@MICROSOFT.COM]
Sent: Sunday, February 25, 2001 9:22 AM
To: SOAP@DISCUSS.DEVELOP.COM
Subject: Re: [SOAP] Question about MIME type


>"The SOAP Fault element is used to carry error and/or status
>information within a SOAP message. If present, the SOAP Fault
>element MUST appear as a body entry and MUST NOT appear more
>than once within a Body element."
>
>Interpretation:
>
>        A SOAP Fault can only be located in a SOAP Body.

The spec says that "the SOAP Fault element MUST appear as a body entry and
MUST NOT appear more than once within a Body element" so your interpretation
only seems to cover one part of the requirement.

>Later, in the description of the Fault <detail> element it states:
>
>"It MUST NOT be used to carry information about error
>information belonging to header entries. Detailed error
>information belonging to header entries MUST be carried within
>header entries."

Note that the "it" here points to the "detail" element and not to the whole
SOAP Fault element of which the "default" element is a sub-element.

>Interpretation:
>
>        Information regarding SOAP Header errors MUST NOT be
>carried in a SOAP Fault <detail> element.

Yes that is correct. The "detail" element is reserved for body faults -
see below.

> The SOAP
>        authors appear to suggest that a SOAP Fault with NO
><detail> element serve as a "flag" to indicate
>      "header related errors" and a SOAP processor should
>examine the returned headers to locate the error(s).
>      How are header errors reported in a SOAP Header element
>- the spec is
>      silent on this and it opens the door to interoperability
>issues, IMO.

No, in fact the spec is quite clear on this - in [1] it is stated that:

   1) Information regarding SOAP Header errors MUST NOT be
      carried in a SOAP Fault <detail> element

   2) Detailed error information belonging to header entries
      MUST be carried within header entries.

The reason for that is that the purpose of SOAP headers is to provide a
mechanism for carrying extensions in an orthogonal manner so that these
extensions can be introduced without central control. This mechanism
also has to cover handling of faults - otherwise we would still have a
"scarce resource" in the SOAP message that would effectively limit how
new headers can be introduced.

The SOAP model is in fact quite simple:

* All faults MUST be reported using the SOAP Fault element

* All details from faults occurring in the body MAY be reported
  in the "detail" element

* All details from faults occurring in the header MAY be reported
  in the header

The basic idea behind this model is the following: Each SOAP "feature"
(or "block" as it is called in XML Protocol) provides some
functionality. Often there is fault situations associated with that
functionality - let's look at an example: Somebody defines an
authentication SOAP header entry that contains the following parts

a) A mechanism for carrying the challenge within the SOAP header
   entry

b) A mechanism for carrying the credentials within the SOAP header
   entry

c) A mechanism for carrying fault information that the challenge was
   not met

Presumably the implementation dealing with this header (in XML Protocol
this is called the handler) knows how to deal with both a) b) and c) -
otherwise it is not likely that it can interoperate with another
implementation.

By having all three parts be carried as a SOAP header, the SOAP
processor only needs to look in a single place for data belonging to
that header.

Expressed in a SOAP envelope this feature could look like this:

  <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
    S:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <S:Header>
        <m:Authentication xmlns:m="http://www.auth.org/simple">
           <m:credentials>Henrik</m:credentials>
        </m:Authentication>
     </S:Header>
     <S:Body>
        ... body goes here ...
     </S:Body>
  </S:Envelope>

And the response could be

  <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
    S:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
     <S:Header>
        <m:Authentication xmlns:m="http://www.auth.org/simple">
           <m:realm>Magic Kindom</m:realm>
        </m:Authentication>
     </S:Header>
     <S:Body>
        <S:Fault>
           <S:faultcode>S:Client</S:faultcode>
           <S:faultstring>Client Error</S:faultstring>
        </S:Fault>
     </S:Body>
  </S:Envelope>

As only the authentication knows what parameters are needed and how they are
represented it makes sense to have them be expressed in the same way as any
other parameters by that header. Note btw that there is nothing in SOAP that
requires a fault to actually be returned.

This is in fact very close to the HTTP model where parameters are
carried as HTTP header fields and if you don't know the parameters then
there is nothing you can do to fix the fault.

The model has two advantages which implementations may pick up on:

* it is possible to report multiple faults at the same time
  because they don't step on each other

* the SOAP processor can be written in a very generic way
  with only one dispatch mechanism

>Another option being discussed by ebXML TRP is the use of
><ErrorList> as a child element of SOAP Body and this "avoids"
>the restriction on the use of SOAP Fault to report ebXML
>header errors. Some folks are concerned that this "bypass" of
>the SOAP Fault is also a violation of the SOAP spec.

Yes that would be a mistake. As the ebXML errorlist can not guarantee to
contain all SOAP faults because those faults can be caused by non-ebXML
headers I am not sure what the benefit of the errorlist is.

>Sorry to be so long winded, but I hope this helped people
>understand some of the "challenges" SOAP implementers are
>struggling with. I am hopeful that the W3C XMLP effort will
>sufficiently address the issue above and other issues that
>could affect interoperability, especially the specifications
>regarding transport bindings.

If you want to make absolutely sure that XML Protocol people see mails
like this then you might want to consider sending this kind of mail to
the <xml-dist-app@w3.org> mailing list asking it to be included in the
issues list [2].

In general, SOAP only has to be concerned about interoperability within
the area addressed by SOAP proper and because SOAP itself is quite
simple, this is not that hard to describe. Any SOAP protocol binding
(below SOAP) and any SOAP based application (above SOAP) has to ensure
interoperability in its own right. It is therefore a mistake to expect
that interoperability between SOAP applications is provided by SOAP --
SOAP only provides interoperability for what it defines.

Henrik

[1] http://www.w3.org/TR/SOAP/#_Ref477488700
[2] http://www.w3.org/2000/xp/Group/xmlp-issues

You can read messages from the SOAP archive, unsubscribe from SOAP, or
subscribe to other
DevelopMentor lists at http://discuss.develop.com.