- From: David Booth via cvs-syncmail <cvsmail@w3.org>
- Date: Sun, 17 Apr 2005 16:57:01 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv14298
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
Finished editing/updating through sec 7.5 (Versioning).
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.51
retrieving revision 1.52
diff -C2 -d -r1.51 -r1.52
*** wsdl20-primer.xml 17 Apr 2005 04:36:22 -0000 1.51
--- wsdl20-primer.xml 17 Apr 2005 16:56:59 -0000 1.52
***************
*** 1374,1384 ****
<head>Multiple Interfaces for the Same Service</head>
<p>Suppose a Web service wishes to expose two different interfaces: a customer interface for its regular users, and a management interface for its operator. WSDL 2.0 limits a wsdl:service to a single wsdl:interface, and does not provide any mechanisms to formally indicate this kind of relationship between interfaces. How can service providers indicate a relationship between services? Conventions outside of the WSDL 2.0 language can be used, but since they are outside of the WSDL 2.0 language (and therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. With that caveat in mind, potential strategies include:<ulist><item><p><b>Declare both interfaces in the same wsdl:description element.</b> Although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:description, an application or toolkit could interpret this to mean that they are related i some way.</p></item><item><p><b>Declare both interfaces in the same wsdl:targetNamespace.</b> Again, although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:targetNamespace, an application or toolkit could interpret this to mean that they are related in some way.
! </p></item><item><p><b>Add an extension to WSDL 2.0</b> that links together all services that are related in this way. WSDL 2.0's open content model permits extension elements from other namespaces to appear in a WSDL document.</p></item><item><p><b>Declare them in completely separate WSDL documents, but use the same endpoint address for both.</b> I.e., declare a wsdl:interface and wsdl:service for the customer interface in one WSDL document, and a wsdl:interface and wsdl:service for the management interface in a different WSDL document, but use the same endpoint address for both. (By "different WSDL document" we mean that both documents are never included or imported into the same WSDL 2.0 descriptions component.) Although this approach may work in some circumstances, it means that the same endpoint address would be used for two different purposes, which is apt to cause confusion or ambiguity. Furthermore, it is contrary to the Web architectural principle that different URIs should be used to identiy different Web resources. [Ref W3C TAB WebArch http://www.w3.org/TR/webarch/#URI-collision ]
! </p></item><item><p><b>Use inheritance to combine the customer interface and management interface</b> into a single, larger wsdl:interface. Of course, this reduces modularity and means that the management interface becomes exposed to the customers, which is not good. </p></item></ulist></p>
</div2><div2 id="adv-versioning">
! <head>Versioning and Service Equivalency</head>
! <p>[ See also <loc href="http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0047.html">http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0047.html</loc> ]</p>
! <p>Per decision 2004-03-04 to add the results of the Versioning Task Force also.</p>
! </div2>
--- 1374,1432 ----
<head>Multiple Interfaces for the Same Service</head>
<p>Suppose a Web service wishes to expose two different interfaces: a customer interface for its regular users, and a management interface for its operator. WSDL 2.0 limits a wsdl:service to a single wsdl:interface, and does not provide any mechanisms to formally indicate this kind of relationship between interfaces. How can service providers indicate a relationship between services? Conventions outside of the WSDL 2.0 language can be used, but since they are outside of the WSDL 2.0 language (and therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. With that caveat in mind, potential strategies include:<ulist><item><p><b>Declare both interfaces in the same wsdl:description element.</b> Although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:description, an application or toolkit could interpret this to mean that they are related i some way.</p></item><item><p><b>Declare both interfaces in the same wsdl:targetNamespace.</b> Again, although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:targetNamespace, an application or toolkit could interpret this to mean that they are related in some way.
! </p></item><item><p><b>Add an extension to WSDL 2.0</b> that links together all services that are related in this way. WSDL 2.0's open content model permits extension elements from other namespaces to appear in a WSDL document.</p></item><item><p><b>Declare them in completely separate WSDL documents, but use the same endpoint address for both.</b> I.e., declare a wsdl:interface and wsdl:service for the customer interface in one WSDL document, and a wsdl:interface and wsdl:service for the management interface in a different WSDL document, but use the same endpoint address for both. (By "different WSDL document" we mean that both documents are never included or imported into the same WSDL 2.0 descriptions component.) Although this approach may work in some circumstances, it means that the same endpoint address would be used for two different purposes, which is apt to cause confusion or ambiguity. Furthermore, it is contrary to the Web architectural principle that different URIs should be used to identiy different Web resources. (See the Web Architecture <bibref ref="webarch"/> section on <xspecref href="http://www.w3.org/TR/webarch/#URI-collision">URI collision</xspecref>.)</p></item><item><p><b>Use inheritance to combine the customer interface and management interface</b> into a single, larger wsdl:interface. Of course, this reduces modularity and means that the management interface becomes exposed to the customers, which is not good. </p></item></ulist></p><p>The desire to express relationships between services is also relevant to Web service versioning, discussed next.</p>
</div2><div2 id="adv-versioning">
! <head>Web Service Versioning</head>
! <p>A WSDL 2.0 document describes a set of messages that a Web service may
! send and receive. In essence, it describes a language for interacting with that service. However it is possible for a Web service to exchange
! other messages beyond those described in a particular WSDL 2.0 document. Often
! this circumstance occurs following an evolution of the client and/or service, and thus an evolution of the interaction language.</p><p>How best to manage the evolution (versioning) of Web based systems is,
! at the time of writing, the subject of a wide ranging debate. However,
! there are three activities within the W3C that are directly relevant
! to versioning of Web services description:</p>
!
! <ednote><edtext>ToDo: Add bibliography entries for several documents mentioned in this section, and fill in appropriate @@ bibrefs @@.</edtext></ednote><ulist><item><p>The <loc href="http://www.w3.org/2001/tag/">Technical Architecture Group (TAG)</loc> has published guidance on
! the extensibility and versioning of data formats in its Web Architecture document <bibref ref="webarch"/>. There is also a more wide ranging draft finding on Versioning
! and Extensibility @@bibref@@. Both of these works build
! upon the technical note on Web Architecture: Extensible Languages @@bibref@@.</p></item><item><p>The <loc href="http://www.w3.org/XML/Schema">XML Schema Working Group</loc> is collecting a series of use cases
! for schema versioning as a part of the Schema 1.1 activity. See XML Schema Versioning Use Cases @@bibref@@.</p></item><item><p>The <loc href="http://www.w3.org/2001/sw/BestPractices/">Semantic Web Best Practices and Deployments Working Group</loc> is
! examining how vocabularies may evolve. See @@bibref: http://esw.w3.org/topic/VocabManagementNote @@</p></item></ulist><p>While incomplete, these activities all agree in one important
! respect: that versioning is difficult, but you SHOULD
! anticipate and plan for change.</p><p>The draft finding on Versioning and Extensibility details two key
! approaches to versioning:</p><ulist><item><p>comaptible evolution; and</p></item><item><p>big bang.</p></item></ulist><div3 id="adv-versioning-compatible-evolution"><head>Compatible Evolution</head><p>In <emph>compatible evolution</emph>, designers are expected to limit changes to
! those that are either backward or forward compatible, or both:</p><glist><gitem><label>Backward compatible</label><def><p>The receiver behaves
! correctly if it receives a message in an <emph>older</emph> version of the interaction
! language.</p></def></gitem><gitem><label>Forward compatible</label><def><p>The receiver behaves
! correctly if it receives a message in a <emph>newer</emph> version of the interaction
! language.</p></def></gitem></glist><p>Since Web services and their clients both send and receive messages, these concepts can apply to both parties. However, since WSDL 2.0 is service-centric, we will focus on the case of service evolution.</p><p>There are three critical areas in which a service described in WSDL 2.0 my
! evolve:</p><ulist><item><p>The service now also supports additional binding.
! In compatible evolution, this should be a safe addition, given that adding
! a new binding should not impact any existing interactions using another
! transport.</p></item><item><p>An interface supports new operations.
! Again, in compatible evolution this is usually safe, given that adding an
! additional operation to an abstract interface should not impact any
! existing interactions.</p></item><item><p>The messages exchanged may include additional data.
! How the messages themselves may change within a description depends to
! a large extent upon the type system being used to describe the message
! contents. RelaxNG @@bibref@@ has good support for describing vocabularies that
! ignore unknown XML, as does OWL/RDF @@bibref@@. XML Schema 1.0 has limited
! support for extending the description of a message via the <code>xs:any</code> and
! <code>xs:anyAttribute</code> constructs. XML Schema 1.1 @@bibref@@ has been chartered to
! provide "changes necessary to provide better support for versioning of
! schemas", and it is anticipated that this will include improved support
! for more "open content" and therefore better support for compatible
! evolution of messages.</p></item></ulist></div3><div3 id="adv-versioning-big-bang"><head>Big Bang</head><p>The <emph>big bang</emph> approach to versioning is the simplest to
! currently represent in WSDL 2.0. In this approach, any change to a WSDL 2.0 document
! implies a change to the document's namespace, a change to the interface
! implies a new interface namespace and a change to the message contents
! is communicated using a new message namespace. This approach has
! particular benefits where an agent may quickly tell if a service has
! changed by simply comparing the namespace value.</p></div3><div3 id="adv-versioning-combined"><head>Combined Approaches</head><p>It is feasible to combine the "compatible evolution" and "big bang" approaches in a variety of different
! ways. For example, the namespace could be changed when message
! descriptions are changed, but the namespace could stay the same when new
! operations are added.</p><p>While the big bang approach is currently the easiest to implement in WSDL 2.0, it can lead to a large number of cloned
! interfaces that become difficult to manage, thus making the compatible
! approach preferable to many for widely distributed systems. In the
! end, the choice of a versioning strategy for Web services described in
! WSDL 2.0 is left as an exercise to the reader.</p></div3></div2>
***************
*** 1392,1398 ****
</ednote>
<!-- =============== -->
! <p>This section shows how the <bibref ref="SOAP-MTOM"/> SOAP Message Transmission Optimization Mechanism (MTOM) may be engaged in the WSDL 2.0 SOAP binding extension.</p>
! <p>Let’s modify the CheckAvailability operation of the GreatH Hotel Reservation Service [ref] to return not only the room rate, but images of the room and the floorplan. We’ll modify the checkAvailabilityResponse data structure to include binary data representing these two images, indicated by xs:base64Binary data type:</p>
<example id="example-MTOM-schema">
--- 1440,1446 ----
</ednote>
<!-- =============== -->
! <p>This section shows how theSOAP Message Transmission Optimization Mechanism (MTOM) <bibref ref="SOAP-MTOM"/> may be engaged in the WSDL 2.0 SOAP binding extension.</p>
! <p>We will modify the CheckAvailability operation of the GreatH Hotel Reservation Service (<specref ref="example-initial"/>) to return not only the room rate, but images of the room and the floorplan. This will involve modifying the checkAvailabilityResponse data structure to include binary data representing these two images, indicated by <code>xs:base64Binary</code> data type:</p>
<example id="example-MTOM-schema">
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.32
retrieving revision 1.33
diff -C2 -d -r1.32 -r1.33
*** wsdl20-primer.html 17 Apr 2005 04:36:22 -0000 1.32
--- wsdl20-primer.html 17 Apr 2005 16:56:59 -0000 1.33
***************
*** 332,337 ****
href="#adv-multiple-docs-describing-same-service">Multiple
Interfaces for the Same Service</a><br />
!     7.5 <a href="#adv-versioning">Versioning
! and Service Equivalency</a><br />
    7.6 <a href="#adv-MTOM">MTOM
Support</a><br />
--- 332,344 ----
href="#adv-multiple-docs-describing-same-service">Multiple
Interfaces for the Same Service</a><br />
!     7.5 <a href="#adv-versioning">Web Service
! Versioning</a><br />
!         7.5.1 <a
! href="#adv-versioning-compatible-evolution">Compatible
! Evolution</a><br />
!         7.5.2 <a
! href="#adv-versioning-big-bang">Big Bang</a><br />
!         7.5.3 <a
! href="#adv-versioning-combined">Combined Approaches</a><br />
    7.6 <a href="#adv-MTOM">MTOM
Support</a><br />
***************
*** 358,368 ****
Schemas</a><br />
        7.13.1 <a
! href="#id5195384">Schemas in Imported Documents</a><br />
        7.13.2 <a
! href="#id5212970">Multiple Inline Schemas on One Document</a><br />
    7.14 <a href="#adv-schema-location">The
schemaLocation Attribute</a><br />
        7.14.1 <a
! href="#id5213278">Using the id Attribute to Identify Inline
Schemas</a><br />
    7.15 <a href="#adv-rdf-mapping">Mapping to
--- 365,375 ----
Schemas</a><br />
        7.13.1 <a
! href="#id5212666">Schemas in Imported Documents</a><br />
        7.13.2 <a
! href="#id5212969">Multiple Inline Schemas on One Document</a><br />
    7.14 <a href="#adv-schema-location">The
schemaLocation Attribute</a><br />
        7.14.1 <a
! href="#id5213277">Using the id Attribute to Identify Inline
Schemas</a><br />
    7.15 <a href="#adv-rdf-mapping">Mapping to
***************
*** 3795,3805 ****
<import namespace="http://finance.example.com/CreditCards/wsdl"
location="credit-card-faults.wsdl"/>
-
. . .
-
<interface name="reservation" extends="cc:creditCardFaults">
-
. . .
-
<operation name="makeReservation"
pattern="http://www.w3.org/2004/03/wsdl/in-out">
--- 3802,3808 ----
***************
*** 3903,3908 ****
confusion or ambiguity. Furthermore, it is contrary to the Web
architectural principle that different URIs should be used to
! identify different Web resources. [Ref W3C TAB WebArch
! http://www.w3.org/TR/webarch/#URI-collision ]</p>
</li>
--- 3906,3913 ----
confusion or ambiguity. Furthermore, it is contrary to the Web
architectural principle that different URIs should be used to
! identify different Web resources. (See the Web Architecture
! [<cite><a href="#webarch">Web Architecture</a></cite>] section on
! <a href="http://www.w3.org/TR/webarch/#URI-collision">URI
! collision</a>.)</p>
</li>
***************
*** 3917,3933 ****
<br />
<br />
</div>
<div class="div2">
! <h3><a id="adv-versioning" name="adv-versioning"></a>7.5 Versioning
! and Service Equivalency</h3>
! <p>[ See also <a
! href="http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0047.html">
! http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0047.html</a>
! ]</p>
! <p>Per decision 2004-03-04 to add the results of the Versioning
! Task Force also.</p>
</div>
--- 3922,4101 ----
<br />
<br />
+ <p>The desire to express relationships between services is also
+ relevant to Web service versioning, discussed next.</p>
</div>
<div class="div2">
! <h3><a id="adv-versioning" name="adv-versioning"></a>7.5 Web
! Service Versioning</h3>
! <p>A WSDL 2.0 document describes a set of messages that a Web
! service may send and receive. In essence, it describes a language
! for interacting with that service. However it is possible for a Web
! service to exchange other messages beyond those described in a
! particular WSDL 2.0 document. Often this circumstance occurs
! following an evolution of the client and/or service, and thus an
! evolution of the interaction language.</p>
! <p>How best to manage the evolution (versioning) of Web based
! systems is, at the time of writing, the subject of a wide ranging
! debate. However, there are three activities within the W3C that are
! directly relevant to versioning of Web services description:</p>
!
! <table border="1" summary="Editorial note">
! <tr>
! <td align="left" valign="top" width="50%"><b>Editorial
! note</b></td>
! <td align="right" valign="top" width="50%"> </td>
! </tr>
!
! <tr>
! <td colspan="2" align="left" valign="top">ToDo: Add bibliography
! entries for several documents mentioned in this section, and fill
! in appropriate @@ bibrefs @@.</td>
! </tr>
! </table>
!
! <ul>
! <li>
! <p>The <a href="http://www.w3.org/2001/tag/">Technical Architecture
! Group (TAG)</a> has published guidance on the extensibility and
! versioning of data formats in its Web Architecture document
! [<cite><a href="#webarch">Web Architecture</a></cite>]. There is
! also a more wide ranging draft finding on Versioning and
! Extensibility @@bibref@@. Both of these works build upon the
! technical note on Web Architecture: Extensible Languages
! @@bibref@@.</p>
! </li>
!
! <li>
! <p>The <a href="http://www.w3.org/XML/Schema">XML Schema Working
! Group</a> is collecting a series of use cases for schema versioning
! as a part of the Schema 1.1 activity. See XML Schema Versioning Use
! Cases @@bibref@@.</p>
! </li>
!
! <li>
! <p>The <a href="http://www.w3.org/2001/sw/BestPractices/">Semantic
! Web Best Practices and Deployments Working Group</a> is examining
! how vocabularies may evolve. See @@bibref:
! http://esw.w3.org/topic/VocabManagementNote @@</p>
! </li>
! </ul>
!
! <p>While incomplete, these activities all agree in one important
! respect: that versioning is difficult, but you SHOULD anticipate
! and plan for change.</p>
!
! <p>The draft finding on Versioning and Extensibility details two
! key approaches to versioning:</p>
!
! <ul>
! <li>
! <p>comaptible evolution; and</p>
! </li>
!
! <li>
! <p>big bang.</p>
! </li>
! </ul>
!
! <div class="div3">
! <h4><a id="adv-versioning-compatible-evolution"
! name="adv-versioning-compatible-evolution"></a>7.5.1 Compatible
! Evolution</h4>
!
! <p>In <em>compatible evolution</em>, designers are expected to
! limit changes to those that are either backward or forward
! compatible, or both:</p>
!
! <dl>
! <dt class="label">Backward compatible</dt>
!
! <dd>
! <p>The receiver behaves correctly if it receives a message in an
! <em>older</em> version of the interaction language.</p>
! </dd>
!
! <dt class="label">Forward compatible</dt>
!
! <dd>
! <p>The receiver behaves correctly if it receives a message in a
! <em>newer</em> version of the interaction language.</p>
! </dd>
! </dl>
!
! <p>Since Web services and their clients both send and receive
! messages, these concepts can apply to both parties. However, since
! WSDL 2.0 is service-centric, we will focus on the case of service
! evolution.</p>
!
! <p>There are three critical areas in which a service described in
! WSDL 2.0 my evolve:</p>
!
! <ul>
! <li>
! <p>The service now also supports additional binding. In compatible
! evolution, this should be a safe addition, given that adding a new
! binding should not impact any existing interactions using another
! transport.</p>
! </li>
!
! <li>
! <p>An interface supports new operations. Again, in compatible
! evolution this is usually safe, given that adding an additional
! operation to an abstract interface should not impact any existing
! interactions.</p>
! </li>
!
! <li>
! <p>The messages exchanged may include additional data. How the
! messages themselves may change within a description depends to a
! large extent upon the type system being used to describe the
! message contents. RelaxNG @@bibref@@ has good support for
! describing vocabularies that ignore unknown XML, as does OWL/RDF
! @@bibref@@. XML Schema 1.0 has limited support for extending the
! description of a message via the <code>xs:any</code> and
! <code>xs:anyAttribute</code> constructs. XML Schema 1.1 @@bibref@@
! has been chartered to provide "changes necessary to provide better
! support for versioning of schemas", and it is anticipated that this
! will include improved support for more "open content" and therefore
! better support for compatible evolution of messages.</p>
! </li>
! </ul>
! </div>
!
! <div class="div3">
! <h4><a id="adv-versioning-big-bang"
! name="adv-versioning-big-bang"></a>7.5.2 Big Bang</h4>
!
! <p>The <em>big bang</em> approach to versioning is the simplest to
! currently represent in WSDL 2.0. In this approach, any change to a
! WSDL 2.0 document implies a change to the document's namespace, a
! change to the interface implies a new interface namespace and a
! change to the message contents is communicated using a new message
! namespace. This approach has particular benefits where an agent may
! quickly tell if a service has changed by simply comparing the
! namespace value.</p>
! </div>
!
! <div class="div3">
! <h4><a id="adv-versioning-combined"
! name="adv-versioning-combined"></a>7.5.3 Combined Approaches</h4>
!
! <p>It is feasible to combine the "compatible evolution" and "big
! bang" approaches in a variety of different ways. For example, the
! namespace could be changed when message descriptions are changed,
! but the namespace could stay the same when new operations are
! added.</p>
!
! <p>While the big bang approach is currently the easiest to
! implement in WSDL 2.0, it can lead to a large number of cloned
! interfaces that become difficult to manage, thus making the
! compatible approach preferable to many for widely distributed
! systems. In the end, the choice of a versioning strategy for Web
! services described in WSDL 2.0 is left as an exercise to the
! reader.</p>
! </div>
</div>
***************
*** 3949,3962 ****
</table>
! <p>This section shows how the [<cite><a href="#SOAP-MTOM">SOAP
! MTOM</a></cite>] SOAP Message Transmission Optimization Mechanism
! (MTOM) may be engaged in the WSDL 2.0 SOAP binding extension.</p>
! <p>Let’s modify the CheckAvailability operation of the GreatH Hotel
! Reservation Service [ref] to return not only the room rate, but
! images of the room and the floorplan. We’ll modify the
checkAvailabilityResponse data structure to include binary data
! representing these two images, indicated by xs:base64Binary data
! type:</p>
<div class="exampleOuter">
--- 4117,4131 ----
</table>
! <p>This section shows how theSOAP Message Transmission Optimization
! Mechanism (MTOM) [<cite><a href="#SOAP-MTOM">SOAP MTOM</a></cite>]
! may be engaged in the WSDL 2.0 SOAP binding extension.</p>
! <p>We will modify the CheckAvailability operation of the GreatH
! Hotel Reservation Service (<a href="#example-initial">Example
! 2-1</a>) to return not only the room rate, but images of the room
! and the floorplan. This will involve modifying the
checkAvailabilityResponse data structure to include binary data
! representing these two images, indicated by
! <code>xs:base64Binary</code> data type:</p>
<div class="exampleOuter">
Received on Sunday, 17 April 2005 16:57:02 UTC