The [WS-Addressing] recommendation defines a mechanism for associating metadata with an endpoint reference. This metadata can be used to define the "the behavior, policies and capabilities of the endpoint." This note defines the semantics of including Policies and Policy References as defined by [WS-Policy Framework] within the metadata property of an endpoint reference.
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 can be found in the W3C technical reports index at http://www.w3.org/TR/.
By publishing this document, W3C acknowledges that the Submitting Members have made a formal Submission request to W3C for discussion. Publication of this document by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the W3C Process. A W3C Team Comment has been published in conjunction with this Member Submission. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership. Please consult the requirements associated with Member Submissions of section 3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member Submissions.
1 Introduction
1.1 Notational
Conventions
2 Associating Policies with Endpoint References
2.1 Syntax
2.2 Scope of Effective
Policy
2.3 Calculating
Effective Policy for Other Policy Scopes
2.4 Validity
of Metadata Information
2.5 Security
Considerations
3 References
The [WS-Addressing] Recommendation defines an XML Infoset-based representation for specifying endpoint references. The XML syntax is as below:
<wsa:EndpointReference>
<wsa:Address>xs:anyURI</wsa:Address>
<wsa:ReferenceParameters>xs:any*</wsa:ReferenceParameters>?
<wsa:Metadata>xs:any*</wsa:Metadata>?
</wsa:EndpointReference>
Note that the Metadata element allows child elements from any namespace. Typically, these are used to include WSDL definitions that apply to that endpoint as well as Policies or Policy References that apply to that endpoint. The [WS-Addressing Metadata] specification defines how to include WSDL metadata in an EPR's metadata section.
This document defines how to include Policies and Policy References within the Metadata element as well as the semantics of such inclusion. We also discuss the semantics of Policies and Policy References directly included within the Metadata element in combination with Policies and Policy References included within WSDL definitions that are also included in the Metadata element.
This specification discusses how to associate Policies with endpoints. It does not discuss how such Policies can be used. The WS-Policy Working Group has published several documents ([WS-Policy Attachment], [WS-Policy Primer], [WS-Policy Guidelines]) that describe how Policies can be used.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [IETF RFC 2119].
This specification uses namespace prefixes that are listed in Table 1. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see [XML Information Set]).
| Prefix | Namespace | Definition |
|---|---|---|
| wsa | http://www.w3.org/2005/08/addressing | WS-Addressing |
| wsp | http://www.w3.org/ns/ws-policy | WS-Policy |
| xs | http://www.w3.org/2001/XMLSchema | XML Schema - Structures |
Namespace names of the general form "http://example.org/..." and "http://example.com/..." represent application or context-dependent URIs (see [IETF RFC 3986]).
All parts of this specification are normative, with the exception of examples and sections explicitly marked as "Non-Normative".
This specification uses XML syntax. Translation to the Infoset Model is straightforward.
This specification uses BNF-style conventions for specifying syntax: "?" denotes zero or one occurrence , "*" denotes zero or more occurrences, "+" one or more occurrences, "(" and ")" are used to form groups, and "|" represents choice.
Policy or Policy Reference MAY appear as direct children of the Metadata element.
<wsa:EndpointReference>
<wsa:Address>xs:anyURI</wsa:Address>
<wsa:ReferenceParameters>xs:any*</wsa:ReferenceParameters>
<wsa:Metadata>
( <wsp:Policy ...> ... </wsp:Policy> |
<wsp:PolicyReference ...> ... </wsp:PolicyReference> )? ... </wsa:Metadata> </wsa:EndpointReference>
If multiple alternatives are desired as part of this single Policy, the operators defined in [WS-Policy Framework] can be used to specify such a structure.
The scope of the Effective Policy calculated above is the endpoint referenced by the endpoint reference. Policy scope is defined in [WS-Policy Attachment].
As mentioned above, the Metadata element within an endpoint reference can contain, as children, WSDL (1.1 and 2.0) definitions in addition to Policies and Policy References. Details are discussed in Section 2.1 of [WS-Addressing Metadata]. These definitions can, in turn, have Policies and Policy References associated with them. Specifically, WSDL 2.0 Service and Interface and WSDL 1.1 Port Type and Service definitions can appear within the Metadata element of an Endpoint. The Effective Policy for the endpoint must be computed by combining the Policies and Policy References that appear as direct children of the Metadata element with the Policies an Policies References that are associated with WSDL definitions that appear within the Metadata element. The algorithms for computing the Effective Policy in such situations is discussed in Section 4 and Section 5 of [WS-Policy Attachment]
The [WS-Addressing] specification discusses caveats to the validity of Metadata information. These apply to Policies embedded within the Metadata element as discussed in this document and bear repeating in full:
The metadata embedded in an EPR is not necessarily a complete statement of the metadata pertaining to the endpoint. Moreover, while embedded metadata is necessarily valid at the time the EPR is initially created it may become stale at a later point in time.
To deal with conflicts between the embedded metadata of two EPRs that have the same [address], or between embedded metadata and metadata obtained from a different source, or to ascertain the current validity of embedded metadata, mechanisms that are outside of the scope of this specification, such as EPR life cycle information ... or retrieval of metadata from an authoritative source, SHOULD be used.
Section 5 of the [WS-Policy Framework] specification spells out in detail security considerations when using Policies. These apply equally to Policies specified within the Metadata element of an Endpoint Reference as discussed in this document.
Section 4 of the [WS-Addressing] specification spells out in detail security considerations when using endpoint references. These apply equally to Policies specified within the Metadata element of an endpoint reference as discussed in this document.