Chapter 1. XML Web Service Standards

Given XML documents, schemas, and fragments determine whether their syntax and form are correct (according to W3C schema) and whether they conform to the WS-I Basic Profile 1.1.

[Note]

Basic Profile. SOAP Envelopes

An ENVELOPE MUST conform to the structure specified in SOAP 1.1 Section 4, "SOAP Envelope"

An ENVELOPE MUST have exactly zero or one child elements of the soap:Body element.

A RECEIVER MUST generate a fault if they encounter an envelope whose document element is not soap:Envelope.

The children of the soap:Body element in an ENVELOPE MUST be namespace qualified.

An ENVELOPE MUST NOT contain a Document Type Declaration.

An ENVELOPE MUST NOT contain Processing Instructions.

An ENVELOPE SHOULD NOT contain the namespace declaration xmlns:xml="http://www.w3.org/XML/1998/namespace".

A DESCRIPTION SHOULD NOT contain the namespace declaration xmlns:xml="http://www.w3.org/XML/1998/namespace".

An ENVELOPE MUST NOT have any element children of soap:Envelope following the soap:Body element.

CORRECT example:

					
<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >
  <soap:Body>
    <p:Process xmlns:p='http://example.org/Operations' >
      <m:Data xmlns:m='http://example.org/information' >
        Here is some data with the message
      </m:Data>
    </p:Process>
  </soap:Body>
</soap:Envelope>

					

INCORRECT example:


<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >
  <soap:Body>
    <p:Process xmlns:p='http://example.org/Operations' />
  </soap:Body>
  <m:Data xmlns:m='http://example.org/information' >
    Here is some data with the message
  </m:Data>
</soap:Envelope>

					

An ENVELOPE MUST NOT contain soap:encodingStyle attributes on any of the elements whose namespace name is "http://schemas.xmlsoap.org/soap/envelope/".

An ENVELOPE MUST NOT contain soap:encodingStyle attributes on any element that is a child of soap:Body.

An ENVELOPE described in an rpc-literal binding MUST NOT contain soap:encodingStyle attribute on any element that is a grandchild of soap:Body.

An ENVELOPE containing a soap:mustUnderstand attribute MUST only use the lexical forms "0" and "1".

A RECEIVER MUST NOT mandate the use of the xsi:type attribute in envelopes except as required in order to indicate a derived type (see XML Schema Part 1: Structures, Section 2.6.1).

The soap:Envelope, soap:Header, and soap:Body elements in an ENVELOPE MUST NOT have attributes in the namespace "http://schemas.xmlsoap.org/soap/envelope/".

Basic Profile. SOAP Processing Model

A RECEIVER MUST handle envelopes in such a way that it appears that all checking of mandatory header blocks is performed before any actual processing.

A RECEIVER MUST generate a "soap:MustUnderstand" fault when an envelope contains a mandatory header block (i.e., one that has a soap:mustUnderstand attribute with the value "1") targeted at the receiver (via soap:actor) that the receiver does not understand.

When a fault is generated by a RECEIVER, further processing SHOULD NOT be performed on the SOAP envelope aside from that which is necessary to rollback, or compensate for, any effects of processing the envelope prior to the generation of the fault.

Where the normal outcome of processing a SOAP envelope would have resulted in the transmission of a SOAP response, but rather a fault is generated instead, a RECEIVER MUST transmit a fault in place of the response.

A RECEIVER that generates a fault SHOULD notify the end user that a fault has been generated when practical, by whatever means is deemed appropriate to the circumstance.

Basic Profile. SOAP Faults

A RECEIVER MUST interpret a SOAP message as a Fault when the soap:Body of the message has a single soap:Fault child.

When an ENVELOPE is a Fault, the soap:Fault element MUST NOT have element children other than faultcode, faultstring, faultactor and detail.

CORRECT example:


<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >
  <faultcode>soap:Client</faultcode>
  <faultstring>Invalid message format</faultstring>
  <faultactor>http://example.org/someactor</faultactor>
  <detail>
    <m:msg xmlns:m='http://example.org/faults/exceptions'>
      There were <b>lots</b> of elements in 
      the message that I did not understand
    </m:msg>
    <m:Exception xmlns:m='http://example.org/faults/exceptions'>
      <m:ExceptionType>Severe</m:ExceptionType>
    </m:Exception>
  </detail>
</soap:Fault>
					
					

INCORRECT example:


<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >
  <faultcode>soap:Client</faultcode>
  <faultstring>Invalid message format</faultstring>
  <faultactor>http://example.org/someactor</faultactor>
  <detail>
    There were <b>lots</b> of elements in the message 
    that I did not understand
  </detail>
  <m:Exception xmlns:m='http://example.org/faults/exceptions' >
    <m:ExceptionType>Severe</m:ExceptionType>
  </m:Exception>
</soap:Fault>
					
					

When an ENVELOPE is a Fault, the element children of the soap:Fault element MUST be unqualified.

CORRECT example:


<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns='' >
  <faultcode>soap:Client</faultcode>
  <faultstring>Invalid message format</faultstring>
  <faultactor>http://example.org/someactor</faultactor>
  <detail>
    <m:msg xmlns:m='http://example.org/faults/exceptions'>
      There were <b>lots</b> of elements in the message that 
      I did not understand
    </m:msg>
  </detail>
</soap:Fault>
					
					

INCORRECT example (children of the soap:Fault elements have namespace qualification):


<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >
  <soap:faultcode>soap:Client</soap:faultcode>
  <soap:faultstring>Invalid message format</soap:faultstring>
  <soap:faultactor>http://example.org/someactor</soap:faultactor>
  <soap:detail>
    <m:msg xmlns:m='http://example.org/faults/exceptions'>
      There were <b>lots</b> of elements in the message that 
      I did not understand
    </m:msg>
  </soap:detail>
</soap:Fault>
					
					

A RECEIVER MUST accept faults that have any number of elements, including zero, appearing as children of the detail element. Such children can be qualified OR unqualified.

A RECEIVER MUST accept faults that have any number of qualified OR unqualified attributes, including zero, appearing on the detail element. The namespace of qualified attributes can be anything other than "http://schemas.xmlsoap.org/soap/envelope/".

A RECEIVER MUST accept faults that carry an xml:lang attribute on the faultstring element.

When an ENVELOPE contains a faultcode element, the content of that element SHOULD be either one of the fault codes defined in SOAP 1.1 (supplying additional information if necessary in the detail element), or a Qname whose namespace is controlled by the fault's specifying authority (in that order of preference).

NOTE: The set of faultcode values defined in SOAP 1.1 document is: VersionMismatch, MustUnderstand, Client, Server.

When an ENVELOPE contains a faultcode element the content of that element SHOULD NOT use of the SOAP 1.1 "dot" notation to refine the meaning of the fault.

CORRECT example:


<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
            xmlns:c='http://example.org/faultcodes' >
  <faultcode>c:ProcessingError</faultcode>
  <faultstring>An error occured while processing the message</faultstring>
</soap:Fault>

					

CORRECT example:


<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >
  <faultcode>soap:Server</faultcode>
  <faultstring>An error occured while processing the message</faultstring>
</soap:Fault>

					

INCORRECT example:


<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
            xmlns:c='http://example.org/faultcodes' >
  <faultcode>soap:Server.ProcessingError</faultcode>
  <faultstring>An error occurred while processing the message</faultstring>
</soap:Fault>

					

Basic Profile. Use of SOAP in HTTP

A MESSAGE MUST be sent using either HTTP/1.1 or HTTP/1.0.

A MESSAGE SHOULD be sent using HTTP/1.1.

A HTTP request MESSAGE MUST use the HTTP POST method.

A MESSAGE MUST NOT use the HTTP Extension Framework (RFC2774).

The value of the SOAPAction HTTP header field in a HTTP request MESSAGE MUST be a quoted string.

A RECEIVER MAY respond with a fault if the value of the SOAPAction HTTP header field in a message is not quoted.

A RECEIVER MUST NOT rely on the value of the SOAPAction HTTP header to correctly process the message.

CORRECT example #1:

A WSDL Description that has:


<soapbind:operation soapAction="foo" />
					
					
results in a message with a SOAPAction HTTP header field of:
SOAPAction: "foo"
					

CORRECT example #2:

A WSDL Description that has:


<soapbind:operation />
					
					
or

<soapbind:operation soapAction="" />
					
					
results in a message with a corresponding SOAPAction HTTP header field as follows:
SOAPAction: ""					
					

An INSTANCE MUST use a 2xx HTTP status code on a response message that indicates the successful outcome of a HTTP request.

An INSTANCE SHOULD use a "200 OK" HTTP status code on a response message that contains an envelope that is not a fault.

Basic Profile. Service Description. Document Structure

A DESCRIPTION MUST only use the WSDL "import" statement to import another WSDL description.

In a DESCRIPTION, the namespace attribute of the wsdl:import MUST NOT be a relative URI.

To import XML Schema Definitions, a DESCRIPTION MUST use the XML Schema "import" statement.

A DESCRIPTION MUST use the XML Schema "import" statement only within the xsd:schema element of the types section.

In a DESCRIPTION the schemaLocation attribute of an xsd:import element MUST NOT resolve to any document whose root element is not "schema" from the namespace "http://www.w3.org/2001/XMLSchema".

CORRECT description example:

					
<definitions name="StockQuote"
   targetNamespace="http://example.com/stockquote/definitions"
           	 ...
   xmlns="http://schemas.xmlsoap.org/wsdl/">
   
   <import namespace="http://example.com/stockquote/definitions"
           location="http://example.com/stockquote/stockquote.wsdl"/>
           
   <message name="GetLastTradePriceInput">
      <part name="body" element="..."/>
   </message>
                  ...
   </definitions>

					

CORRECT description example:


<definitions name="StockQuote"  
   targetNamespace="http://example.com/stockquote/"
   xmlns:xsd1="http://example.com/stockquote/schemas"
           	 ...
   xmlns="http://schemas.xmlsoap.org/wsdl/">
   
   <import namespace="http://example.com/stockquote/definitions"
        location="http://example.com/stockquote/stockquote.wsdl"/>
           
   <message name="GetLastTradePriceInput">
      <part name="body" element="xsd1:TradePriceRequest"/>
   </message>
               ...
</definitions>

					

INCORRECT description example (imports not "wsdl" document):


<definitions name="StockQuote"
   targetNamespace="http://example.com/stockquote/definitions"
   xmlns:xsd1="http://example.com/stockquote/schemas"
           	 ...
   xmlns="http://schemas.xmlsoap.org/wsdl/">

   <import namespace="http://example.com/stockquote/schemas"
           location="http://example.com/stockquote/stockquote.xsd"/>
         
   <message name="GetLastTradePriceInput">
        <part name="body" element="xsd1:TradePriceRequest"/>
    </message>
               ...
</definitions>

					

A DESCRIPTION MUST specify a non-empty location attribute on the wsdl:import element.

When they appear in a DESCRIPTION, wsdl:import elements MUST precede all other elements from the WSDL namespace except wsdl:documentation.

When they appear in a DESCRIPTION, wsdl:types elements MUST precede all other elements from the WSDL namespace except wsdl:documentation and wsdl:import.

CORRECT example:


<definitions name="StockQuote" targetNamespace="http://example.com/stockquote/definitions">

    <import namespace="http://example.com/stockquote/base"
        location="http://example.com/stockquote/stockquote.wsdl"/>
        
    <message name="GetLastTradePriceInput">
        <part name="body" element="..."/>
    </message>
                  ...
</definitions>

					

CORRECT example:


<definitions name="StockQuote"  
           	 ...
   xmlns="http://schemas.xmlsoap.org/wsdl/">

   <types>
      <schema targetNamespace="http://example.com/stockquote/schemas"
          xmlns="http://www.w3.org/2001/XMLSchema">
           .......
      </schema>
   </types>
           
   <message name="GetLastTradePriceInput">
      <part name="body" element="tns:TradePriceRequest"/>
   </message>
               ...
   <service name="StockQuoteService">
      <port name="StockQuotePort" binding="tns:StockQuoteSoap">
           ....
      </port>
   </service>
</definitions>

					

INCORRECT example (wsdl:types elements MUST precede all other elements):


<definitions name="StockQuote"  
           	 ...
   xmlns="http://schemas.xmlsoap.org/wsdl/">
   
   <import namespace="http://example.com/stockquote/definitions"
         location="http://example.com/stockquote/stockquote.wsdl"/>
           
   <message name="GetLastTradePriceInput">
      <part name="body" type="tns:TradePriceRequest"/>
   </message>
               ...
   <service name="StockQuoteService">
      <port name="StockQuotePort" binding="tns:StockQuoteSoap">
           ....
      </port>
   </service>

   <types>
      <schema targetNamespace="http://example.com/stockquote/schemas"
               xmlns="http://www.w3.org/2001/XMLSchema">
           .......
      </schema>
   </types>
</definitions>

					

Basic Profile. Service Description. Types

A DESCRIPTION MUST NOT use QName references to WSDL components in namespaces that have been neither imported, nor defined in the referring WSDL document.

A QName reference to a Schema component in a DESCRIPTION MUST use the namespace defined in the targetNamespace attribute on the xsd:schema element, or to a namespace defined in the namespace attribute on an xsd:import element within the xsd:schema element.

In a DESCRIPTION, declarations MUST NOT extend or restrict the soapenc:Array type.

In a DESCRIPTION, declarations MUST NOT use wsdl:arrayType attribute in the type declaration.

In a DESCRIPTION, elements SHOULD NOT be named using the convention ArrayOfXXX.

An ENVELOPE MUST NOT include the soapenc:arrayType attribute.

CORRECT example:

Given the WSDL Description:


<xsd:element name="MyArray1" type="tns:MyArray1Type"/>
<xsd:complexType name="MyArray1Type">
  <xsd:sequence>
    <xsd:element name="x" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
  </xsd:sequence>
</xsd:complexType>

					
The envelope would serialize as (omitting namespace declarations for clarity):

<MyArray1>
  <x>abcd</x>
  <x>efgh</x>
</MyArray1>
					
					

INCORRECT example:

Given the WSDL Description:


<xsd:element name="MyArray2" type="tns:MyArray2Type"/>
<xsd:complexType name="MyArray2Type" 
  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" >
  <xsd:complexContent>
    <xsd:restriction base="soapenc:Array">
      <xsd:sequence>
        <xsd:element name="x" type="xsd:string" 
           minOccurs="0" maxOccurs="unbounded"/>
      </xsd:sequence>
      <xsd:attribute ref="soapenc:arrayType" 
          wsdl:arrayType="tns:MyArray2Type[]"/>
    </xsd:restriction>
  </xsd:complexContent>
</xsd:complexType>
					
					
The envelope would serialize as (omitting namespace declarations for clarity):

<MyArray2 soapenc:arrayType="tns:MyArray2Type[]" >
  <x>abcd</x>
  <x>efgh</x>
</MyArray2>
					
					

.........................

Professional hosting     Belorussian informational portal         Free SCWCD 1.4 Study Guide     Free SCDJWS 1.4 Study Guide     SCDJWS 1.4 Quiz     Free IBM Certified Associate Developer Study Guide     IBM Test 000-287. Enterprise Application Development with IBM WebSphere Studio, V5.0 Study Guide     SCDJWS 5.0 Quiz