Web Services Base
Faults 1.2
(WS-BaseFaults)
OASIS Standard, April 1 2006
Document identifier: wsrf-ws_base_faults-1.2-spec-os
Location:
http://docs.oasis-open.org/wsrf/wsrf-ws_base_faults-1.2-spec-os.pdf
Editors:
Lily Liu, webMethods <lily.liu@webmethods.com>
Sam Meder, Argonne National Laboratory < meder@mcs.anl.gov>
Abstract:
Problem determination in a Web services setting is simplified by standardizing a base set of information that may appear in fault messages. WS-BaseFaults defines an XML Schema type for base faults, along with rules for how this base fault type is used and extended by Web services.
Status:
This document is an OASIS Standard.
Committee members should send comments on this specification to the wsrf@lists.oasis-open.org list. Others may submit comments to the TC via the web form found on the TC's web page at http://www.oasis-open.org/committees/wsrf. Click the button for "Send A Comment" at the top of the page. Submitted comments (for this work as well as other works of that TC) are publicly archived and can be viewed at http://lists.oasis-open.org/archives/wsrf-comment/.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the WSRF TC web page (http://www.oasis-open.org/committees/wsrf/).
Table of Contents
2.1 Example SOAP 1.1 Encoding of a Base Fault
2.2 Example SOAP 1.2 Encoding of a Base Fault
3 Use of Base Faults in WSDL 1.1
1 Introduction
A designer of a Web services application often uses interfaces defined by others. Managing faults in such an application is more difficult when each interface uses a different convention for representing common information in fault messages.
Support for problem determination and fault management can be enhanced by specifying Web services fault messages in a common way. When the information available in faults from various interfaces is consistent, it is easier for requestors to understand faults. It is also more likely that common tooling can be created to assist in the handling of faults.
WS-BaseFaults defines an XML Schema type for a base fault, along with rules for how this fault type is used by Web services.
WS-BaseFaults is inspired by a portion of the Global Grid Forum’s “Open Grid Services Infrastructure (OGSI) Version 1.0” specification [OGSI].
1.1 Goals and Requirements
The goal of WS-BaseFaults is to standardize the terminology, concepts, XML types, and WSDL usage of a base fault type for Web service interfaces.
1.1.1 Requirements
This specification intends to meet the following requirements:
Define a standard XML Schema type containing base fault information.
Define how this base fault type is used within WSDL defined interfaces.
1.1.2 Non-Goals
The following topics are outside the scope of this specification:
It is not an objective of this specification to define a common hierarchy of common faults upon the base fault.
1.2 Terminology
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
When describing abstract data models, this specification uses the notational convention used by the [XML-Infoset]. Specifically, abstract property names always appear in square brackets (e.g., [some property]).
This specification uses a notational convention, refered to as “Pseudo-schemas” in a fashion similar to the WSDL 2.0 Part 1 specification. A Pseudo-schema uses a BNF-style convention to describe attributes and elements:
`?' denotes optionality (i.e. zero or one occurrences),
`*' denotes zero or more occurrences,
`+' one or more occurrences,
`[' and `]' are used to form groups,
`|' represents choice.
Attributes are conventionally assigned a value which corresponds to their type, as defined in the normative schema.
<!-- sample pseudo-schema -->
<element
required_attribute_of_type_QName="xs:QName"
optional_attribute_of_type_string="xs:string"? >
<required_element />
<optional_element />?
<one_or_more_of_these_elements />+
[ <choice_1 /> | <choice_2 /> ]*
</element>
Where there is disagreement between the separate XML schema and WSDL files describing the messages defined by this specification and the normative descriptive text (excluding any pseudo-schema) in this document, the normative descriptive text will take precedence over the separate files. The separate files take precedence over any pseudo-schema and over any schema and WSDL included in the appendices
1.3 Namespaces
The following namespaces are used in this document:
|
Prefix |
Namespace |
|
s11 |
http://schemas.xmlsoap.org/soap/envelope/ |
|
s12 |
http://www.w3.org/2003/05/soap-envelope |
|
xsd |
http://www.w3.org/2001/XMLSchema |
|
xsi |
http://www.w3.org/2001/XMLSchema-instance |
|
wsrf-bf |
http://docs.oasis-open.org/wsrf/bf-2 |
|
wsa |
http://www.w3.org/2005/08/addressing |
1.4 Fault Definition
All faults defined by this specification MUST use the following wsa:Action
URI:
http://docs.oasis-open.org/wsrf/fault
2 Base Fault Type
The base fault has the following syntax. The normative XML Schema definition is in Appendix D:
<BaseFault>
{any}*
<Timestamp>xsd:dateTime</Timestamp>
<OriginatorReference>
wsa:EndpointReferenceType
</OriginatorReference> ?
<ErrorCode dialect="anyURI">xsd:anyType</ErrorCode> ?
<Description>xsd:string</Description> *
<FaultCause>{any}</FaultCause> ?
</BaseFault>
/wsrf-bf:BaseFault/Timestamp
This REQUIRED element MUST be the time at which the fault occurred. There MUST be only one timestamp element in BaseFault. In the absence of the time zone designation, the xsd:dateTime value MUST be interpreted as universal time (UTC) time.
/wsrf-bf:BaseFault/OriginatorReference
This OPTIONAL element is a WS-Addressing [WS-Addressing] EndpointReference of the Web service that generated the fault. This element MAY be omitted if the fault originator is clearly implied by the context in which the fault appears (for example in a simple request response message exchange). One use of this element is in a situation of nested faults.
/wsrf-bf:BaseFault/ErrorCode
This OPTIONAL element provides convenient support for legacy fault reporting systems (e.g., POSIX errno). The dialect attribute on ErrorCode MUST be a URI that defines the context in which the ErrorCode MUST be interpreted. For example, a URI might be defined that describes how a POSIX errno is mapped to a ErrorCode and that URI must appear on any ErrorCode element carrying a POSIX errno.
/wsrf-bf:BaseFault/Description
This OPTIONAL element contains a plain language description of the fault. This description is expected to be helpful in explaining the fault to users. There MAY be any number of description elements.
/wsrf-bf:BaseFault/FaultCause
This OPTIONAL element, if present, MUST contain a BaseFault or an element whose type extends the BaseFaultType that describes an underlying cause of this fault. The ability to include a FaultCause element in a fault allows for chaining of fault information so that a recipient of a fault MAY examine details underlying the cause of the fault.
Note that there is no required child element within BaseFault that identifies the particular type (or class) of fault. Rather, an application-specific extension of BaseFault MUST be defined for each distinct type of fault
/wsrf-bf:BaseFault/{any}
BaseFaultType includes open element extensibility. This provides a mechanism to add additional information to each specific type of BaseFault, if desired. The extensibility element is not intended to be used to distinguish between different reasons for a fault.
To define an extended fault, you MUST use XML Schema extension to extend the BaseFault type to include additional attributes and/or elements.
2.1 Example SOAP 1.1 Encoding of a Base Fault
The WS-Resource [WS-Resource] specification defines the ResourceUnknownFault BaseFault. The below shows a non-normative example SOAP 1.1 [SOAP 1.1] encoding of such a fault:
<s11:Envelope
xmlns="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsa=" http://www.w3.org/2005/08/addressing"
xmlns:wsrf-bf="http://docs.oasis-open.org/wsrf/bf-2"
xmlns:wsrf-r="http://docs.oasis-open.org/wsrf/r-2">
<s11:Header>
<wsa:Action>
http://docs.oasis-open.org/wsrf/fault
</wsa:Action>
…
<!-- other headers elided for clarity -->
</s11:Header>
<s11:Body>
<s11:Fault>
<faultcode>s11:Client</faultcode>
<faultstring>No such resource exists</faultstring>
<faultactor>http://example.org/someactor</faultactor>
<detail>
<wsrf-r:ResourceUnknownFault>
<wsrf-bf:Timestamp>
2005-05-04T20:18:44.970Z
</wsrf-bf:Timestamp>
<wsrf-bf:Description>
Resource unknown
</wsrf-bf:Description>
</wsrf-r:ResourceUnknownFault>
</detail>
</s11:Fault>
</s11:Body>
</s11:Envelope>
2.2 Example SOAP 1.2 Encoding of a Base Fault
The WS-Resource [WS-Resource] specification defines the ResourceUnknownFault BaseFault. The below shows a non-normative example SOAP 1.2 [SOAP 1.2] encoding of such a fault:
<s12:Envelope
xmlns="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:s12="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsrf-bf="http://docs.oasis-open.org/wsrf/bf-2"
xmlns:wsrf-r="http://docs.oasis-open.org/wsrf/r-2">
<s12:Header>
<wsa:Action>
http://docs.oasis-open.org/wsrf/fault
</wsa:Action>
…
<!-- other headers elided for clarity -->
</s12:Header>
<s12:Body>
<s12:Fault>
<Code>
<Value>s12:Sender</Value>
</Code>
<Reason>
<Text xml:lang="en">No such resource exists</Text>
</Reason>
<Detail>
<wsrf-r:ResourceUnknownFault>
<wsrf-bf:Timestamp>
2005-05-04T20:18:44.970Z
</wsrf-bf:Timestamp>
<wsrf-bf:Description>
Resource unknown
</wsrf-bf:Description>
</wsrf-r:ResourceUnknwnFault>
</Detail>
</s12:Fault>
</s12:Body>
</s12:Envelope>
3 Use of Base Faults in WSDL 1.1
Each distinct type of base fault associated with a WSDL [WSDL 1.1] operation SHOULD be listed as a separate fault response in the WSDL operation definition, as follows:
1. As described above, there MUST be a distinct XML Schema complexType that extends wsrf-bf:BaseFaultType, which represents this fault’s distinct type. This extended fault complexType MAY contain additional attributes and/or elements.
2. An element MUST be defined for this distinct fault, whose type is the complexType of the distinct fault as defined in step 1.
3. A WSDL message MUST be defined for this distinct fault. This message MUST have one part. The WSDL part MUST have an ‘element’ attribute and this MUST refer by QName to the element of this distinct fault as defined in step 2.
4. The WSDL operation MUST have a fault element for this distinct fault. The value of the WSDL fault element’s name attribute SHOULD be the same as the NCName of the fault element defined in step 2, although it MAY choose to ignore this rule (for example to avoid NCName collisions between fault elements defined in different namespaces). The value of the WSDL fault element’s message attribute MUST refer by QName to the WSDL message element of this distinct fault as defined in step 3.
In addition to any operation-specific faults, all WSDL operations MAY also have a WSDL fault element whose name attribute has the value “BaseFault” and whose message element has the value “wsrf-bf:BaseFaultMessage”.
The following non-normative example defines a portType named “pt” with a single operation named “op” that has two distinct faults, “hisFault” and “herFault”, in addition to a basic “baseFault”. The “hisFault” element does not extend “BaseFault” with any additional information (i.e. it just defines a distinct fault type with the base information), while the “herFault” element extends “BaseFault” with an additional details element.
…
<wsdl:definitions …>
<wsdl:types>
<xsd:schema …>
<!-- Type and element declarations for each distinct fault -->
<xsd:complexType name="HisFaultType">
<xsd:complexContent>
<xsd:extension base="wsrf-bf:BaseFaultType"/>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="hisFault" type="tns:HisFaultType"/>
<xsd:complexType name="HerFaultType">
<xsd:complexContent>
<xsd:extension base="wsrf-bf:BaseFaultType">
<xsd:sequence>
<xsd:element name="details" type="xsd:string"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="herFault" type="tns:HerFaultType"/>
</xsd:schema>
</wsdl:types>
<!-- WSDL messages for each distinct fault -->
<wsdl:message name="hisFaultMessage">
<wsdl:part name="fault" element="tns:hisFault"/>
</wsdl:message>
<wsdl:message name="herFaultMessage">
<wsdl:part name="fault" element="tns:herFault"/>
</wsdl:message>
<wsdl:portType name="pt">
<wsdl:operation name="op">
<!-- WSDL operation fault elements for each distinct fault -->
<wsdl:input … />
<wsdl:output … />
<wsdl:fault name="hisFault"
message="tns:hisFaultMessage"/>
<wsdl:fault name="herFault"
message="tns:herFaultMessage"/>
<wsdl:fault name="BaseFault"
message="wsrf-bf:BaseFaultMessage"/>
</wsdl:operation>
</wsdl:portType>
</wsdl:definitions>
A Web service MAY return a more refined fault in place of a particular fault that is defined by a WSDL operation. To do so, a complexType MUST be defined that extends one of the faults found in the WSDL operation. The fault message that is returned by the service MUST then use the element of the fault from which the more refined fault is derived with an xsi:type attribute whose value is the QName of the complexType for the more refined fault.
For example, if an implementation of the “pt” example above wants to return a more refined version hisFault for the “op” operation, it must define a complexType of hisFault such as:
…
targetNamespace="http://example.com/ExtendedFaults" …
<xsd:complexType name="ExtendedHisFaultType">
<xsd:complexContent>
<xsd:extension base="tns:HisFaultType">
<xsd:sequence>
<xsd:element name="otherDetails"
type="xsd:string"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
This example service can then return a fault message for the “op” operation such as:
<hisFault
xmlns:ef="http://example.com/ExtendedFaults"
xsi:type="ef:ExtendedHisFaultType">
<timeStamp>…</timeStamp>
…
<otherDetails>…</otherDetails>
</hisFault>
4 Security Considerations
Fault messages may contain sensitive information. Policies should be defined such that such sensitive content of fault messages are appropriately protected. For example, the security policy can be specified to require that the sensitive content be encrypted based on WS-Security [WS-Security]. Depending on the context in which the fault occurred, it may also be desireable that the integrity of the message be ensured. In such cases, the security policy can reflect this by specifying the need to digitally sign the resulting fault messages based on the WS-Security specification.
5 References
5.1 Normative References
[RFC2119]
S. Bradner, Key words for use in RFCs to Indicate Requirement
1650 Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March
1651 1997.
[WSDL 1.1]
http://www.w3.org/TR/xml-infoset/
[XML]
5.2 Non-Normative References
http://www.gridforum.org/documents/GFD.15.pdf
[SOAP 1.1]
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
[SOAP 1.2]
http://www.w3.org/TR/2003/REC-soap12-part1-20030624/
http://www.w3.org/TR/ws-addr-core/
http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html
http://docs.oasis-open.org/wsrf/wsrf-ws_resource-1.2-spec-os.pdf
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf
Special thanks to the Global Grid Forum’s Open Grid Services Infrastructure working group, which defined the OGSI v1.0 [OGSI] specification which was a large inspiration for the ideas expressed in this specification.
The following individuals were members of the committee during the development of this specification:
Mario Antonioletti (EPCC, The University of Edinburgh), Akhil Arora (Sun Microsystems), Tim Banks (IBM), Jeff Bohren (OpenNetwork), Fred Carter (AmberPoint), Martin Chapman (Oracle), Glen Daniels (Sonic Software), David De Roure (University of Southampton), Thomas Freund (IBM), John Fuller (Individual), Stephen Graham (IBM), Anish Karmarkar (Oracle), Hideharu Kato (Hitachi), David Levine (IBM), Paul Lipton (Computer Associates), Mark Little (Arjuna Technologies Limited), Lily Liu (WebMethods, Inc.), Tom Maguire (IBM), Susan Malaika (IBM), Mark Mc Keown (University of Manchester), David Martin (IBM), Samuel Meder (Argonne National Laboratory), Jeff Mischkinsky (Oracle), Roger Menday (Forschungszentrum Jülich GmbH), Bryan Murray (Hewlett-Packard), Mark Peel (Novell), Alain Regnier (Ricoh Company, Ltd.), Ian Robinson (IBM), Tom Rutt (Fujitsu), Mitsunori Satomi (Hitachi), Igor Sedukhin (Computer Associates), Hitoshi Sekine (Ricoh Company, Ltd.), Frank Siebenlist (Argonne National Laboratory), Alex Sim (Lawrence Berkeley National Laboratory), David Snelling (Fujitsu), Latha Srinivasan (Hewlett-Packard), Rich Thompson (IBM), Jem Treadwell (Hewlett-Packard), Steve Tuecke (Argonne National Laboratory), William Vambenepe (Hewlett-Packard), Katy Warr (IBM), Alan Weissberger (NEC Corporation), Pete Wenzel (SeeBeyond Technology Corporation), Kirk Wilson (Computer Associates) and Umit Yalcinalp (SAP).
|
Rev |
Date |
By Whom |
What |
|
wd-01 |
2004-06-02 |
Lily Liu, Sam Meder |
Initial version created from submission by contributing companies. Minor modifications made to reflect OASIS formatting. |
|
wd-02 |
2004-06-10 |
Sam Meder |
Consistency fixes from Ian Robinson Updated namespaces Cleaned up the references |
|
wd-02 |
2004-06-28 |
Lily Liu |
Namespace fixes in xsd and wsdl and minor format changes in the requirement section. |
|
wd-02 |
2004-06-30 |
Sam Meder |
Inserted updated schema and wsdl – adds elementFormDefault="qualified" attributeFormDefault="unqualified" attributes to schema declarations. |
|
wd-03 |
2004-11-11 |
Lily Liu |
Issue resolutions from October F2F: WSRF43 Updated the status section Updated document identifier, location and namespaces o Changed doc identifier to “Summary Info Title”
|
|
wd-04 |
2005-02-17 |
Lily Liu |
Issue resolutions from Jan F2F, 2005: Updated draft number and namespaces o Applied resolutions to issues 62, 81, 90, and 96.
|
|
wd-05 |
2005-05-17 |
Sam Meder |
Updated draft number and namespaces o Applied resolutions to issues 92, 99, 100, 106, 109, 110, 114 |
|
pr-01 |
2005-06-13 |
Sam Meder |
Changed status to PR |
|
pr-02 |
2005-10-07 |
Lily Liu |
PR draft 2 |
|
wd-07 |
2005-09-15 |
Bryan Murray |
Address Public Review comments
|
|
wd-08 |
2005-09-16 |
Bryan Murray |
Correct link to WS-Addressing spec |
|
wd-09 |
2005-09-16 |
Bryan Murray |
Move WS-I reference to non-normative |
|
pr-02.a |
2005-11-17 |
Lily Liu |
Accept all changes for PR draft 2 |
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification, can be obtained from the OASIS Executive Director.
OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.
Copyright © OASIS Open 2005. All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself does not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an “AS IS” basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.