- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 09 Mar 2005 06:42:43 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv14189/ws/desc/wsdl20
Modified Files:
wsdl20-primer.xml
Log Message:
reworked the section for "advanced topic I..."/"defining messages"
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.33
retrieving revision 1.34
diff -C2 -d -r1.33 -r1.34
*** wsdl20-primer.xml 8 Mar 2005 18:32:39 -0000 1.33
--- wsdl20-primer.xml 9 Mar 2005 06:42:41 -0000 1.34
***************
*** 485,489 ****
<p></p>
! In other words,
<ulist>
<item>
--- 485,489 ----
<p></p>
! In other words,the children elements of the <CODE>description</CODE> element should be ordered as follows:
<ulist>
<item>
***************
*** 561,573 ****
! <div1 id="advanced-topic-i"><head>Advanced Topic I: More on Message Types, Interfaces, Bindings, and Services</head>
<!-- ******************MessageTypes********************************** -->
<!-- ******************MessageTypes********************************** -->
! <div2 id="more-types"><head>More on Message Types</head>
<div3 id="more-types-schema">
! <head>Defining Messages Using XML Schema</head>
!
! <p>As we saw previously, WSDL 2.0 provides a <code>types</code> element for enclosing messages definitions in a WSDL document. There are two ways to enclose messages definitions within the <code>types</code> element: use <code>xs:import</code> mechanism provided by XML Schema, or embed the schemas within <code>xs:schema</code> elements. It's perfectly reasonable to use both ways in one WSDL. The following is a summary of the XML syntax for the <code>types</code> element:</p>
<eg xml:space="preserve"><description>
<<b>types</b>>
--- 561,580 ----
! <div1 id="advanced-topic-i"><head>Advanced Topic I: More on Description of Messages, Interfaces, Bindings, and Services</head>
<!-- ******************MessageTypes********************************** -->
<!-- ******************MessageTypes********************************** -->
! <div2 id="more-types"><head>Defining Messages</head>
!
! WSDL 2.0 <code>types</code> element provides a mechanism for enclosing messages definitions in a WSDL document. WSDL 2.0 only defines the use W3C XML Schema Language
! <bibref ref="XMLSchemaP1"/>. Support for XML Schema <bibref ref="XMLSchemaP1"/> is required of all WSDL2.0 processors. Alternatively, other type languages can be used via extension to define messages.
!
<div3 id="more-types-schema">
! <head>Defining Messages Using XML Schema</head>
! <p>There are two ways to enclose XML Schema messages definitions within the <code>types</code> element. One way is to use <code>xs:import</code> directly under <code>types</code>, the other way is to embed schema definitions within <code>xs:schema</code> elements which are children of <code>types</code>. It's perfectly reasonable to use both ways in one WSDL.</p>
!
! <p>A WSDL description MUST NOT refer to XML Schema components in a given namespace unless they are either imported or embedded into the WSDL description. In other words, using the <code>xs:import</code> and/or <code>xs:schema</code> constructs is a necessary condition for making XML Schema components available to a WSDL description. </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>>
***************
*** 580,648 ****
</description>
</eg>
! <p>A WSDL description MUST NOT refer to XML Schema components in a given namespace unless an <code>xs:import</code> and/or <code>xs:schema</code> statement
! for that namespace is present. In other words, using the <code>xs:import</code> and/or
! <code>xs:schema</code> constructs is a necessary condition for making XML Schema
! components available to a WSDL description. </p>
! <p>The use of type system other than XML Schema is permitted by the extension elements in the above syntax. (See <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix E <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#other-schemalang">Examples of Specifications of Extension Elements for Alternative Schema Language Support</xspecref>.)
! </p>
! <div4 id="more-types-schema-import">
! <head>Importing XML Schema</head>
! <p>Let's examine the XML Schema <code>import</code> first. Note the schema import mechanism described here is defined in the XML Schema language with some additional restrictions. It is different from the WSDL import/include as explained in <specref ref="adv-import-and-authoring"/>. The schema components defined in the imported schema are available for reference by QName. Note that only components defined in the schema itself and components the schema includes via <code>xs:include</code> are available to WSDL. Specifically, components that the schema imports via <code>xs:import</code> are NOT available to WSDL. <ednote><name>dbooth</name><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote></p>
! <p>A <code>types</code> element can contain zero or more <code>import</code>s which may have one or two attributes as follows:</p>
! <ulist>
! <item>
! <p>A REQUIRED <att>namespace</att> attribute of type <emph>xs:anyURI</emph>.</p>
! <p>The <att>namespace</att> attribute defines the namespace of the element declarations imported from the referenced schema. As mandated in Section 3 of the Part 1 specification, the referenced schema MUST contain an XML Schema <att>targetNamespace</att> attribute on its <code>xs:schema</code> element and the values of these two attributes MUST be identical. It is an error to import a schema that does not have an XML Schema target namespace. Such schemas must first be included (using <code>xs:include</code>) in a schema that contains a <att>targetNamespace</att> attribute; on its <code>xs:schema</code> element, which can then be either imported or inlined in the WSDL document.</p>
! </item>
! <item>
! <p>An OPTIONAL <att>schemaLocation</att> attribute of type <emph>xs:anyURI</emph>.</p>
! <p>The <att>schemaLocation</att> attribute, if present, provides a hint to the WSDL processor as to where the schema may be located. It's optional since the WSDL may have better ways to locate the schema files, for example, caching and
! cataloging technologies may provide better information than this hint.</p>
! </item>
! </ulist>
! </div4>
<div4 id="more-types-schema-embed">
<head>Embedding XML Schema</head>
! <p>When an XML schema is embedded directly in a WSDL document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so. This is comparable to simply cutting and pasting an
! existing, stand-alone schema to a location inside the <code>types</code> element.</p>
<p>The schema components defined in the embedded schema are available to
! WSDL for reference by QName (see @@@@). Note
! that only components defined in the schema itself and components
! included by it via <code>xs:include</code> are available to WSDL. Specifically,
! components that the schema imports via <code>xs:import</code> are NOT
! available to WSDL.</p>
! <p> Similarly, components defined in an embedded XML schema are NOT automatically
! made available to a WSDL description that imported (using <code>wsdl:import</code>)
! the description that embeds the schema (see section @@@@ for more details). For this reason, it is recommended that XML schema documents intended
! to be shared across several WSDL descriptions be placed in separate documents and imported using <code>xs:import</code>, rather than embedded inside a WSDL document.</p>
! <p>Inside an embedded XML schema, the <code>xs:import</code> and <code>xs:include</code>
! elements MAY be used to refer to other XML schemas embedded in the same
! WSDL description, provided that an appropriate value is specified for
! their <code>schemaLocation</code> attributes. The semantics of such elements are
! governed solely by the XML Schema specification <bibref ref="XMLSchemaP1"/>.</p>
! <ednote>
! <name>KevinL</name>
! <date>20040517</date>
! <edtext>
! Add Example - illustrate use of xs:import and xs:include for embedded schema
!
! Clarification - what should be the "appropriate value" for schemalocation, especially when its's xs:include?
! </edtext>
! </ednote>
! <p>A <code>types</code> element can contain zero or more <code>schema</code> elements, which may have the following attributes:</p>
! <ulist>
! <item>
! <p>A REQUIRED <att>targetNamespace</att> attribute of type <emph>xs:anyURI</emph>.</p>
! <p>It defines the XML Schema target namespace of the element declarations embedded in its owner <code>xs:schema</code>. Note that WSDL modifies the
! XML Schema definition of XML Schema <code>xs:schema</code> to make the <att>targetNamespace</att> attribute required. </p>
! </item>
! <item>
! <p>Additional OPTIONAL attributes as specified for the <code>xs:schema</code> element by the XML Schema specification.</p>
! </item>
! <item>
! <p>Zero or more child elements as specified for <code>xs:schema</code> by the XML Schema specification.</p>
! </item>
! </ulist>
! <p>Here is an example of importing a schema.</p>
<example id="example-schema-import">
<head>Importing Message Definitions into WSDL 2.0</head>
--- 587,617 ----
</description>
</eg>
!
<div4 id="more-types-schema-embed">
<head>Embedding XML Schema</head>
! <p>We have already seen examples of using embedded schema definitions in section <specref ref="basics-types" /> . When an XML schema is embedded directly in a WSDL document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so. This is comparable to simply cutting and pasting an existing, stand-alone schema to a location inside the <code>types</code> element.</p>
<p>The schema components defined in the embedded schema are available to
! WSDL for reference by QName (see @@@@). </p>
! <p>Just like in normal schemas, an embedded XML schema may use the <code>xs:import</code> and <code>xs:include</code>
! elements to refer to other XML schemas either in separate files or embedded in the same
! WSDL description. Note that components embedded in WSDL, <code>xs:import</code>ed, or <code>xs:include</code>d have different visibility to the containing WSDL description. Only components defined in the embedded schemas and components
! <code>xs:include</code>d are available to WSDL for Qname reference.Components that the embedded schemas import via <code>xs:import</code> are NOT available to WSDL.</p>
!
! <p>A <code>types</code> element can contain zero or more <code>schema</code> elements</p>
!
! </div4>
!
! <div4 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 to embedding them directly in WSDL. One reason is reusability of the schemas. Components defined in an embedded XML schema are NOT automatically made available to a WSDL description that imported (using <code>wsdl:import</code>)the description that embeds the schema (see section @@@@ for more details).So it is recommended that XML schema documents intended
! to be shared across several WSDL descriptions be placed in separate schema documents and imported into a WSDL document.To facilitate this, WSDL 2.0 allows use of <code>xs:import</code> directly under <code>types</code>. </p>
!
!
! <p>Note the schema import mechanism described here leverages XML Schema language <bibref ref="XMLSchemaP1"/>. It is different from the WSDL import/include as explained in <specref ref="adv-import-and-authoring"/>. The schema components defined in the imported schema are available to the containing WSDL for reference by QName. Note that only components defined in the imported schema itself and components the schema includes via <code>xs:include</code> are available to the containing WSDL. Specifically, components that the schema imports via <code>xs:import</code> are NOT available to WSDL. </p>
!
! <ednote><name>dbooth</name><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote>
!
! <p>A <code>types</code> element can contain zero or more <code>import</code>s </p>
! <p>Now let's see an example of importing a schema. Assuming the messages 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 as follows: </p>
<example id="example-schema-import">
<head>Importing Message Definitions into WSDL 2.0</head>
***************
*** 657,664 ****
<types>
- <documentation>
- Messages definitions of the reservation Web service of GreatH hotel.
- </documentation>
-
<xs:import namespace="http://greath.example.com/2004/schemas/resSvc"
schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
--- 626,629 ----
***************
*** 668,674 ****
</description>]]></eg>
</example>
-
</div4>
</div3>
</div2>
--- 633,655 ----
</description>]]></eg>
</example>
</div4>
</div3>
+
+ <div3 id="more-types-other-schema">
+ <head>Defining Messages Using other type languages</head>
+ <p>The use of type systems other than XML Schema is permitted by using extensions within <code>types</code>.
+
+ <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix E <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#other-schemalang"> provides a set of examples of using DTD and RELAX NG as alternative schema Languages</xspecref>.
+ </p>
+
+ <ednote>
+ <name>KevinL</name>
+ <date>20050308</date>
+ <edtext>
+ The WSD WG has decided to move Appendix E to a seperate notes. Reference here needs update when the new Notes is published.
+ </edtext>
+ </ednote>
+
+ </div3>
</div2>
***************
*** 679,686 ****
<!-- ************************interface*************************** -->
! <p>We previously mentioned that a WSDL 2.0 interface is basically a set of operations. However, there are some additional capabilities that we have not yet covered. First, let's review the syntax for the <code>interface</code> element. </p>
<div3 id="more-interfaces-interfaces">
<head>Interface Syntax </head>
! <ednote><name>dbooth</name><edtext>To do: Simplify this syntax summary.</edtext></ednote><p>Below is the XML syntax summary of the <code>interface</code> element:</p>
<eg xml:space="preserve">
<description targetNamespace="<emph>xs:anyURI</emph>" >
--- 660,669 ----
<!-- ************************interface*************************** -->
! <p>We previously mentioned that a WSDL 2.0 interface is basically a set of operations. However, there are some additional capabilities that we have not yet covered. First, let's review the complete syntax for the <code>interface</code> element. </p>
<div3 id="more-interfaces-interfaces">
<head>Interface Syntax </head>
! <ednote><name>dbooth</name><edtext>To do: Simplify this syntax summary.</edtext></ednote>
!
! <p>Below is the XML syntax summary of the <code>interface</code> element:</p>
<eg xml:space="preserve">
<description targetNamespace="<emph>xs:anyURI</emph>" >
***************
*** 822,832 ****
</eg>
</example>
! <ednote>
! <name>KevinL</name>
! <date>20040520</date>
! <edtext>
! Need clarification - fault must be named uniquely across interfaces?
! </edtext>
! </ednote>
</div4>
<div4 id="more-interfaces-operations">
--- 805,809 ----
</eg>
</example>
!
</div4>
<div4 id="more-interfaces-operations">
Received on Wednesday, 9 March 2005 06:42:44 UTC