ws-i bp1.0 recommendations on wsdl1.1

WS-I BP1.0 Recommendations On WSDL1.1

Kevin Liu

October 2003

SAP AG 2002, Title of Presentation, Speaker Name / 2

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


Background: WSDL1.1 Basics

What A portType describes the

abstract interface of the Web service

Each contained operation can have an input, an output and a number of fault messages

message

portType operation*

input

0..1

*

output0..1

*

fault

*

*

binding

1

*

service port*

*

1

*

HowA binding specifies exactly one protocol for the operations of a portType

WhereA port defines the Web service endpoint by specifying a single network address

part*


Background: WSDL 1.1 – A simplified Example

<definitions name="StockQuote“ …> <types> <schema ...> <complexType name="TimePeriod"> <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>

Wh

at

how

XML Schema

Wh

ere


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


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


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


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. WS-I 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


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


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


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>

<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>


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


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”


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


When do you need to provide a namespace for soap binding element?

Selected soap

binding style

Does it have to provide a value for

soapbind:body@namespace?

How does it impact the soap message?

Document- Literal

No

(note soapbind:header/headerfault/fault are always document style)

In the wire message, the serialized element child of soap:body gets its namespace from its xsd element definition

RPC- Literal

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


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


Example - A RPC style WSDL1.1 definition<definitions … targetNamespace =“http://example.org/bar/” xmlns:foo=“http://example.org/foo/” 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> </xsd:complexType> <xsd:element name="bar" type="xsd:string"/> <xsd:element name="baf" type="xsd:integer"/>

</xsd:schema> </types>

<message name="BarMsg"> <part name="BarAccessor" type="foo:fooType"/>

</message>

<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> </operation>

</binding>

<definitions … targetNamespace =“http://example.org/bar/” xmlns:foo=“http://example.org/foo/” 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> </xsd:complexType> <xsd:element name="bar" type="xsd:string"/> <xsd:element name="baf" type="xsd:integer"/>

</xsd:schema> </types>

<message name="BarMsg"> <part name="BarAccessor" type="foo:fooType"/>

</message>

<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> </operation>

</binding>

In the case of RPC, the resulting soap message is described as a mix of wsdl constructs and xsd constructs.

used as the name of the operation wrapper

used as the name of the part accessor

used as the namespace of the operation wrapper

used as the definition of part accessor children


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/>

<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>

</s:Envelope>

<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/>

<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>

</s:Envelope>

Operation wrapper has the same name of the wsdl:operation, and it takes the ns value from soapbind:body@namespace in its wsdl definition

Part accessor has the same name as the wsdl:part@name, and it must not have any namespace

Children of part accessor have their namespace from their schema definition


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 non-conformant bindings


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>


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

ws-i bp1.0 recommendations on wsdl1.1

Documents

title of presentation

wsdl definitionregdata

wsdl examples

wsdl definitionpart

use of wsdl1

overall wsdl definition

wrt bp1

discussion bp1