Transcript WS-I BP1.0 Recommendations On WSDL1.1

WS-I BP1.0
Recommendations
On WSDL1.1
Kevin Liu
October 2003
Objectives
Provide background information for Issue 72
 What’s value of BP1.0 wrt BP1.0
 BP1.0 constraints on use of WSDL1.1
 BP1.0 clarifications on use of WSDL1.1
 Conformance to BP1.0
 Impacts on BPEL - discussion
 SAP AG 2002, Title of Presentation, Speaker Name / 2
Background: WSDL1.1 Basics
*
part
message
*
0..1
0..1
output
input
portType
 A portType describes the
abstract interface of the Web
service
fault
* **
*
operation
*
1
*
1
How
Where
*
 SAP AG 2002, Title of Presentation, Speaker Name / 3
 Each contained operation can
have an input, an output and a
number of fault messages
A binding specifies exactly one
protocol for the operations of a
portType
binding
service
What
*
port
A port defines the Web service
endpoint by specifying a single
network address
Where
how
What
Background: WSDL 1.1 – A simplified Example
<definitions name="StockQuote“ …>
<types>
<schema ...> <complexType name="TimePeriod">
XML Schema
<element name="startTime" type="xsd:timeInstant"/> ...
</complexType> </schema>
</types>
<message name="GetTradePricesInput">
<part name="tickerSymbol" type="xsd:string"/> ...
</message> ...
<portType name="StockQuotePortType">
<operation name="GetLastTradePrice">
<input message="tns:GetTradePricesInput"/>
<output message="tns:GetTradePricesOutput"/>
</operation>
</portType>
<binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="GetTradePrices"> <soap:operation soapAction="..."/>
<input> <soap:body use="encoded" ... encodingStyle="..."/> </input> ...
</operation>
</binding>
<service name="StockQuoteService">
<port name="StockQuotePort" binding="tns:StockQuoteBinding">
<soap:address location="http://example.com/stockquote"/>
</port>
</service>
</definitions>
 SAP AG 2002, Title of Presentation, Speaker Name / 4
What’s the value of BP1.0 wrt WSDL1.1?
BP1.0 aims at interoperability
 It’s the result of resolving 344 interoperability issues reported by 100+ WS-I
members
 It provides 161 recommendations about using its selected specifications,
majority focuses on the use of WSDL1.1
WSDL1.1 contains many errors, ambiguities, and inconsistencies (among
the spec text, examples, and schemas)
 BP1.0 provides clarifications, correction, examples and guidance to improve
the usability and interoperability of WSDL1.1
WSDL1.1 allows multiple mechanisms to do same thing while many of
the mechanisms are underspecified and causes interoperability
problems. BP1.0 recommends the mostly adopted mechanism
 XML schema as type system + soap over http as binding
BP1.0 contains 72 recommendations on WSDL1.1 (details to follow)
 Constraints
 Guidance
 SAP AG 2002, Title of Presentation, Speaker Name / 5
BP1.0 Constraints on Web services description
BP1.0 assigns WSDL1.1 as one of the mandatory mechanisms for
describing a Web Service
 A service must be described using WSDL, UDDI, or both
BP1.0 constraints on use of WSDL1.1




XML1.0 is mandated for WSDL definitions
XML schema is the only conformant type system
SOAP over HTTP is the only conformant binding
Disallow operation overloading - operation name must be unique
within a portType
 Disallow out-bound operations
 Disallows (soap) encoding

No @use=“encoded” in wsdl bindings

No @encodingStyle in soap messages
 SAP AG 2002, Title of Presentation, Speaker Name / 6
BP1.0 Clarifications on WSDL1.1
BP1.0 provides clarifications and guidance on the use of the
following WSDL1.1 (details to follow)
 Dedicated schema files
 Ordering of top WSDL1.1 elements




wsdl:import vs. xsd:import
wsdl:part@type vs. @element
XML namespaces
Faults description
 Use of RPC style
 SAP AG 2002, Title of Presentation, Speaker Name / 7
Which WSDL1.1 schema files to use?
WSDL1.1 schemas in the appendix of the spec is out of date, and
inconsistent with the spec in many cases
Earlier experimental projects have provided updates to the schemas. WSI has made a snapshot of the updated schemas available in the following
URIs
 WSDL schema:


http://schemas.xmlsoap.org/wsdl/2003-02-11.xsd
Note this schema allows extension to portType
 SOAP Binding schema:

http://schemas.xmlsoap.org/wsdl/soap/2003-02-11.xsd
A WSDL1.1 definition must be valid with the above schemas to claim
BP1.0 conformant
Who is responsible for validating WSDL1.1 definition against the above
schemas?
 It’s the responsibility of the WSDL author to assure it’s schema validated
 Consumers of the WSDL may be more tolerant if they choose to
 SAP AG 2002, Title of Presentation, Speaker Name / 8
Order of WSDL elements
WSDL1.1 spec and its appended WSDL1.1 schema are
inconsistent about what are the appropriate order of the top
WSDL1.1 elements
BP1.0 provides the following guidance:
 If present, the wsdl:import element must precede all other wsdl
elements except wsdl:documentation
 If present, wsdl:type must precede all other elements except
wsdl:documentation and wsdl:import
 The order of all other elements are not important, but in general it
should be in the following order







documentation
import
types
message
portType
binding
service
 SAP AG 2002, Title of Presentation, Speaker Name / 9
wsdl:import vs. xsd:import
WSDL1.1 uses import mechanism to allow flexible authoring
 Different sections of a WSDL definition can be defined in separate
files and then imported into another WSDL file
 wsdl:import is modeled after xsd:import, but the WSDL1.1 spec
doesn’t provide any explanation about how it should be used

It’s interpreted differently by different vendor and causes interoperability
problems
BP1.0 provides the following guidance:
 wsdl:import can only be used to import other wsdl files

The imported definition can either in the same namespace, or in a
different namespace than the importing definition
 Namespace coercion is disallowed. The imported wsdl must be
referenced with the same namespace as defined by its targetNamespace
 The location attribute is required and so must not be empty, but its value
should only be treated as a hint to the wsdl processor
 xsd:import can only be used to import XML schema definitions

It can only be used in the <types> section
 It should follow the same rules as specified in xml schema
 SAP AG 2002, Title of Presentation, Speaker Name / 10
Example – wsdl:import vs xsd:import
<definitions ... xmlns:wsdl =“http://schemas.xmlsoap.org/wsdl/”
xmlns:test1 = “http://example.com/stockquote/test1”
xmlns:test2 = “http://example.com/stockquote/test2”>
<wsdl:import namespace=“http://example.com/stockquote/test1”
location="http://example.com/stockquote/stockquote.wsdl"/>
<wsdl:types>
<xsd:schema … xmlns:xsd ="http://www.w3.org/2001/XMLSchema">
<xsd:import namespace=“http://example.com/stockquote/test2”
schemaLocation="http://example.com/stockquote/stockquote.xsd"/>
</xsd:schema>
</wsd:types>
…
</definitions>
 SAP AG 2002, Title of Presentation, Speaker Name / 11
wsdl:part@element vs. wsdl:part@type
WSDL:part has two exclusive attributes – element or type
 One can use the “element” attribute to reference an XSD global element. e.g.
<message name="GetTradePricesInput">
<part name=“purchaseOrder" element=“tns:purchaseOrder"/> ...
</message>
 Or use “type” to reference an XSD simple or complex type. E.g.
<message name="GetTradePricesInput">
<part name="tickerSymbol" type="xsd:string"/> ...
</message>
 The choice of “type” vs “element” has significant impact on soap binding definition, and
in turn on the soap message
wsdl:part
attribute
Allowed XSD
Definition
Allowed SOAP
Binding Style
Impact on SOAP Message
type
XSD simple or
complex types
RPC
The xsd type will be used as
the type of the child of a part
accessor which gets its name
from wsdl:part@name
element
XSD global element
declaration
document
the xsd element defines the
child of soap:body
 SAP AG 2002, Title of Presentation, Speaker Name / 12
How to handle fault?
Do you have to specify all faults in your WSDL? NO
 A WSDL should, but not required to, include all known faults
 Soap faults can appear as body fault or header fault
What is the “style” of soapbind:fault or soapbind:headerfault?
 “RPC” is only appliable to soapbind:body
 Headers, headerfaults, and faults are always “document” style
 They can only refer to a wsdl:part that has been defined using the
“element” attribute
What are the right fault code to use?
 “VersionMismatch”, and “MustUnderstand” should be first checked
 If the recipient receives a soap message that is inconsistent with its
WSDL, it should generate a soap:Fault with a fault code of “Client”
 SAP AG 2002, Title of Presentation, Speaker Name / 13
Use of xml namespaces
<xsd:schema> contained in the <wsdl:types> must have a target namespace
attribute with a valid and non-null value
 One exception: when xsd:import is its only child
The targetNamespace of a WSDL definition and the targetNamespace of its
contained schema maybe the same – they are in different symbol spaces
 SAP AG 2002, Title of Presentation, Speaker Name / 14
When do you need to provide a namespace for soap
binding element?
Selected
soap
binding
style
Does it have to provide a
How does it impact the soap
value for
message?
soapbind:body@namespace?
Document- No
Literal
In the wire message, the
serialized element child of
(note
soap:body gets its namespace
soapbind:header/headerfault/fault from its xsd element definition
are always document style)
RPCLiteral
Yes
1. Operation wrapper element :
the wire message use the
provided value as its
namespace
2. part accessors and return
values must be placed
under no namespace
3. Children of part accessor
must be namespace
qualified and get their ns
value from its xsd definition
 SAP AG 2002, Title of Presentation, Speaker Name / 15
Use of RPC style
Many of BP1.0 recommendations are related to the use of RPC
style
 Already covered some in the slides for part@type use and
namespace use
 Example follows
 SAP AG 2002, Title of Presentation, Speaker Name / 16
Example - A RPC style WSDL1.1 definition
the case of RPC, the resulting soap message is
<definitions … targetNamespace =“http://example.org/bar/”Inxmlns:foo=“http://example.org/foo/”
described as a mix of wsdl constructs and xsd constructs.
xmlns:bar=“http://example.org/bar/” >
<types>
<xsd:schema targetNamespace="http://example.org/foo/" xmlns:tns="http://example.org/foo/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified“
attributeFormDefault="unqualified">
<xsd:complexType name="fooType">
<xsd:sequence>
<xsd:element ref="tns:bar"/>
<xsd:element ref="tns:baf"/>
</xsd:sequence>
used as the definition of part accessor children
</xsd:complexType>
<xsd:element name="bar" type="xsd:string"/>
<xsd:element name="baf" type="xsd:integer"/>
</xsd:schema>
</types>
used as the name of the part accessor
<message name="BarMsg">
<part name="BarAccessor" type="foo:fooType"/>
</message>
used as the name of the operation wrapper
<portType name="BarPortType">
<operation name="BarOperation">
<input message="bar:BarMsg"/>
</operation>
</portType>

<binding name="BarSOAPBinding" type="bar:BarPortType">
<soapbind:binding transport="http://schemas.xmlsoap.org/soap/http/" style="rpc"/>
<operation name="BarOperation">
<input message="bar:BarMsg">
<soapbind:body use="literal" namespace="http://example.org/bar/"/>
</input>
used as the namespace of the operation wrapper
</operation>
SAP AG 2002, Title of Presentation,
Speaker Name / 17
Example – the resulting soap message
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:foo="http://example.org/foo/">
<s:Header/>
Operation wrapper has the same name of the wsdl:operation, and
it takes the ns value from soapbind:body@namespace in its wsdl
definition
<s:Body>
<m:BarOperation xmlns:m="http://example.org/bar/">
<BarAccessor>
<foo:bar>String</foo:bar>
<foo:baf>0</foo:baf>
</BarAccessor>
</m:BarOperation>
</s:Body>
Children of part accessor have their namespace from their schema
definition
</s:Envelope>
Part accessor has the same name as the wsdl:part@name, and it
must not have any namespace
 SAP AG 2002, Title of Presentation, Speaker Name / 18
Conformance to BP1.0
BP1.0 has a well-defined scope which is decided by its underlying
specifications.
 Conformance is only relevant within its
 BP1.0 covers WSDL1.1, SOAP1.1, UDDI 2.0 and a few other related specs
BP1.0 conformance is based on three kinds of artifacts




MESSAGE – the soap message
DESCRIPTION – the wsdl definition
REGDATA – the uddi registry elements
A conformant artifact has to meet all requirements targeted for that artifact
For DESCRIPTION, conformance can be claimed for the following
elements of WSDL1.1
 Port
 Binding
 portType


Operation
Message
Conformance is not about the overall WSDL definition. e.g. A WSDL
definition may contain a conformant binding and multiple nonconformant bindings
 SAP AG 2002, Title of Presentation, Speaker Name / 19
How can I claim conformance to BP1.0?
WS-I provides testing tools which can be used to check
conformance of a target artifact, such as a SOAP message
WS-I defines a schema for wsi:Claim element which can be used
to advertise conformance to a profile in different ways
 WSDL top elements( e.g. wsdl:port, wsdl:binding, etc)
 SOAP message header
 UDDI tModel
For Example,
<wsdl:service name="MyService" >
 <wsdl:port name="MyPort" binding="tns:MyBinding" >

<wsdl:documentation>

<wsi:Claim conformsTo="http://ws-i.org/profiles/basic/1.0" />
</wsdl:documentation>

<soapbind:address location="http://example.org/myservice/myport" />
 </wsdl:port>
</wsdl:service>
 SAP AG 2002, Title of Presentation, Speaker Name / 20
Discussion – BP1.0 Impact On WSDL1.1
BP1.0 provides many valuable clarifications on use of WSDL1.1.
These clarifications should be reflected in all WSDL examples in
BPEL spec
The following BP1.0 constraints affect portType definitions and
should be considered for BPEL
 XML1.0 is mandated for WSDL definitions - OK
 XML schema is the only conformant type system - OK
 Disallow operation overloading - operation name must be unique
within a portType – should be enforced
 Disallow out-bound operations – OK
The following constraints are for bindings, there is no direct
conflicts with BPEL
 SOAP over HTTP is the only conformant binding –OK, we only
provide conformant portType definition, bindings are up to the
services implementers.
 Disallows (soap) encoding – OK, same as above
 SAP AG 2002, Title of Presentation, Speaker Name / 21