- From: Arthur Ryman via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 29 Mar 2005 23:08:26 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20 In directory hutz:/tmp/cvs-serv20058 Modified Files: wsdl20-primer.xml Log Message: Add section to Primer on Schemas in Imported Documents. Index: wsdl20-primer.xml =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v retrieving revision 1.41 retrieving revision 1.42 diff -C2 -d -r1.41 -r1.42 *** wsdl20-primer.xml 28 Mar 2005 12:23:21 -0000 1.41 --- wsdl20-primer.xml 29 Mar 2005 23:08:24 -0000 1.42 *************** *** 1943,1961 **** <date>20050326</date> <edtext> ! There is a minor problem in this example. ! For some reason, the Xerces parser thinks ! that when I restrict the ! <code>wsdl:ServiceType</code> ! complex type by constraining the <code>wsdl:endpoint</code> ! element to have a fixed value for its <code>binding</code> ! attribute, that the namespace of the ! <code>wsdl:endpoint</code> ! element changes to the target namespace of ! the schema. I assume this is a bug in ! Xerces. I'd appreciate it if someone could ! try validating this example with another ! processor. </edtext> </ednote> --- 1943,1962 ---- <date>20050326</date> <edtext> ! There is a problem in the current design of ! the WSDL schema. At present, the <code>wsdl:endpoint</code> ! element is namespace qualified so it is ! impossible to restrict ! <code>wsdl:ServiceType</code> ! to use the restricted ! <code>wsdl:EndPoint</code> ! type that has a fixed value for the <code>binding</code> ! attribute. The workaround is to change the ! WSDL schema so that ! <code>endpoint</code> ! has no namespace. For consistency, other ! nested elements should also have no ! namespace. </edtext> </ednote> *************** *** 2149,2153 **** <p><specref ref="reservationList.xsd"/>Shows the schema for the messages used in the Reservation List Web service.</p> <example id="reservationList.xsd"> ! <head></head> <eg><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <schema xmlns="http://www.w3.org/2001/XMLSchema" --- 2150,2154 ---- <p><specref ref="reservationList.xsd"/>Shows the schema for the messages used in the Reservation List Web service.</p> <example id="reservationList.xsd"> ! <head>The Reservation List Schema: reservationList.xsd</head> <eg><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <schema xmlns="http://www.w3.org/2001/XMLSchema" *************** *** 2209,2217 **** <p>[Add Paul Downey's contribution at http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0007.html ]</p> </div2> ! <div2 id="adv-multiple-inline-schemas"><head>Multiple In-Line Schemas</head><p>[Need to explain that this can be done. See - http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0109.html - http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0126.html - http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0130.html ]</p> </div2> <div2 id="adv-schema-location"> --- 2210,2455 ---- <p>[Add Paul Downey's contribution at http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0007.html ]</p> </div2> ! <div2 id="adv-multiple-inline-schemas"> ! <head>Multiple In-Line Schemas</head> ! <ednote> ! <name>Arthur</name> ! <date>20050329</date> ! <edtext> ! The cited discussion thread is about Schemas in ! imported WSDL, not Multiple In-Line Schemas. I ! will therefore include an example that addresses ! that topic of the thread, and an example that ! addresses the section title. ! </edtext> ! </ednote> ! <p> ! [Need to explain that this can be done. See ! http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0109.html ! http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0126.html ! http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0130.html ! ] ! </p> ! <p> ! WSDL 2.0 documents may contain one or more XML ! schemas defined within the ! <code>wsdl:types</code> ! element. This section illustrates the correct way to ! refer to these schemas, both from within the same ! document and from other documents. ! </p> ! ! <div3> ! <head>Schemas in Imported Documents</head> ! <p> ! In this example, we consider some GreatH Hotel ! Web services that retrieve and update ! reservation details. The retrieval Web service ! is defined in the ! <code>retrieveDetails.wsdl</code> ! WSDL document, along with a schema for the ! message format. The updating Web service is ! defined in the ! <code>updateDetails.wsdl</code> ! WSDL document which imports the first document ! and refers to both WSDL and schema definitions ! contained in the imported document. ! </p> ! ! <p> ! <specref ref="retrieveDetails.wsdl" /> ! shows the definition of the retrieval Web ! service in the ! <code> ! http://greath.example.com/2004/services/retrieveDetails ! </code> ! target namespace. This WSDL document also ! contains an inline schema that describes the ! reservation detail in the ! <code> ! http://greath.example.com/2004/schemas/reservationDetails ! </code> ! target namespace. This schema is visible to the ! <code>retrieveDetailsInterface</code> ! interface definition which refers to it in the ! <code>retrieve</code> ! operation's output message. ! </p> ! ! <example id="retrieveDetails.wsdl"> ! <head> ! The Retrieve Reservation Details Web ! Service: retrieveDetails.wsdl ! </head> ! <eg> ! <![CDATA[<?xml version="1.0" encoding="utf-8" ?> ! <description xmlns="http://www.w3.org/2004/08/wsdl" ! targetNamespace="http://greath.example.com/2004/services/retrieveDetails" ! xmlns:tns="http://greath.example.com/2004/services/retrieveDetails" ! xmlns:wdetails="http://greath.example.com/2004/schemas/reservationDetails" ! xmlns:xs="http://www.w3.org/2001/XMLSchema"> ! ! <documentation> ! This document describes the GreatH Retrieve Reservation Details ! Web service. ! </documentation> ! ! <types> ! <xs:schema xmlns="http://www.w3.org/2001/XMLSchema" ! targetNamespace="http://greath.example.com/2004/schemas/reservationDetails"> ! ! <xs:element name="reservationDetails"> ! <xs:complexType> ! <xs:sequence> ! <xs:element name="confirmationNumber" ! type="string" /> ! <xs:element name="checkInDate" type="date" /> ! <xs:element name="checkOutDate" type="date" /> ! <xs:element name="roomType" type="string" /> ! <xs:element name="smoking" type="boolean" /> ! </xs:sequence> ! </xs:complexType> ! </xs:element> ! </xs:schema> ! </types> ! ! <interface name="retrieveDetailsInterface"> ! ! <operation name="retrieve" ! pattern="http://www.w3.org/2004/03/wsdl/in-out"> ! <input messageLabel="In" element="#none" /> ! <output messageLabel="Out" ! element="wdetails:reservationDetails" /> ! </operation> ! ! </interface> ! ! </description>]]> ! </eg> ! </example> ! ! <p> ! <specref ref="updateDetails.wsdl" /> ! shows the definition of the updating Web service ! in the ! <code> ! http://greath.example.com/2004/services/updateDetails ! </code> ! target namespace. The ! <code>updateDetailsInterface</code> ! interface extends the ! <code>retrieveDetailsInterface</code> ! interface. However, the ! <code>retrieveDetailsInterface</code> ! belongs to the ! <code> ! http://greath.example.com/2004/services/retrieveDetails ! </code> ! namespace, so the ! <code>updateDetails.wsdl</code> ! document must import the ! <code>retrieveDetails.wsdl</code> ! to make that namespace visible.</p> ! <p> ! The ! <code>updateDetailsInterface</code> ! interface also uses the ! <code>reservationDetails</code> ! element definition that is contained in the ! inline schema of the imported ! <code>retrieveDetails.wsdl</code> ! document. However, this schema is not ! automatically visible within the ! <code>updateDetails.wsdl</code> ! document. To make it visible, the ! <code>updateDetails.wsdl</code> ! document must import the namespace of the inline ! schema within the ! <code>types</code> ! element using the XML schema ! <code>import</code> ! element. ! </p> ! <p> ! In this example, the ! <code>schemaLocation</code> ! attribute of the ! <code>import</code> ! element has been omitted. The ! <code>schemaLocation</code> ! attribute is a hint to the WSDL processor of the ! location of the imported schema namespace. ! However, the WSDL processor has already ! processed the ! <code>retrieveDetails.wsdl</code> ! document which contains the imported namespace ! in an inline schema so it should not need a ! further hint. However, this behavior depends on ! the implementation of the processor and so ! cannot be relied on. ! </p> ! <p> ! Although the WSDL document may validly omit the ! <code>schemaLocation</code> attribute, it is a best practice to either provide a ! reliable value for ! it or move the inline schema to a separate ! document, say ! <code>reservationDetails.xsd</code>, and directly import it in the ! <code>types</code> ! element of both ! <code>retrieveDetails.wsdl</code> ! and ! <code>updateDetails.wsdl</code>. In general, schemas that are expected to be ! referenced from more than one WSDL document ! should be defined in a separate schema document ! rather than be inlined. ! </p> ! ! <example id="updateDetails.wsdl"> ! <head>The Update Reservation Details Web Service: updateDetails.wsdl</head> ! <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?> ! <description xmlns="http://www.w3.org/2004/08/wsdl" ! targetNamespace="http://greath.example.com/2004/services/updateDetails" ! xmlns:tns="http://greath.example.com/2004/services/updateetails" ! xmlns:retrieve="http://greath.example.com/2004/services/retrieveDetails" ! xmlns:details="http://greath.example.com/2004/schemas/reservationDetails" ! xmlns:xs="http://www.w3.org/2001/XMLSchema"> ! ! <documentation> ! This document describes the GreatH Update Reservation Details ! Web service. ! </documentation> ! ! <import ! namespace="http://greath.example.com/2004/services/retrieveDetails" ! location="retrieveDetails.wsdl" /> ! ! <types> ! <xs:import ! namespace="http://greath.example.com/2004/schemas/reservationDetails" /> ! </types> ! ! <interface name="updateDetailsInterface" ! extends="retrieve:retrieveDetailsInterface"> ! ! <operation name="update" ! pattern="http://www.w3.org/2004/03/wsdl/in-out"> ! <input messageLabel="In" ! element="details:reservationDetails" /> ! <output messageLabel="Out" ! element="details:reservationDetails" /> ! </operation> ! ! </interface> ! ! </description>]]></eg> ! </example> ! ! </div3> ! ! <div3> ! <head>Multiple Inline Schemas on One Document</head> ! <p>TBD.</p> ! </div3> </div2> <div2 id="adv-schema-location">
Received on Tuesday, 29 March 2005 23:08:27 UTC