- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 30 Sep 2005 05:27:05 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv8174/ws/desc/wsdl20
Modified Files:
wsdl20-primer.html wsdl20-primer.xml
Log Message:
rewrite "More on Message Types" section to incorporated resolution for LC343
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.132
retrieving revision 1.133
diff -C2 -d -r1.132 -r1.133
*** wsdl20-primer.xml 28 Sep 2005 00:03:43 -0000 1.132
--- wsdl20-primer.xml 30 Sep 2005 05:27:02 -0000 1.133
***************
*** 688,713 ****
<!-- ******************MessageTypes********************************** -->
<div2 id="more-types"><head>More on Message Types</head>
- <p>The WSDL 2.0 <code>types</code> element provides a mechanism for enclosing message schemas in a WSDL 2.0 document. Because WSDL 2.0 directly supports schemas written in XML Schema
- <bibref ref="XMLSchemaP1"/>, we will focus here on the use of XML Schema to define message types. Schemas written in other type definition languages must be defined using a WSDL 2.0 language extension. For examples of other schema languages, see the W3C notes on <bibref ref="altschemalangs"/> . </p>
-
- <p>There are two ways to indicate XML Schema message definitions using the <code>types</code> element.
- One way is to inline schema definitions within <code>xs:schema</code> elements that are children of <code>types</code>, as we have already seen. The other way is to use <code>xs:import</code> directly under <code>types</code>. It is perfectly reasonable to use both ways in one WSDL 2.0 document.</p>
-
- <p>
- A WSDL 2.0
- <code>description</code>
- may only refer to XML Schema components that are either
- imported or inlined into that WSDL 2.0
- <code>description</code>. In other words, the use of
- <code>xs:import</code>
- and/or
- <code>xs:schema</code>
- is a necessary condition for making XML Schema
- components available to a WSDL 2.0 Description
- component.
- </p>
! <p>The following XML syntax for the <code>types</code> element illustrates the use of <code>xs:import</code> and <code>xs:schema</code>:</p>
<eg xml:space="preserve"><description>
<<b>types</b>>
--- 688,699 ----
<!-- ******************MessageTypes********************************** -->
+
<div2 id="more-types"><head>More on Message Types</head>
! <p>Message types may be defined in various schema languages. In this primer, we will only focus on the use of XML Schema <bibref ref="XMLSchemaP1"/> since XML Schema
! support is required and natively supported by WSDL 2.0. Message type definitions written in other schema languages may be introduced into a WSDL 2.0 via extensions. The W3C notes on <bibref ref="altschemalangs"/> provides examples of using other schema languages. </p>
!
! <p>The following is the XML syntax for the <code>wsdl:types</code> element:</p>
!
<eg xml:space="preserve"><description>
<<b>types</b>>
***************
*** 719,735 ****
</description>
</eg>
<div3 id="more-types-schema-inline">
<head>Inlining XML Schema</head>
! <p>We have already seen an example of using inlined schema definitions in section <specref ref="basics-types"/>, so we will merely add a few additional points here. </p>
! <p>When XML Schema is inlined directly in a WSDL 2.0 document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so, as though the schema had been copied and pasted into the <code>types</code> element.
! The schema components defined in the inlined schema are then available to
! WSDL 2.0 for reference by QName (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="&w3c-designation-part1;#qnameres">QName Resolution</xspecref>"). </p>
! <p>Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism (described in the next section),
! an inlined XML schema may also use XML Schema's native <code>xs:import</code> and <code>xs:include</code>
! elements to refer to schemas either in separate files or inlined in the same
! WSDL 2.0 document. However, components inlined using <code>xs:import</code> have different visibility from those
! inlined using <code>xs:include</code>: <code>xs:include</code>d components are available to WSDL 2.0 for reference by QName, but <code>xs:import</code>ed components are not.</p>
!
--- 705,716 ----
</description>
</eg>
+
+ <p>There are two ways to make XML Schema message definitions visible, or in other words, available for reference by Qname (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="&w3c-designation-part1;#qnameres">QName Resolution</xspecref>") in a WSDL 2.0 document: inlining or importing. Inlining is to put the schema definitions directly within an <code>xs:schema</code> element under <code>types</code>. Importing is to have the schema defined in a separate document and then bring it into the WSDL definition by using <code>xs:import</code> directly under <code>types</code>. </p>
+
+ <p>In the following sections, we will provide examples for the different mechanisms.</p>
<div3 id="more-types-schema-inline">
<head>Inlining XML Schema</head>
! <p>We have already seen an example of using inlined schema definitions in section <specref ref="basics-types"/>. When XML Schema is inlined directly in a WSDL 2.0 document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema to do so, as though a schema file had been copied and pasted into the <code>types</code> element. The schema components defined in the inlined schema are then available to the containing WSDL 2.0 <code>description</code> for reference by QName. For instance, in <specref ref="example-initial"/>, the input message of the interface operation "opCheckAvailability" is defined by the "ghns:checkAvailability" element in the inlined schema. </p>
***************
*** 738,764 ****
<div3 id="more-types-schema-import">
<head>Importing XML Schema</head>
- <p> There are many cases where one would prefer importing schema definitions from separate schema files instead of
- inlining them directly under the <code>types</code> element. One reason is reusability of the schemas. Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism,
- type and element declarations inlined in a WSDL 2.0 document are NOT automatically made available to the importing document, even though other WSDL 2.0 components (such as Interfaces, Bindings, etc.) do become available. Therefore, if one wishes to share schema documents across several WSDL 2.0 documents, they should instead be placed in separate XML Schema documents and imported into each WSDL 2.0 document using <code>xs:import</code> directly under <code>types</code>. </p>
-
! <p>
! Within the <el>types</el> element, the type components defined in any
! XML Schema namespaces that are imported
! via <el>xs:import</el> elements and any type components defined via <el>xs:schema</el> elements
! are available to the WSDL 2.0 components defined in the containing WSDL 2.0 documents.
! The type components defined in <el>xs:schema</el> elements may by introduced via <el>xs:include</el>
! elements.
! However, the XML Schema namespaces declared via <el>xs:import</el> elements within
! <el>xs:schema</el> elements do not become available to the WSDL 2.0 components defined in the
! containing WSDL 2.0 document.
! </p>
! <p>Here is an example of importing a schema. Assuming the message types in <specref ref="example-initial-types"/> are defined in a separate schema file named "http://greath.example.com/2004/schemas/resSvc.xsd" with a target namespace "http://greath.example.com/2004/schemas/resSvc", the schema definition can then be imported into the WSDL 2.0 as follows: </p>
<example id="example-schema-import">
! <head>Example of Importing Message Definitions</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
! <description
! ]]>xmlns="&wsdl-ns;"<![CDATA[
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"
--- 719,733 ----
<div3 id="more-types-schema-import">
<head>Importing XML Schema</head>
! <p>XML Schema components can be defined in separate schema files and be made available to a WSDL2.0 <code>description</code> by using <code>xs:import</code> directly under <code>types</code>. </p>
! <p> There are many cases where one would prefer having schema definitions in separate schema files. One reason is the reusability of the schema definitions. Inlined schema definitions are only available to the containing WSDL 2.0 <code>description</code>. Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism for importing other WSDL files, schema definitions inlined in an imported WSDL document are NOT automatically made available to the importing WSDL 2.0 document, even though other WSDL 2.0 components (such as Interfaces, Bindings, etc.) do become available. Therefore, if one wishes to share schema definitions across several WSDL 2.0 <code>description</code>s, these schema definitions should instead be placed in separate XML Schema documents and imported into each WSDL 2.0 <code>description</code> using <code>xs:import</code> directly under <code>types</code>.</p>
!
! <p>Let's see an example. Assuming the message types in <specref ref="example-initial-types"/> are defined in a separate schema file named "http://greath.example.com/2004/schemas/resSvc.xsd" with a target namespace "http://greath.example.com/2004/schemas/resSvc", the schema definition can then be brought into the WSDL 2.0 <code>description</code> using <code>xs:import</code>. Note that only components in the imported namespace "http://greath.example.com/2004/schemas/resSvc" are available for reference in the WSDL 2.0 document. </p>
!
<example id="example-schema-import">
! <head> <code>xs:import</code>ed Message Definitions are made Available to the Containing WSDL 2.0 Description</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
! <description ]]>xmlns="&wsdl-ns;"<![CDATA[
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"
***************
*** 768,773 ****
<types>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc"
! schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
</types>
--- 737,742 ----
<types>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc"
! schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
</types>
***************
*** 775,781 ****
--- 744,807 ----
</description>]]></eg>
</example>
+
+
+ <p>It's important to note that <code>xs:import</code> used directly under <code>wsdl:types</code> has been given a different visibility than <code>xs:import</code> used inside an inlined schema. An inlined schema may use native XML schema <code>xs:import</code> to bring in external schema definitions that are in different namespaces; However, though this is the schema importing mechanism recommended for WSDL 1.1 in <xspecref href="http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html#WSDL_and_Schema_Import">WS-I Basic Profile</xspecref>, according to XML Schema specification, such enclosed message definitions are only visible to the importing schema (in this case, the inlined schema). They are not visible to the containing WSDL 2.0 <code>description</code>. </p>
+
+ <p>If we change <specref ref="example-schema-import"/> to use XML Schema's native <code>xs:import</code> element in an inlined schema, the schema components defined in the namespace http://greath.example.com/2004/schemas/resSvc are not available to our example WSDL 2.0 definition any more. </p>
+
+ <example id="example-schema-import1">
+ <head><code>xs:import</code>ed Message Definitions are not Available to the Containing WSDL 2.0 Description</head>
+ <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
+ <description ]]>xmlns="&wsdl-ns;"<![CDATA[
+ targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"
+ xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"
+ xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"
+ . . . >
+ . . .
+
+ <types>
+ <xs:schema targetNamespace="http://greath.example.com/2004/schemas/resSvcWrapper">
+ <xs:import namespace="http://greath.example.com/2004/schemas/resSvc"
+ schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
+ </xs:schema>
+ </types>
+
+ . . .
+ </description>]]></eg>
+ </example>
+
+
+ <p>Of course, an inlined XML schema may also use XML Schema's native <code>xs:include</code> element to refer to schemas defined in separate files when the included schema has the same namespace as the including schema. In this case, according to XML Schema, the included schema components become a part of the including schema as though they had been copied and pasted into the including schema. Hence, the included schema components are also available to the containing WSDL 2.0 <code>description</code> for reference by Qname. </p>
+
+ <p>The following example has the same effect as <specref ref="example-initial-types"/>:</p>
+
+ <example id="example-schema-import2">
+ <head><code>xs:included</code> Message Definitions are Available to the Containing WSDL 2.0 Description</head>
+ <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
+ <description ]]>xmlns="&wsdl-ns;"<![CDATA[
+ targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"
+ xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"
+ xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"
+ . . . >
+ . . .
+
+ <types>
+ <xs:schema targetNamespace="http://greath.example.com/2004/schemas/resSvc">
+ <xs:include schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
+ </xs:schema>
+ </types>
+
+ . . .
+ </description>]]></eg>
+ </example>
+
</div3>
+
+
+
<div3
id="more-types-import-include-summary"><head>Summary of Import and Include Mechanisms</head>
+
+
<p>So far we have briefly covered both WSDL import/include and schema import/include. The following table summarizes the similarities and differences
between the WSDL 2.0 and XML Schema
***************
*** 790,793 ****
--- 816,820 ----
<th>Object</th>
<th>Meaning</th>
+ <th>Visibility of Schema Components</th>
</tr>
</thead>
***************
*** 801,804 ****
--- 828,836 ----
from a DIFFERENT targetNamespace.
</td>
+ <td>
+ XML Schema Components in the imported <comp>description</comp>
+ component are NOT visible to the containing <code>description</code>.
+ </td>
+
</tr>
<tr>
***************
*** 810,816 ****
that has the SAME targetNamespace.
</td>
</tr>
<tr>
! <td>xs:import</td>
<td>XML Schema Namespace</td>
<td>
--- 842,853 ----
that has the SAME targetNamespace.
</td>
+ <td>
+ XML Schema components in the included <comp>Description</comp> component's
+ <prop comp="Description">element declarations</prop> and
+ <prop comp="Description">type definitions</prop> properties are visible to the containing <code>description</code>.
+ </td>
</tr>
<tr>
! <td>wsdl:types/ xs:import</td>
<td>XML Schema Namespace</td>
<td>
***************
*** 819,825 ****
from a DIFFERENT targetNamespace.
</td>
</tr>
<tr>
! <td>xs:include</td>
<td>XML Schema Document</td>
<td>
--- 856,879 ----
from a DIFFERENT targetNamespace.
</td>
+
+ <td>
+ XML Schema components in the imported namespace are visible to the containing <code>description</code>.
+ </td>
</tr>
<tr>
! <td>wsdl:types/ xs:schema/xs:import</td>
! <td>XML Schema Namespace</td>
! <td>
! Declare that XML Schema components
! refer to XML Schema components
! from a DIFFERENT targetNamespace.
! </td>
!
! <td>
! XML Schema components in the imported namespace are NOT visible to the containing <code>description</code>.
! </td>
! </tr>
! <tr>
! <td>wsdl:types/ xs:schema/xs:include</td>
<td>XML Schema Document</td>
<td>
***************
*** 828,835 ****
SAME targetNamespace.
</td>
</tr>
</tbody>
</table>
-
</div3>
--- 882,892 ----
SAME targetNamespace.
</td>
+ <td>
+ XML Schema components in the
+ included document are visible to the containing <code>description</code>.
+ </td>
</tr>
</tbody>
</table>
</div3>
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.96
retrieving revision 1.97
diff -C2 -d -r1.96 -r1.97
*** wsdl20-primer.html 28 Sep 2005 00:03:43 -0000 1.96
--- wsdl20-primer.html 30 Sep 2005 05:27:02 -0000 1.97
***************
*** 1,3 ****
! <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Web Services Description Language (WSDL) Version 2.0 Part 0: Primer</title><style type="text/css">
code { font-family: monospace; }
--- 1,3 ----
! <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Web Services Description Language (WSDL) Version 2.0 Part 0: Primer</title><style type="text/css">
code { font-family: monospace; }
***************
*** 45,49 ****
div.exampleHeader { font-weight: bold;
[...1213 lines suppressed...]
<interface name="reservationListInterfaceWithQuery">
--- 3718,3722 ----
</p>
<div class="exampleOuter">
! <p style="text-align: left" class="exampleHead"><a name="example_reservationList_HTTP_GET_single_wsdl"></a><i><span>Example 5-17. </span>WSDL 2.0 for Using a Single Query Type</i></p>
<div class="exampleInner"><pre>. . .
<interface name="reservationListInterfaceWithQuery">
***************
*** 3727,3731 ****
<h3><a name="adv-rdf-mapping"></a>5.5 Mapping to RDF and Semantic Web</h3>
! <table border="1" summary="Editorial note: KevinL"><tr><td width="50%" valign="top" align="left"><b>Editorial note: KevinL</b></td><td width="50%" valign="top" align="right">20050429</td></tr><tr><td valign="top" align="left" colspan="2">
This section might be removed - pending on the availability of the RDF mapping note. </td></tr></table>
--- 3784,3788 ----
<h3><a name="adv-rdf-mapping"></a>5.5 Mapping to RDF and Semantic Web</h3>
! <table border="1" summary="Editorial note: KevinL"><tr><td align="left" valign="top" width="50%"><b>Editorial note: KevinL</b></td><td align="right" valign="top" width="50%">20050429</td></tr><tr><td colspan="2" align="left" valign="top">
This section might be removed - pending on the availability of the RDF mapping note. </td></tr></table>
Received on Friday, 30 September 2005 05:27:14 UTC