Copyright © 2009 W3C® ( MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is the W3C Working Group Note "Framework for SML EPR-based Reference Schemes". This document was produced by the SML Working Group as part of the XML Activity.
Please submit comments on this document using the procedure described on the Working Group's home page. In summary, the Working Group solicits comments in Bugzilla from those who have access, and on the Working Group's public mailing list (public archive) from others.
Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document is intended to serve as guidance for designing SML reference schemes that employ WS-Addressing [WS-A] endpoint references (EPRs). Currently, this document is consistent with the Service Modeling Language (SML) 1.1 specification [SML] and the Service Modeling Language Interchange Format (SML-IF) 1.1 specification [SML-IF], but it may be obsoleted by future versions of these specifications. The SML WG does not expect this document to become a W3C Recommendation.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
The Service Modeling Language [SML] specification extends the Extensible Mark-up Language [XML] and XML Schema [XML Schema] with a mechanism for incorporating into XML documents references to other documents or document fragments. A reference to another document or document fragment is encoded by means of markup compliant with one or more reference schemes as defined in SML ([SML] , section 4.3). The SML specification defines one reference scheme, the SML URI Reference Scheme, which enables XML documents to use URIs [RFC 3986] to identify documents or document fragments. The SML URI Reference Scheme has the significant advantage of guaranteeing referential conformance of models that are exchanged between vendors ([SML-IF], section 5.1).
However, not all documents or document fragments can be retrieved simply by means of a URI that may be dereferenced. For example, the targeted document may be accessible only through a Web service endpoint. There are several protocols, each specifying its own message exchange pattern (MEP), that make documents and document fragments available through inter with a Web service. These include (but are not limited to):
Other such services may be defined in the future. It is a common characteristic of these services that their endpoints must be addressed using endpoint references (EPRs) as defined in the WS-Addressing specification [WS-A]. Consequently, this note considers how SML reference schemes can use Web services endpoint references to refer to services that provide documents or document fragments through message exchanges.
The SML specification provides a mechanism to define other reference schemes beyond the SML URI Reference Scheme in order to accommodate special purpose reference schemes as well as reference schemes that fall outside of the capabilities of URIs. The purpose of this Note is to propose a framework for defining SML reference schemes that accommodate references to documents accessed via EPRs.
EPRs cannot simply be placed in browsers and dereferenced to locate the target resource. Processors must know how to process a given EPR and this knowledge often involves knowing (1) the operations offered by the service and (2) the protocol required for invoking the targeted operation of the service. In this sense, the use of EPRs goes beyond the standard architecture of the Web [AWWW]. Therefore, use of the SML URI Reference Scheme is encouraged and remains the recommended approach for SML models. Nevertheless, it is recognized that in some cases model documents may be accessible only through a service that requires being addressed by means of an EPR. For further discussion of EPRs and interoperability, see section 4.2.
This section proposes a set of characteristics, or framework, for EPR-based SML reference schemes. These characteristics are based on the Reference Scheme definition requirements of SML ([SML], section 4.3 ).
The following guidance is recommended for defining EPR-based SML reference schemes:
An SML reference element should be identified as an instance of an EPR-based reference scheme if and
only if exactly one element information item whose
[local name] is
EndpointReference and whose
[namespace name] is defined by a WS-Addressing
specification (for example,
http://www.w3.org/2005/08/addressing)
is present as a child of the SML reference element.
An instance of an EPR-based SML reference scheme should be resolved by the SML validator by constructing the appropriate message to the service based on the provided EPR and any additional information it has or is provided about how to interact with the Web service endpoint. This additional information includes the signature of the operation that is to be invoked to access the targeted document or document fragment. This operation needs to be bound into a message to the service (e.g., a SOAP message [SOAP]) according the rules identified below (items a through c).
Note that to resolve an instance of an EPR-based SML reference scheme compliant with this framework, the SML validator must be a Web services client. If the validator does not have adequate information to construct the appropriate Web services request to the service providing access to the targeted document, then the EPR-based SML reference is unresolved.
The resolution process should conform to the following rules:
The Web service client should follow the appropriate binding rules for the EPR as specified in the WS-Addressing specification.
The appropriate binding rules for the operation as specified in the Web Service Description Language
(WSDL) [WSDL] binding element should be applied
in constructing the request to the service.
The SML reference target (see [SML], section 2.2) should be the content or a child within the content of the service response message. If there is no response message returned by the service (as defined by the service protocol), then the SML reference is unresolved.
The WS-Addressing specification defines the value of the abstract
[address] property
as an IRI [RFC 3987]. Since the IRI in the wsa:Address
element of the EPR identifies only an endpoint of a service and typically requires out-of-band
knowledge to retrieve a document or document fragment from that endpoint, an
EPR-based SML reference scheme usually does not use
target-complete identifiers. This Note should not be interpreted as excluding the possibility that the
design of a Web service could allow target-complete identifiers.
If this Framework is adopted as a normative basis for defining EPR-based SML reference schemes, then testing compliance with the framework would require the following changes to the language of the framework.
As noted in point 2 above, the additional knowledge that is required by a Web service client to resolve an instance of the an EPR-based reference scheme may include knowledge of the operations supported by the service endpoint. Because the operations are typically not provided in the EPR itself, and the Framework does not constrain these bindings, two otherwise equal EPRs associated with different service bindings could target different documents. Specific knowledge regarding the MEPs needed to interact with the service pointed to by the EPR may need to be made available to the SML model validator. See section 3.1 for a means by which such knowledge may be made available through an EPR-based SML reference scheme.
Consider thefollowing simple XML document:
<UniversityCourses xmlns="http://www.university.example.org/ns">
<PHY101>
. . .
</PHY101>
<PHY102>
. . .
</PHY102>
. . .
</UniversityCourses>
This simple document will be used in both the following example and the EPR-based SML
reference scheme to be developed in section 3. In the following example
we will assume that each course entry is indexed by an information item named CourseName, whose type is
xs:ID or xs:keyref and whose value is the name of the element.
The following example illustrates the use of an EPR-based SML reference scheme that is
compliant with the Framework. The EnrolledCourse element references a course named
PHY101 from the preceding document:
<EnrolledCourse xmlns:sml="http://www.w3.org/sml/2007/02"
sml:ref="true">
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Address>
http://www.university.example.org?CourseName=PHY101
</wsa:Address>
</wsa:EndpointReference>
</EnrolledCourse>
The service providing the university's list of courses is addressed by the URI
http://www.university.example.org. The service endpoint
expects a course name to be encoded in the query component of the IRI in the wsa:Address element.
Access to the same content may require a different EPR-based SML reference scheme if the
university's service interface involves a different means to target the desired
fragment. For example, section 3.2 provides another example
of an SML reference using a totally different EPR-based SML reference scheme.
Because of the virtually unlimited latitude in specifying Web service interfaces for
retrieving documents, EPR-based SML reference schemes may be defined with
mechanisms to address the requirements of specific service protocols. For
example, it may be desirable to include in the reference scheme definition a
specific wsa:Action that the Web service
client is to use in constructing the message to the service, or to provide a
fragment identifier as a separate operation parameter in the form of a QName or
XPath [XPath] expression. In some cases, because
of the service protocol, it may not be feasible to include this additional
information within the wsa:EndpointReference element itself. The
definition of a specific EPR reference scheme should use the Framework as its
basis and may add several conditions for identifying an instance of the
specific scheme.
Let us assume that the course listing in the previous example (section 2.2) is maintained by a WS-Resource conformant to the WS-ResourceFramework (WS-RF) specification [WS-RF]. The WS-ResourceFramework requires the use of EPRs to address conformant services. A definition of a specific SML Reference Scheme based on the WS-ResourceFramework might proceed as follows:
This reference scheme fully complies with the Framework defined in section 2.1.
An SML reference element is identified as an instance of the SML WS-RF Reference Scheme if and only if it is identified as using the Framework and it contains the following:
It has exactly one child element information item for which all of the following are true
Its [local name] is EndpointReference.
Its [namespace name] is http://www.w3.org/2005/08/addressing.
It has exactly one child element information item for which all of the following are true
Its [local name] is Action.
Its [namespace name] is http://www.w3.org/2005/08/addressing.
The content of this element must be a IRI that represents a valid WS-ResourceProperties [WS-RP] request operation.
It has at most one valid WS-RF message request element for which all the following are true:
Its [local name] corresponds to a WS-ResourceProperties operation element.
Its [namespace name] is http://docs.oasis-open.org/wsrf/rp-2.
The content of this element, if present, is a single QName or XPath expression.
NOTE:
The WS-ResourceProperties GetResourcePropertyDocument
operation does not require a message request element. The WS-RP operations
GetResourceProperty and Query ResourceProperties require a single element as the content of the SOAP
Body. However, the GetMultipleResourceProperties operation, which may
retrieve multiple resource properties, would, under conditions of normal usage,
yield an invalid SML reference because of referencing multiple elements.
Resolution of this reference scheme should conform with the following rules:
The EndpointReference
element is mapped to SOAP Header element(s) as specified in the WS-Addressing SOAP Binding
specification [WS-A SOAP].
The Action child element is mapped to a SOAP Header
element with the same QName and content value.
The WS-RF message request element, if present, is mapped to the SOAP
Body element with the same QName and content value.
The SML reference target is the content of the service response message. If there is no response message returned by the service, then the SML reference is unresolved.
As a consequence of conforming to the Framework, and not placing additional constraints on the resolution process sufficient to make it fully deterministic in the absence of outside knowledge, this reference scheme does not use target-complete identifiers.
This definition is not proposed as a normative definition of a WS-ResourceFramework reference scheme; however, this lack of normative standing should not be taken as precluding a similar definition being normatively defined.
Section 4.1 will identify further components of this definition that are required to insure that the reference scheme is interoperable.
This section illustrates the WS-RF Reference Scheme defined in the preceding section. For simplicity, we will use the same simple XML document introduced in the University Course Example (section 2.2). To conform to the WS-ResourceFramework, we assume that the schema of this document is constructed in the following manner:
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://www.university.example.org/ns"
targetNamespace="http://www.university.example.org/ns">
<xs:complexType name="CourseType">
<xs:sequence>
. . .
</xs:sequence>
</xs:complexType>
<xs:element name="PHY101" type="tns:CourseType"/>
<xs:element name="PHY102" type="tns:CourseType"/>
. . .
<xs:element name="UniversityCourses">
<xs:complexType>
<xs:sequence>
<xs:element ref="tns:PHY101"/>
<xs:element ref="tns:PHY102"/>
. . .
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
This example is not meant to imply that this is the best way to design the XML document or the schema for this kind of list; it is meant only as a means to enable both of the SML reference scheme examples to reference instance documents the same simple structure.
To retrieve the PHY101
element via the WS-RF Reference Scheme, the WS-ResourceProperties
GetResourceProperty operation may be used.
This operation has a wsa:Action as follows:
<wsa:Action>
http://docs.oasis-open.org/wsrf/rpw-2/GetResourceProperty/GetResourcePropertyRequest
</wsa:Action>
The WS-ResourceProperties message request element specifies the QName of the targeted document fragment, which must be a Global Element Declaration (GED), as the content value of the element representing the operation:
<wsrp:GetResourceProperty
xmlns:wsrp="http://docs.oasis-open.org/wsrf/rp-2"
xmlns:tns="http://www.university.example.org/ns">
tns:PHY101
</wsrp:GetResourceProperty>
Thus, a functionally equivalent SML reference to the reference in section 2.2 (for an identically structured XML instance document) could be specified with the WS-RF Reference Scheme as follows:
<EnrolledCourse
xmlns:sml="http://www.w3.org/sml/2007/02"
xmlns:wsrp="http://docs.oasis-open.org/wsrf/rp-2"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
sml:ref="true">
<wsa:EndpointReference>
<wsa:Address>http://www.university.example.org</wsa:Address>
</wsa:EndpointReference>
<wsa:Action>
http://docs.oasis-open.org/wsrf/rpw-2/GetResourceProperty/GetResourcePropertyRequest
</wsa:Action>
<wsrp:GetResourceProperty
xmlns:tns="http://www.university.example.org/ns">
tns:PHY101
</wsrp:GetResourceProeprty>
</EnrolledCourse>
WS-RF Reference Scheme instances provide to the SML model validator three essential parts for
constructing the message that is to be sent to the university course service:
the EPR of the service, the wsa:Action that is bound into the
SOAP Header, and the content of the
SOAP Body. Note that knowledge of
how to use the service bindings in constructing a SOAP message, for example,
what component(s) should go into the SOAP Header and which
into the SOAP Body, must be made available to the model consumer. This information
is typically provided by the WSDL binding for the service.
Interchanging SML models consisting of documents containing SML references that use EPR-based SML reference schemes requires special consideration. Interchange is performed by packaging the documents comprising an SML model into a single document as described in the SML-IF specification. In order to perform interchange set validation, the SML-IF validator must first look to validate any SML reference in terms of what is packaged in the SML-IF document itself. If validation fails from this perspective, SML-IF validators may choose to pursue the reference outside of the SML-IF document; however, given the complexity of de-referencing an EPR, SML-IF validators may be reluctant to do so.
In order to support this internal test of SML reference validity, the SML-IF specification introduces the notion of a document [alias] ([SML-IF], section 5.3.3). For aliases to be usable in the context of SML-IF, an alias name (a URI) must be derivable from the reference scheme instance so that the validator can determine what document in the interchange set the reference scheme is intending to point to. Thus if an EPR-based SML reference scheme will be used in the context of SML-IF, the reference scheme definition should include a method for mapping each EPR to a predictable URI. In particular, consideration should be given to mapping the EPR's [address] value (an IRI) to a URI. (However, to simplify the following discussion, this consideration will be left as an exercise for implementations of this Note.)
The following considerations pertain to the processing of SML references exposing EPR-based SML reference schemes in SML-IF documents by means of aliasing:
Unless the EPR-based SML reference scheme is sufficiently constrained to make use of
target-complete identifiers, which is unlikely for EPRs, its wsa:Address
cannot be used as an SML-IF document alias. Nevertheless, the
referenced document may be embedded in the SML-IF document. If maintaining the
fidelity of these links during interchange is necessary, several alternatives
are available, including but not limited to:
For each EPR-based SML reference scheme of an SML reference, the SML-IF producer adds a second reference scheme instance understood by the receiving SML-IF consumer. This second reference could use a URI that does not follow the SML-IF rules for resolving target-complete identifiers ([SML-IF], section 5.3.4 .) That is, the URI would fall into "category 3" discussed in that section. Note that the identifier value must be generated dynamically from the information given in the EPR reference scheme instance. Care must be taken to avoid collisions, since SML-IF allows document aliases to be preserved across multiple interchanges.
An EPR-based SML reference scheme definition can specify an algorithm for generating target-complete identifiers for the purpose of SML-IF URI reference processing as described in SML-IF ([SML-IF], section 5.3.4).
Using the first case as an example, the SML-IF document producer generates a reference scheme instance based on information in the given instance of the EPR reference scheme that is sufficient to uniquely identify the target document or document fragment within the interchange model. Thus, this scheme specifies a document alias. For example, the SML reference from the example in section 3.2 may have a generated reference scheme instance with an algorithmically generated identifier as shown in the following:
<EnrolledCourse
xmlns:sml="http://www.w3.org/sml/2007/02"
xmlns:wsrp="http://docs.oasis-open.org/wsrf/rp-2"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
sml:ref="true">
<wsa:EndpointReference>
<wsa:Address>http://www.university.example.org</wsa:Address>
</wsa:EndpointReference>
<wsa:Action>
http://docs.oasis-open.org/wsrf/rpw-2/GetResourceProperty/GetResourcePropertyRequest
</wsa:Action>
<wsrp:GetResourceProperty
xmlns:tns="http://www.university.example.org/ns">
tns:PHY101
</wsrp:GetResourceProperty>
<newScheme:generatedWSRFIdentifier
xmlns:newScheme="http://www.example.com/myNewScheme_namespace"
xmlns:tns="http://www.university.example.org/ns">
http://www.university.example.org?GetResourceProperty=tns:PHY101
</newScheme:generatedWSRFIdentifier>
</EnrolledCourse>
The generated reference scheme instance is comprised by the newScheme:generatedWSRFIdentifier
element. (It is left as an exercise for the reader to trace through the algorithmic steps by which the
URI //www.university.example.org?GetResourceProperty=tns:PHY101
in the generated instance
can be computed from the preceding EPR Reference Scheme instance. Obviously,
the schema declaration of EnrolledCourse must allow additional
elements.)
This new reference scheme targets the document independently of how the document is made available through the Web service targeted by the preceding EPR-based Reference Scheme. The alias for this reference would be:
<alias>
http://www.university.example.org?GetResourceProperty=tns:PHY101
</alias>
Moreover, the process by which the identifier is resolved to the targeted document within the SML-IF document must be defined in the reference scheme definition similar to the way the resolution process for target-complete URI references is defined in SML-IF ([SML-IF], section 5.3.4). (This resolution algorithm is also left as an exercise for the reader.)
Note:
While the SML-IF consumer may recognize the reference scheme added by the SML-IF producer, we assume that the reference scheme will not be recognized by the SML model processor; thus the SML model processor will not attempt to resolve it. Should the SML model processor recognize the reference scheme (e.g., if the SML URI Reference Scheme is used to contain the document alias URI) and should the SML model processor attempt to resolve it by normal processing for that reference scheme, the reference may fail. Implementations may take steps to prevent this failure.
If the targeted service exposes only the targeted document, or, more precisely, the wsa:Address
element of the EPR uniquely identifies the
target document within the service, it may be possible to utilize the second
strategy above and generate a target-complete identifier to both identify and
serve as a document alias to the document or document fragment in the SML-IF
document. For example, if the service addressed at the URI http://www.university.example.org
in the University Course
Example exposes only that one document, a target-complete identifier in the
preceding example might be:
http://www.university.example.org#smlxpath1(/u:UniversityCourses/u:PHY101)
where UniversityCourses is the root element of the document and the u prefix represents the
http://www.university.example.org/ns namespace. It is not
expected that EPR-based SML reference schemes will typically be able to support
a target-complete identifier.
EPRs as values of the SML-IF document/locator element are subject to
the same semantic and processing requirements as are EPR-based reference
schemes. EPR document locators should be avoided if wide interoperability is
desired.
Because EPR-based SML reference schemes cannot in general be represented by SML URI Reference schemes, an SML-IF document containing EPR-based reference schemes cannot typically be referentially conforming as defined by the SML-IF Specification ([SML-IF], section 5.1). However, the two mechanisms defined in section 4.1.1 for generating aliases within the SML-IF document partially address interoperability issues at the level of the SML-IF document. Other considerations related to interoperability exists even if the reference schemes may be be defined with sufficient rigor to insure interoperability amongst those who adopt the reference scheme. These other issues include whether model documents are embedded or included by reference only in the SML-IF document and whether the SML-IF document is schema-complete ([SML-IF], section 4.5 ).
Definitions of EPR-based SML reference schemes should be sufficiently rigorous to support model interoperability amongst those vendors who agree to use a specific EPR-based reference scheme.
The following points summarize the issues that should be considered when defining an EPR-based SML reference scheme.
Consideration should be given to using the Framework Core described in section 2 and to adopting it as normative.
Consideration should be given to the operations and their parameters offered by the service interface through which the document or document fragment is accessed. The critical issue in defining an EPR-based SML reference scheme is how much of this special knowledge should be captured in the EPR-based SML reference scheme itself and how much might be otherwise made available to the model consumer.
If the EPR-based SML reference scheme will be used in the context of an SML-IF document, then a method for supporting SML-IF document aliases should be defined as part of the reference scheme definition. This note explored several strategies by which this issue could be addressed. These strategies involve:
Defining an algorithm for generating a reference scheme using a URI identifier with an explicitly stated resolution process, so that targeted documents can be identified within the SML-IF document by SML-IF aliasing mechanism, or
Defining an algorithm for generating a target-complete URI reference scheme so that the alias can be resolved by the mandated process for resolving SML URI Reference Schemes.
The author thanks the members of the SML Working Group, particularly John Arwe (IBM) and Len Charest, for providing input for this note, and Len Charest for a superb job of editing the final version.