WSI BP 1 0 Recommendations On WSDL 1

WS-I BP 1. 0 Recommendations On WSDL 1. 1 Kevin Liu October 2003

Objectives Provide background information for Issue 72 n n n ã What’s value of BP 1. 0 wrt BP 1. 0 constraints on use of WSDL 1. 1 BP 1. 0 clarifications on use of WSDL 1. 1 Conformance to BP 1. 0 Impacts on BPEL - discussion SAP AG 2002, Title of Presentation, Speaker Name / 2

Background: WSDL 1. 1 Basics * message * 0. . 1 input part output port. Type fault * ** * operation * 1 SAP AG 2002, Title of Presentation, Speaker Name / 3 How Where * ã n A port. Type describes the abstract interface of the Web service n 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 port. Type 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="Stock. Quote“ …> <types> <schema. . . > <complex. Type name="Time. Period"> XML Schema <element name="start. Time" type="xsd: time. Instant"/>. . . </complex. Type> </schema> </types> <message name="Get. Trade. Prices. Input"> <part name="ticker. Symbol" type="xsd: string"/>. . . </message>. . . <port. Type name="Stock. Quote. Port. Type"> <operation name="Get. Last. Trade. Price"> <input message="tns: Get. Trade. Prices. Input"/> <output message="tns: Get. Trade. Prices. Output"/> </operation> </port. Type> <binding name="Stock. Quote. Soap. Binding" type="tns: Stock. Quote. Port. Type"> <soap: binding style="rpc" transport="http: //schemas. xmlsoap. org/soap/http"/> <operation name="Get. Trade. Prices"> <soap: operation soap. Action=". . . "/> <input> <soap: body use="encoded". . . encoding. Style=". . . "/> </input>. . . </operation> </binding> <service name="Stock. Quote. Service"> <port name="Stock. Quote. Port" binding="tns: Stock. Quote. Binding"> <soap: address location="http: //example. com/stockquote"/> </port> </service> </definitions> SAP AG 2002, Title of Presentation, Speaker Name / 4

What’s the value of BP 1. 0 wrt WSDL 1. 1? BP 1. 0 aims at interoperability n It’s the result of resolving 344 interoperability issues reported by 100+ WS-I members n It provides 161 recommendations about using its selected specifications, majority focuses on the use of WSDL 1. 1 contains many errors, ambiguities, and inconsistencies (among the spec text, examples, and schemas) n BP 1. 0 provides clarifications, correction, examples and guidance to improve the usability and interoperability of WSDL 1. 1 allows multiple mechanisms to do same thing while many of the mechanisms are underspecified and causes interoperability problems. BP 1. 0 recommends the mostly adopted mechanism n XML schema as type system + soap over http as binding BP 1. 0 contains 72 recommendations on WSDL 1. 1 (details to follow) n Constraints n Guidance ã SAP AG 2002, Title of Presentation, Speaker Name / 5

BP 1. 0 Constraints on Web services description BP 1. 0 assigns WSDL 1. 1 as one of the mandatory mechanisms for describing a Web Service n A service must be described using WSDL, UDDI, or both BP 1. 0 constraints on use of WSDL 1. 1 n n XML 1. 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 port. Type n Disallow out-bound operations n Disallows (soap) encoding No @use=“encoded” in wsdl bindings u No @encoding. Style in soap messages u ã SAP AG 2002, Title of Presentation, Speaker Name / 6

BP 1. 0 Clarifications on WSDL 1. 1 BP 1. 0 provides clarifications and guidance on the use of the following WSDL 1. 1 (details to follow) n n n n ã Dedicated schema files Ordering of top WSDL 1. 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 WSDL 1. 1 schema files to use? WSDL 1. 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 n WSDL schema: u http: //schemas. xmlsoap. org/wsdl/2003 -02 -11. xsd u Note this schema allows extension to port. Type n SOAP Binding schema: u http: //schemas. xmlsoap. org/wsdl/soap/2003 -02 -11. xsd A WSDL 1. 1 definition must be valid with the above schemas to claim BP 1. 0 conformant Who is responsible for validating WSDL 1. 1 definition against the above schemas? n It’s the responsibility of the WSDL author to assure it’s schema validated n 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 WSDL 1. 1 spec and its appended WSDL 1. 1 schema are inconsistent about what are the appropriate order of the top WSDL 1. 1 elements BP 1. 0 provides the following guidance: n If present, the wsdl: import element must precede all other wsdl elements except wsdl: documentation n If present, wsdl: type must precede all other elements except wsdl: documentation and wsdl: import n The order of all other elements are not important, but in general it should be in the following order u u u u ã documentation import types message port. Type binding service SAP AG 2002, Title of Presentation, Speaker Name / 9

wsdl: import vs. xsd: import WSDL 1. 1 uses import mechanism to allow flexible authoring n Different sections of a WSDL definition can be defined in separate files and then imported into another WSDL file n wsdl: import is modeled after xsd: import, but the WSDL 1. 1 spec doesn’t provide any explanation about how it should be used u It’s interpreted differently by different vendor and causes interoperability problems BP 1. 0 provides the following guidance: n 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 u Namespace coercion is disallowed. The imported wsdl must be referenced with the same namespace as defined by its target. Namespace u 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 u n xsd: import can only be used to import XML schema definitions It can only be used in the <types> section u It should follow the same rules as specified in xml schema u ã SAP AG 2002, Title of Presentation, Speaker Name / 10

Example – wsdl: import vs xsd: import <definitions. . . xmlns: wsdl =“http: //schemas. xmlsoap. org/wsdl/” xmlns: test 1 = “http: //example. com/stockquote/test 1” xmlns: test 2 = “http: //example. com/stockquote/test 2”> <wsdl: import namespace=“http: //example. com/stockquote/test 1” location="http: //example. com/stockquote. wsdl"/> <wsdl: types> <xsd: schema … xmlns: xsd ="http: //www. w 3. org/2001/XMLSchema"> <xsd: import namespace=“http: //example. com/stockquote/test 2” schema. Location="http: //example. com/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 n One can use the “element” attribute to reference an XSD global element. e. g. <message name="Get. Trade. Prices. Input"> <part name=“purchase. Order" element=“tns: purchase. Order"/>. . . </message> n Or use “type” to reference an XSD simple or complex type. E. g. <message name="Get. Trade. Prices. Input"> <part name="ticker. Symbol" type="xsd: string"/>. . . </message> n 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 n A WSDL should, but not required to, include all known faults n Soap faults can appear as body fault or header fault What is the “style” of soapbind: fault or soapbind: headerfault? n “RPC” is only appliable to soapbind: body n Headers, headerfaults, and faults are always “document” style n They can only refer to a wsdl: part that has been defined using the “element” attribute What are the right fault code to use? n “Version. Mismatch”, and “Must. Understand” should be first checked n 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 n One exception: when xsd: import is its only child The target. Namespace of a WSDL definition and the target. Namespace 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 BP 1. 0 recommendations are related to the use of RPC style n Already covered some in the slides for part@type use and namespace use n Example follows ã SAP AG 2002, Title of Presentation, Speaker Name / 16

Example - A RPC style WSDL 1. 1 definition the case of RPC, the resulting soap message is <definitions … target. Namespace =“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 target. Namespace="http: //example. org/foo/" xmlns: tns="http: //example. org/foo/" xmlns: xsd="http: //www. w 3. org/2001/XMLSchema" element. Form. Default="qualified“ attribute. Form. Default="unqualified"> <xsd: complex. Type name="foo. Type"> <xsd: sequence> <xsd: element ref="tns: bar"/> <xsd: element ref="tns: baf"/> </xsd: sequence> used as the definition of part accessor children </xsd: complex. Type> <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="Bar. Msg"> <part name="Bar. Accessor" type="foo: foo. Type"/> </message> used as the name of the operation wrapper <port. Type name="Bar. Port. Type"> <operation name="Bar. Operation"> <input message="bar: Bar. Msg"/> </operation> </port. Type> ã <binding name="Bar. SOAPBinding" type="bar: Bar. Port. Type"> <soapbind: binding transport="http: //schemas. xmlsoap. org/soap/http/" style="rpc"/> <operation name="Bar. Operation"> <input message="bar: Bar. Msg"> <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. w 3. org/2001/XMLSchema-instance" xmlns: xsd="http: //www. w 3. 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: Bar. Operation xmlns: m="http: //example. org/bar/"> <Bar. Accessor> <foo: bar>String</foo: bar> <foo: baf>0</foo: baf> </Bar. Accessor> </m: Bar. Operation> </s: Body> </s: Envelope> Children of part accessor have their namespace from their schema definition 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 BP 1. 0 has a well-defined scope which is decided by its underlying specifications. n Conformance is only relevant within its n BP 1. 0 covers WSDL 1. 1, SOAP 1. 1, UDDI 2. 0 and a few other related specs BP 1. 0 conformance is based on three kinds of artifacts n n 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 WSDL 1. 1 n Port n Binding n port. Type u Operation u 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 BP 1. 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 n WSDL top elements( e. g. wsdl: port, wsdl: binding, etc) n SOAP message header n UDDI t. Model For Example, <wsdl: service name="My. Service" > l <wsdl: port name="My. Port" binding="tns: My. Binding" > l <wsdl: documentation> l <wsi: Claim conforms. To="http: //ws-i. org/profiles/basic/1. 0" /> </wsdl: documentation> l <soapbind: address location="http: //example. org/myservice/myport" /> l </wsdl: port> </wsdl: service> ã SAP AG 2002, Title of Presentation, Speaker Name / 20

Discussion – BP 1. 0 Impact On WSDL 1. 1 BP 1. 0 provides many valuable clarifications on use of WSDL 1. 1. These clarifications should be reflected in all WSDL examples in BPEL spec The following BP 1. 0 constraints affect port. Type definitions and should be considered for BPEL n XML 1. 0 is mandated for WSDL definitions - OK n XML schema is the only conformant type system - OK n Disallow operation overloading - operation name must be unique within a port. Type – should be enforced n Disallow out-bound operations – OK The following constraints are for bindings, there is no direct conflicts with BPEL n SOAP over HTTP is the only conformant binding –OK, we only provide conformant port. Type definition, bindings are up to the services implementers. n Disallows (soap) encoding – OK, same as above ã SAP AG 2002, Title of Presentation, Speaker Name / 21