Web Services Policy 1.5 - Primer

2.1 Web Services Policy

Web services are being successfully used for interoperable solutions across various industries. One of the key reasons for interest and investment in Web services is that they are well-suited to enable service-oriented systems. XML-based technologies such as SOAP, XML Schema and WSDL provide a broadly-adopted foundation on which to build interoperable Web services. The WS-Policy and WS-PolicyAttachment specifications extend this foundation and offer mechanisms to represent the capabilities and requirements of Web services as Policies.

Service metadata is an expression of the visible aspects of a Web service, and consists of a mixture of machine- and human-readable languages. Machine-readable languages enable tooling. For example, tools that consume service metadata can automatically generate client code to call the service. Service metadata can describe different parts of a Web service and thus enable different levels of tooling support.

First, service metadata can describe the format of the payloads that a Web service sends and receives. Tools can use this metadata to automatically generate and validate data sent to and from a Web service. The XML Schema language is frequently used to describe the message interchange format within the SOAP message construct, i.e. to represent SOAP Body children and SOAP Header blocks.

Second, service metadata can describe the ‘how’ and ‘where’ a Web service exchanges messages, i.e. how to represent the concrete message format, what headers are used, the transmission protocol, the message exchange pattern and the list of available endpoints. The Web Services Description Language is currently the most common language for describing the ‘how’ and ‘where’ a Web service exchanges messages. WSDL has extensibility points that can be used to expand on the metadata for a Web service.

Third, service metadata can describe the capabilities and requirements of a Web service, i.e. representing whether and how a message must be secured, whether and how a message must be delivered reliably, whether a message must flow a transaction, etc. Exposing this class of metadata about the capabilities and requirements of a Web service enables tools to generate code modules for engaging these behaviors. Tools can use this metadata to check the compatibility of requesters and providers. Web Services Policy can be used to represent the capabilities and requirements of a Web service.

Web Services Policy is a machine-readable language for representing the capabilities and requirements of a Web service. These are called ‘policies’. Web Services Policy offers mechanisms to represent consistent combinations of capabilities and requirements, to determine the compatibility of policies, to name and reference policies and to associate policies with Web service metadata constructs such as service, endpoint and operation. Web Services Policy is a simple language that has four elements - Policy, All, ExactlyOne and PolicyReference - and two attributes - wsp:Optional and wsp:Ignorable.

2.2 Simple Message

Let us start by considering a SOAP Message in the example below.

<soap:Envelope>
  <soap:Header>
            <wsa:To>http://x.example.com/realquote</wsa:To>
            <wsa:Action>http://x.example.com/GetRealQuote</wsa:Action>
  </soap:Header>
  <soap:Body>…</soap:Body>
</soap:Envelope>

This message uses message addressing headers. The wsa:To and wsa:Action header blocks identify the destination and the semantics implied by this message respectively. (The prefix wsa is used here to denote the Web Services Addressing XML Namespace. B. XML Namespaces lists all the namespaces and prefixes that are used in this document.)

Let us look at a fictitious scenario used in this document to illustrate the features of the policy language. A Web service developer is building a client application that retrieves real time stock quote information from Company-X, Ltd. Company-X supplies real time data using Web services. The developer has Company-X’s advertised WSDL description of these Web services. Company-X requires the use of addressing headers for messaging. Just the WSDL description is not sufficient for the developer to enable the interaction between her client and these Web services. WSDL constructs do not indicate requirements such as the use of addressing.

(The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, places, or events is intended or should be inferred.)

Providers have the option to convey requirements, such as the use of addressing, through word-of-mouth and documentation – as they always have. To interact successfully with this service, the developer may have to read any related documentation, call someone at Company-X to understand the service metadata, or look at sample SOAP messages and infer such requirements or behaviors.

Web Services Policy is a machine-readable language for representing these Web service capabilities and requirements as policies. Policy makes it possible for providers to represent such capabilities and requirements in a machine-readable form. For example, Company-X may augment the service WSDL description with a policy that requires the use of addressing. The client application developer can use a policy-aware client that understands this policy and engages addressing automatically.

How does Company-X use policy to represent the use of addressing? The example below illustrates a policy expression that requires the use of addressing.

<Policy>
  <wsam:Addressing>…</wsam:Addressing>
</Policy>

The policy expression in the above example consists of a Policy main element and a child element wsam:Addressing. Child elements of the Policy element that are not from the Policy namespace are policy assertions. Company-X attaches the above policy expression to a WSDL binding description.

<wsdl:binding name="AddressingBinding" type="tns:RealTimeDataInterface" >
  <Policy>
    <wsam:Addressing>…</wsam:Addressing>
  </Policy>
  …
</wsdl:binding>
            

Policies can also be attached to WSDL using references (See 2.10 Referencing Policy Expressions.)

The wsam:Addressing element is a policy assertion. (The prefix wsam is used here to denote the Web Services Addressing – Metadata XML Namespace.) This assertion identifies the use of Web Services Addressing information headers. A policy-aware client can recognize this policy assertion, engage addressing automatically, and use headers such as wsa:To and wsa:Action in SOAP Envelopes.

It is important to understand the association between the SOAP message and policy expression in the above example. As you can see by careful examination of the message, there is no reference to any policy expression. Just as WSDL does not require a message to reference WSDL constructs (such as port, binding and portType), Web Services Policy does not require a message to reference a policy expression though the policy expression describes the message.

2.3 Secure Message

In addition to requiring the use of addressing, Company-X requires the use of transport-level security for protecting messages.

<soap:Envelope>
  <soap:Header>
    <wss:Security soap:mustUnderstand="1" >
      <wsu:Timestamp wsu:Id="_0">
       <wsu:Created>2006-01-19T02:49:53.914Z</u:Created>
       <wsu:Expires>2006-01-19T02:54:53.914Z</u:Expires>
      </wsu:Timestamp>
    </wss:Security>
   <wsa:To>http://x.example.com/quote</wsa:To>
   <wsa:Action>http://x.example.com/GetRealQuote</wsa:Action>
  </soap:Header>
  <soap:Body>…</soap:Body>
</soap:Envelope>

The SOAP message in the example above includes security timestamps that express creation and expiration times of this message. Company-X requires the use of security timestamps and transport-level security - such as HTTPS – for protecting messages. (The prefixes wss and wsu are used here to denote the Web Services Security and Utility namespaces.)

Similar to the use of addressing, Company-X indicates the use of transport-level security using a policy expression. The example below illustrates a policy expression that requires the use of addressing and transport-level security for securing messages.

<Policy>
  <wsam:Addressing>…</wsam:Addressing>
  <sp:TransportBinding>…</sp:TransportBinding>
</Policy>

The sp:TransportBinding element is a policy assertion. (The prefix sp is used here to denote the Web Services Security Policy XML Namespace.) This assertion identifies the use of transport-level security – such as HTTPS - for protecting messages. Policy-aware clients can recognize this policy assertion, engage transport-level security for protecting messages and include security timestamps in SOAP Envelopes.

The client application developer can use a policy-aware client that recognizes this policy expression and engages both addressing and transport-level security automatically.

For the moment, let us set aside the contents of the sp:TransportBinding policy assertion and consider its details in a later section.

2.4 Other Assertions

Thus far, we explored how Company-X uses policy expressions and assertions for representing behaviors that must be engaged for a Web service interaction. What is a policy assertion? What role does it play? In brief, a policy assertion is a piece of service metadata, and it identifies a domain (such as messaging, security, reliability and transaction) specific behavior that is a requirement. Company-X uses a policy assertion to convey a condition under which they offer a Web service. A policy-aware client can recognize policy assertions and engage these behaviors automatically.

Providers, like Company-X, have the option to combine behaviors for an interaction from domains such as messaging, security, reliability and transactions. Using policy assertions, providers can represent these behaviors in a machine-readable form. Web service developers can use policy-aware clients that recognize these assertions and engage these behaviors automatically.

Who defines policy assertions? Where are they? Policy assertions are defined by Web services developers, product designers, protocol authors and users. Like XML Schema libraries, policy assertions are a growing collection. Several WS-* protocol specifications and applications define policy assertions:

• Web Services Security Policy [WS-SecurityPolicy]

• Web Services Reliable Messaging Policy [Web Services Reliable Messaging Policy Assertion]

• Web Services Atomic Transaction [Web Services Atomic Transaction]

• Web Services Business Activity Framework [Web Services Business Activity Framework]

• Devices Profile for Web Services [Devices Profile for Web Services]

• …

2.5 Combining Policy Assertions

Policy assertions can be combined in different ways to express consistent combinations of behaviors (capabilities and requirements). There are three policy operators for combining policy assertions: Policy, All and ExactlyOne (the Policy operator is a synonym for All).

Let us consider the All operator first. The policy expression in the example below requires the use of addressing and transport-level security. There are two policy assertions. These assertions are combined using the All operator. Combining policy assertions using the Policy or All operator means that all the behaviors represented by these assertions are required.

<All>
  <wsam:Addressing>…</wsam:Addressing>
  <sp:TransportBinding>…</sp:TransportBinding>
</All>

In addition to requiring the use of addressing, Company-X allows either the use of transport- or message-level security for protecting messages. Web Services Policy language can indicate this choice of behaviors in a machine-readable form. To indicate the use of message-level security for protecting messages, Company-X uses the sp:AsymmetricBinding policy assertion (see the example below).

<sp:AsymmetricBinding>…</sp:AsymmetricBinding>

The sp:AsymmetricBinding element is a policy assertion. (The prefix sp is used here to denote the Web Services Security Policy namespace.) This assertion identifies the use of message-level security – such as WS-Security 1.0 - for protecting messages. Policy-aware clients can recognize this policy assertion, engage message-level security for protecting messages and use headers such as wss:Security in SOAP Envelopes.

To allow the use of either transport- or message-level security, Company-X uses the ExactlyOne policy operator. Policy assertions combined using the ExactlyOne operator requires exactly one of the behaviors represented by the assertions. The policy expression in the example below requires the use of either transport- or message-level security for protecting messages.

<ExactlyOne>
  <sp:TransportBinding>…</sp:TransportBinding>
  <sp:AsymmetricBinding>…</sp:AsymmetricBinding>
</ExactlyOne>

Company-X requires the use of addressing and requires the use of either transport- or message-level security for protecting messages. They represent this combination using the All and ExactlyOne operators. Policy operators can be mixed to represent different combinations of behaviors (capabilities and requirements). The policy expression in the example below requires the use of addressing and one of transport- or message-level security for protecting messages.

<All>
  <wsam:Addressing>…</wsam:Addressing>
  <ExactlyOne>
    <sp:TransportBinding>…</sp:TransportBinding>
    <sp:AsymmetricBinding>…</sp:AsymmetricBinding>
  </ExactlyOne>
</All>

Using this policy expression, Company-X gives the choice of mechanisms for protecting messages to clients (or requesters).

2.6 Optional Policy Assertion

Through a customer survey program, Company-X learns that a significant number of their customers prefer to use the Optimized MIME Serialization (as defined in the MTOM specification) for sending and receiving messages. Company-X adds optional support for the Optimized MIME Serialization and expresses this optional behavior in a machine-readable form.

To indicate the use of optimization using the Optimized MIME Serialization, Company-X uses the mtom:OptimizedMimeSerialization policy assertion (see the example below).

<mtom:OptimizedMimeSerialization />

The mtom:OptimizedMimeSerialization element is a policy assertion. (The prefix mtom is used here to denote the Optimized MIME Serialization Policy namespace.) This assertion identifies the use of MIME Multipart/Related serialization as required for request and response messages. Policy-aware clients can recognize this policy assertion and engage Optimized MIME Serialization for messages. The semantics of this assertion are reflected in messages: they use an optimized wire format (MIME Multipart/Related serialization).

Like Company-X’s optional support for Optimized MIME Serialization, there are behaviors that may be engaged (in contrast to must be engaged) for a Web service interaction. A service provider will not fault if these behaviors are not engaged. Policy assertions can be marked optional to represent behaviors that may be engaged for an interaction. A policy assertion is marked as optional using the wsp:Optional attribute. Optional assertions represent the capabilities of the service provider as opposed to the requirements of the service provider.

In the example below, the Optimized MIME Serialization policy assertion is marked optional. This policy expression allows the use of optimization and requires the use of addressing and one of transport- or message-level security. If a client sends an optimized (MTOM) message, this will be indicated by characteristics associated by using such an optimized message, including a wire format that is a Multipart/Related message and a content-type header of "application/xop+xml" for the outer package. In this case, the response message will also be optimized, also having a Multipart/Related message and content-type header of "application/xop+xml". Note that when optimized messages are used, the Multipart/Related message can have a single part containing the primary SOAP envelope.

<All>
  <mtom:OptimizedMimeSerialization wsp:Optional="true"/>
  <wsam:Addressing>…</wsam:Addressing>
  <ExactlyOne>
    <sp:TransportBinding>…</sp:TransportBinding>
    <sp:AsymmetricBinding>…</sp:AsymmetricBinding>
  </ExactlyOne>
</All>

Company-X is able to meet their customer needs by adding optional support for the Optimized MIME Serialization. Optional support is outlined in section 3.4 Web Services Policy 1.5 - Framework and detailed in section 4.5.2, Web Services Policy 1.5 - Guidelines for Policy Assertion Authors, specifically for Optimized MIME Serialization. An optional policy assertion represents a behavior that may be engaged. When that policy assertion is absent from a policy alternative (See section 3.2, Web Services Policy 1.5 - Framework), a policy-aware client should not conclude anything (other than ‘no claims’) about the absence of that policy assertion. See section 2.11 Attaching Policy Expressions to WSDL on the absence of policy expressions.

2.7 Ignorable Policy Expressions

Suppose Company-X decides that it will log SOAP messages sent and received in an exchange. This behavior has no direct impact on the messages sent on the wire, and does not affect interoperability. Some parties might have a concern about such logging and might decide not to interact with Company-X knowing that such logging is performed. To address this concern, Company-X includes a Logging assertion in its policy to enable such parties to be aware of logging. By marking the Logging assertion with the wsp:Ignorable attribute with a value of "true" Company-X indicates that a requester may choose to either ignore such assertions or to consider them as part of policy intersection. An assertion that may be ignored for policy intersection is called an ignorable assertion.

The wsp:Ignorable attribute allows providers to clearly indicate which policy assertions indicate behaviors that don’t manifest on the wire and may not be of concern to a requester when determining policy compatibility. Using the wsp:Optional attribute would be incorrect in this scenario, since it would indicate that the behavior would not occur if the alternative without the assertion were selected.

<log:Logging wsp:Ignorable="true" />

(The log: prefix is used here to denote a hypothetical example namespace for this example logging policy assertion.)

The attribute wsp:Ignorable is of type xs:boolean. Omitting this attribute is semantically equivalent to including it with a value of "false".

The use of the wsp:Ignorable attribute has no impact on normalization. Assertions marked with the wsp:Ignorable attribute remain marked with the wsp:Ignorable attribute after normalization. Please note that the impact of the ignorable attribute is at the discretion of policy consumers through selection of "lax" or "strict" mode (See 3.4.1 Strict and Lax Policy Intersection). Therefore ignorable assertions may have an effect on determining compatibility of provider and consumer policies.

2.8 Marking Assertions both Optional and Ignorable

As described in the sections above and in Section 3.4.1 Strict and Lax Policy Intersection, the WS-Policy 1.5 specification defines two attributes that can be used to mark an assertion: wsp:Optional and wsp:Ignorable.

The WS-Policy Framework allows a policy assertion to be marked with both "Optional" and "Ignorable" attributes simultaneously. The presence of "@wsp:optional=true" on an assertion is a syntactic compact form for two alternatives in normal form, one with the assertion and the other without the assertion. Hence syntactically marking an assertion "A" with both the @wsp:Optional and @wsp:Ignorable with the value of "true" for both, is equivalent to two alternatives; one where the assertion A exists with @wsp:Ignorable=true and the second where the assertion A does not exist.

2.9 Nested Policy Expressions

In the previous sections, we considered two security policy assertions. In this section, let us look at one of the security policy assertions in a little more detail.

As you would expect, securing messages is a complex usage scenario. Company-X uses the sp:TransportBinding policy assertion to indicate the use of transport-level security for protecting messages. Just indicating the use of transport-level security for protecting messages is not sufficient. To successfully interact with Company-X’s Web services, the developer must also know what transport token to use, what particular secure transport to use, what specific algorithm suite to use for performing cryptographic operations, etc. The sp:TransportBinding policy assertion can represent these dependent behaviors. In this section, let us look at how to capture these dependent behaviors in a machine-readable form.

A policy assertion – like the sp:TransportBinding - identifies a visible domain specific behavior that is a requirement. Given an assertion, there may be other dependent behaviors that need to be enumerated for a Web Service interaction. In the case of the sp:TransportBinding policy assertion, Company-X needs to identify the use of a transport token, a secure transport, an algorithm suite for performing cryptographic operations, etc. A nested policy expression can be used to enumerate such dependent behaviors.

What is a nested policy expression? A nested policy expression is a policy expression that is a child element of a policy assertion element. A nested policy expression further qualifies the behavior of its parent policy assertion.

In the example below, the child Policy element is a nested policy expression and further qualifies the behavior of the sp:TransportBinding policy assertion. The sp:TransportToken is a nested policy assertion of the sp:TransportBinding policy assertion. The sp:TransportToken assertion requires the use of a specific transport token and further qualifies the behavior of the sp:TransportBinding policy assertion (which already requires the use of transport-level security for protecting messages).

<sp:TransportBinding>
  <Policy>
    <sp:TransportToken>
      <Policy>
        <sp:HttpsToken>
          <wsp:Policy/>
        </sp:HttpsToken>
      </Policy>
    </sp:TransportToken>
    <sp:AlgorithmSuite>
      <Policy>
        <sp:Basic256Rsa15/>
      </Policy>
    </sp:AlgorithmSuite>
    …
  </Policy>
</sp:TransportBinding>

The sp:AlgorithmSuite is a nested policy assertion of the sp:TransportBinding policy assertion. The sp:AlgorithmSuite assertion requires the use of the algorithm suite identified by its nested policy assertion (sp:Basic256Rsa15 in the example above) and further qualifies the behavior of the sp:TransportBinding policy assertion.

Setting aside the details of using transport-level security, Web service developers can use a policy-aware client that recognizes this policy assertion and engages transport-level security and its dependent behaviors automatically. That is, the complexity of security usage is absorbed by a policy-aware client and hidden from these Web service developers.

In another example, WS-Security Policy defines a sp:HttpToken assertion to contain three possible nested elements, sp:HttpBasicAuthentication, sp:HttpDigestAuthentication and sp:RequireClientCertificate. When the HttpToken is used with an empty nested policy in a policy expression by a provider, it will indicate that none of the dependent behaviors namely authentication or client certificate is required. A non-anonymous client who requires authentication or client certificate will not be able to use this provider solely on the basis of policy intersection algorithm alone.

<sp:TransportToken>
    <wsp:Policy>
      <sp:HttpsToken> 
       <wsp:Policy/> 
      </sp:HttpsToken> 
    </wsp:Policy>
</sp:TransportToken>

2.10 Referencing Policy Expressions

Company-X has numerous Web service offerings that provide different kinds of real-time quotes and book information on securities such as GetRealQuote, GetRealQuotes and GetExtendedRealQuote. To accommodate the diversity of Company-X’s customers, Company-X supports multiple WSDL bindings for these Web services. Company-X provides consistent ways to interact with their services and wants to represent these capabilities and requirements consistently across all of their offerings without duplicating policy expressions multiple times. How? It is simple - a policy expression can be named and referenced for re-use.

Section 2.2 Simple Message, showed how a policy expression can be attached directly to a binding inline. A single policy expression may be used in several parts of a WSDL document. In this case it is desirable to use references to the policy expression rather than to directly inline the policy expression.

A policy expression may be identified by an IRI and referenced for re-use as a standalone policy or within another policy expression. There are three mechanisms to identify a policy expression: the wsu:Id, xml:id and Name attributes. A PolicyReference element can be used to reference a policy expression identified using either of these mechanisms.

<Policy wsu:Id=”common”>
  <mtom:OptimizedMimeSerialization wsp:Optional="true"/>
  <wsam:Addressing>…</wsam:Addressing>
</Policy>

In the example above, the wsu:Id attribute is used to identify a policy expression. The value of the wsu:Id attribute is an XML ID. The relative IRI for referencing this policy expression (within the same document) is #common. If the policy document IRI is http://x.example.com/policy.xml then the absolute IRI for referencing this policy expression is http://x.example.com/policy.xml#common. (The absolute IRI is formed by combining the document IRI, # and the value of the wsu:Id attribute.)

In addition to the Example 2-12, Company-X could have used either the xml:id or wsu:Id. An example of the use of xml:id similar to that of wsu:Id is shown in Example 2-13.

<Policy xml:id=”common”>
  <mtom:OptimizedMimeSerialization wsp:Optional="true"/>
  <wsam:Addressing>…</wsam:Addressing>
</Policy>

Conditions and constraints on the use of the |xml:id| attribute in conjunction with Canonical XML 1.0 are specified in Appendix C of XML ID and are further detailed in C14N 1.0 Note. Significant care is suggested in the use of xml:id.

For re-use, a PolicyReference element can be used to reference a policy expression as a standalone policy or within another policy expression. The example below is a policy expression that re-uses the common policy expression above.

<PolicyReference URI="#common"/>

For referencing a policy expression within the same XML document, Company-X uses the wsu:Id attribute for identifying a policy expression and an IRI to this ID value for referencing this policy expression using a PolicyReference element.

The example below is a policy expression that re-uses the common policy expression within another policy expression. This policy expression requires the use of addressing, one of transport- or message-level security for protecting messages and allows the use of optimization.

<Policy wsu:Id=”secure”>
  <All>
    <PolicyReference URI="#common"/>
    <ExactlyOne>     
      <sp:TransportBinding>…</sp:TransportBinding>
      <sp:AsymmetricBinding>…</sp:AsymmetricBinding >
    </ExactlyOne>
  </All>
</Policy>

The Name attribute is an alternate mechanism to identify a policy expression. The value of the Name attribute is an absolute IRI and is independent of the location of the XML document where the identified policy expression resides in. As such, referencing a policy expression using the Name attribute relies on additional out of band information and is outside the scope of the Web Services Policy Framework and Attachment (See 3.6 Policy Retrieval). In the example below, the Name attribute identifies the policy expression. The IRI of this policy expression is http://x.example.com/policy/common.

<Policy Name=”http://x.example.com/policy/common”>
  <mtom:OptimizedMimeSerialization wsp:Optional="true"/>
  <wsam:Addressing>…</wsam:Addressing>
</Policy>

The example below is a policy expression that re-uses the common policy expression above.

<PolicyReference URI="http://x.example.com/policy/common"/>

The following example shows a policy expression identified using a UDDI key, which may refer to a tModel that references the reusable policy expression as described in section 6.3 of Web Services Policy Attachment.

<PolicyReference URI="uddi:3bed4710-1f46-11dc-899e-391cf3b1899c"/>

The reusable policy expression could be registered in UDDI using a tModel as shown below

<tModel tModelKey="uddi:3bed4710-1f46-11dc-899e-391cf3b1899c">
  <name>…</name>
  <description xml:lang="EN">
Policy Expression for example's Web services
  </description>
  <overviewDoc>
    <description xml:lang="EN">Web Services Policy Expression</description>
    <overviewURL>http://repository.example.com/policy/common</overviewURL>
  </overviewDoc>
  <categoryBag>
    <keyedReference
      keyName="Reusable policy Expression"
      keyValue="policy"
      tModelKey="uddi:w3.org:ws-policy:v1.5:attachment:policytypes" />
    <keyedReference
      keyName="Policy Expression for example's Web services"
      keyValue="http://x.example.com/policy/common"
      tModelKey="uddi:w3.org:ws-policy:v1.5:attachment:remotepolicyreference" />
  </categoryBag>
</tModel>

As policy expressions are composed from other policy expressions and assertions from different domains are used in a policy expression, complex expressions will emerge. Naming parts of complex expressions for reuse and building more complex policies through referencing enables building more complicated policy scenarios easily. This approach enables the association of additional policy subjects to identified policy expressions. It also promotes manageability of the expressions as they are uniquely identified and allows profiles for common scenarios to be developed. Note that when a named expression has assertions that contains parameterized expressions, care must be given to ensure that the parameterized content is statically available to enable reuse.

2.11 Attaching Policy Expressions to WSDL

A majority of Company-X’s customers use WSDL for building their client applications. Company-X leverages this usage by attaching policy expressions to the WSDL binding descriptions.

In the example below, the SecureBinding WSDL binding description defines a binding for an interface that provides real-time quotes and book information on securities. (The prefixes wsdl and tns are used here to denote the Web Services Description language XML namespace and target namespace of this WSDL document.) To require the use of security for these offerings, Company-X attaches the secure policy expression in the previous section to this binding description. The WSDL binding element is a common policy attachment point. The secure policy expression attached to the SecureBinding WSDL binding description applies to any message exchange associated with any port that supports this binding description. This includes all the message exchanges described by operations in the RealTimeDataInterface.

<wsdl:binding name="SecureBinding" type="tns:RealTimeDataInterface" >
  <PolicyReference URI="#secure" />
  <wsdl:operation name="GetRealQuote">…</wsdl:operation>
  …
</wsdl:binding>

In addition to providing real-time quotes and book information on securities, Company-X provides other kinds of data through Web services such as quotes delayed by 20 minutes and security symbols through Web services (for example GetDelayedQuote, GetDelayedQuotes, GetSymbol and GetSymbols). Company-X does not require the use of security for these services, but requires the use of addressing and allows the use of optimization.

<wsdl:binding name="OpenBinding" type="tns:DelayedDataInterface" >
  <PolicyReference URI="#common" />
  <wsdl:operation name="GetDelayedQuote">…</wsdl:operation>
  …
</wsdl:binding>

In the example above, the OpenBinding WSDL binding description defines a binding for an interface that provides other kinds of data such as quotes delayed by 20 minutes and security symbols. To require the use of addressing and allow the use of optimization, Company-X attaches the common policy expression in the previous section to this binding description. As we have seen in the SecureBinding case, the common policy expression attached to the OpenBinding WSDL binding description applies to any message exchange associated with any port that supports this binding description. This includes all the message exchanges described by operations in the DelayedDataInterface.

As mentioned earlier, providers have the option to convey requirements, such as the use of addressing or security, through word-of-mouth and documentation – as they always have. The absence of policy expressions, for example, in a WSDL document does not indicate anything about the capabilities and requirements of a service. The service may have capabilities and requirements that can be expressed as policy expressions, such as the use of addressing, security and optimization. Or, the service may not have such capabilities and requirements. A policy aware client should not conclude anything about the absence of policy expressions.

Service providers, like Company-X, can preserve and leverage their investments in WSDL and represent the capabilities and requirements of a Web service as policies. A WSDL document may specify varying behaviors across Web service endpoints. Web service developers can use a policy-aware client that recognizes these policy expressions in WSDL documents and engages behaviors automatically for each of these endpoints. Any complexity of varying behaviors across Web service endpoints is absorbed by a policy-aware client or tool and hidden from these Web service developers.

2.12 Policy Automates Web Services Interaction

As you have seen, Web Services Policy is a simple language that has four elements - Policy, All, ExactlyOne and PolicyReference - and two attributes - wsp:Optional and wsp:Ignorable. In practice, service providers, like Company-X, use policy expressions to represent combinations of capabilities and requirements. Web service developers use policy-aware clients that understand policy expressions and engage the behaviors represented by providers automatically. A sizable amount of complexity is absorbed by policy-aware clients (or tools) and is invisible to these Web service developers.

Web Services Policy extends the foundation on which to build interoperable Web services, hides complexity from developers and automates Web service interactions.

3.1 Policy Expression

A policy expression is the XML representation and interoperable form of a Web Services Policy. A policy expression consists of a Policy wrapper element and a variety of child and descendant elements. Child and descendent elements from the policy language are Policy, All, ExactlyOne and PolicyReference. Other child elements of Policy, All and ExactlyOne are policy assertions. (The Policy element plays two roles: wrapper element and operator.) Policy assertions can contain a nested policy expression. Policy assertions can also be marked optional to represent behaviors that may be engaged (capabilities) for an interaction. The optional marker is the wsp:Optional attribute which is placed on a policy assertion element.

Let us take a closer look at Company-X’s policy expression (see below) from the previous section.

<Policy>
  <All>
    <mtom:OptimizedMimeSerialization wsp:Optional="true"/>
    <wsam:Addressing>…</wsam:Addressing>
    <ExactlyOne>
     <sp:TransportBinding>…</sp:TransportBinding>
     <sp:AsymmetricBinding>…</sp:AsymmetricBinding >
    </ExactlyOne>
  </All>
</Policy>

The Policy element is the wrapper element. The All and ExactlyOne elements are the policy operators. All other child elements of the All and ExactlyOne elements are policy assertions from domains such as messaging, addressing, security, reliability and transactions.

3.2 Normal Form for Policy Expressions

Web Services Policy language defines two forms of policy expressions: compact and normal form. Up to this point, we have used the compact form. The compact form is less verbose than the normal form. The compact form is useful for authoring policy expressions. The normal form is an intuitive representation of the policy data model. We will look into the policy data model in the next section.

The normal form uses a subset of constructs used in the compact form and follows a simple outline for its XML representation:

<Policy>
  <ExactlyOne>
    <All>
     <x:AssertionA>…</x:AssertionA>
     <y:AssertionB>…</y:AssertionB>
      …
    </All>
    <All>
     <x:AssertionA>…</x:AssertionA>
     <z:AssertionC>…</z:AssertionC>
      …
    </All>
   … 
  </ExactlyOne>
<Policy/>

The normal form consists of a Policy wrapper element and has one child ExactlyOne element. This ExactlyOne element has zero or more All child elements. Each of these All elements has zero or more policy assertions. The PolicyReference element and wsp:Optional attribute are not used in the normal form. And, a nested policy expression in the normal form has at most one policy alternative.

The normal form represents a policy as a collection of policy alternatives and a policy alternative as a collection of policy assertions in a straight-forward manner.

The example below is a policy expression in the normal form. This expression contains two policy alternatives: one that requires the use of transport-level security and the other that requires the use of message-level security for protecting messages.

<Policy>
  <ExactlyOne>
    <All>
     <sp:TransportBinding>…</sp:TransportBinding>
    </All>
    <All>
     <sp:AsymmetricBinding>…</sp:AsymmetricBinding >
    </All>
  </ExactlyOne>
</Policy>

A policy expression in the compact form can be converted to the normal form. Web Services Policy language describes the algorithm for this conversion.

Let us re-consider Company-X’s policy expression (see the example below). Company-X requires the use of addressing and either transport- or message-level security and allows the use of optimization. This policy expression is in the compact form and has four policy alternatives for requesters:

1. Requires the use of addressing and transport-level security

2. Requires the use of addressing and message-level security

3. Requires the use of optimization, addressing and transport-level security and

4. Requires the use of optimization, addressing and message-level security.

<Policy wsu:Id=”secure”>
  <All>
    <PolicyReference URI=”#common”/>
    <ExactlyOne>
     <sp:TransportBinding>…</sp:TransportBinding>
     <sp:AsymmetricBinding>…</sp:AsymmetricBinding >
    </ExactlyOne>
  </All>
</Policy>

<Policy wsu:Id=”common”>
  <mtom:OptimizedMimeSerialization wsp:Optional="true"/>
  <wsam:Addressing>…</wsam:Addressing>
</Policy>

Let us look at the normal form for this policy expression. The example below is Company-X’s policy expression in the normal form. As you can see, the compact form is less verbose than the normal form. The normal form represents a policy as a collection of policy alternatives. Each of the All operators is a policy alternative. There are four policy alternatives in the normal form. These alternatives map to list items (1) through (4) above.

<Policy>
  <ExactlyOne>
    <All> <!-- - - - - - - - - - - - - - Policy Alternative (a) -->
       <wsam:Addressing>…</wsam:Addressing>
       <sp:TransportBinding>…</sp:TransportBinding>
    </All>
    <All> <!-- - - - - - - - - - - - - - Policy Alternative (b) -->
      <wsam:Addressing>…</wsam:Addressing>
      <sp:AsymmetricBinding>…</sp:AsymmetricBinding >
    </All>
    <All> <!-- - - - - - - - - - - - - - Policy Alternative (c) -->
      <mtom:OptimizedMimeSerialization />
       <wsam:Addressing>…</wsam:Addressing>
       <sp:TransportBinding>…</sp:TransportBinding>
    </All>
    <All> <!-- - - - - - - - - - - - - - Policy Alternative (d) -->
      <mtom:OptimizedMimeSerialization />
      <wsam:Addressing>…</wsam:Addressing>
      <sp:AsymmetricBinding>…</sp:AsymmetricBinding>
    </All>
  </ExactlyOne>
</Policy>

The wsp:Optional attribute, nested policy expression and PolicyReference element are converted to their corresponding normal form. The wsp:Optional attribute converts to two alternatives, one with and the other without the assertion. A policy alternative containing an assertion with a nested policy expression that has multiple policy alternatives converts to multiple policy alternatives where the assertion contains a nested policy expression that has at most one policy alternative.

The PolicyReference element is replaced with its referenced policy expression. See section 3.6 Policy Retrieval for more details on how to retrieve referenced policy expressions.

3.3 Policy Data Model

In the previous section, we considered the normal form for policy expressions. As we discussed, the normal form represents a policy as a collection of policy alternatives. In this section, let us look at the policy data model.

Company-X uses a policy to convey the conditions for an interaction. Policy-aware clients, like the one used by the developer in our example (as explained earlier in 2. Basic Concepts: Policy Expression), view a policy as an unordered collection of zero or more policy alternatives. A policy alternative is an unordered collection of zero or more policy assertions. A policy alternative represents a collection of behaviors or requirements or conditions for an interaction. In simple words, each policy alternative represents a set of conditions for an interaction. The diagram below describes the policy data model.

Figure 3-1. WS-Policy Data Model

A policy-aware client uses a policy to determine whether one of these policy alternatives (i.e. the conditions for an interaction) can be met in order to interact with the associated Web Service. Such clients may choose any of these policy alternatives and must choose exactly one of them for a successful Web service interaction. Clients may choose a different policy alternative for a subsequent interaction. It is important to understand that a policy is a useful piece of metadata in machine-readable form that enables tooling, yet is not required for a successful Web service interaction. Why? Web service developers could use the documentation, talk to the service providers, or look at message traces to infer these conditions for an interaction. Developers continue to have these options, as they always had.

As we discussed, a policy assertion identifies a domain specific behavior or requirement or condition. A policy assertion has a QName that identifies its behavior or requirement or condition. In the XML representation, the QName of the assertion element is the QName of the policy assertion. A policy assertion may contain assertion parameters and a nested policy.

The assertion parameters are the opaque payload of an assertion. Parameters carry additional useful pieces of information necessary for engaging the behavior described by an assertion. In the XML representation, the child elements and attributes of an assertion excluding the child elements and attributes from the WS-Policy language XML namespace name, are the assertion parameters. For example @wsp:Optional and @wsp:Ignorable are not assertion parameters.

We considered nested policy expressions in the context of a security usage scenario. Let us look at its shape in the policy data model. A nested policy expression is a policy expression that is a child element of an assertion. In the normal form, a nested policy expression has at most one policy alternative. The policy alternative in a nested policy expression represents a collection of associated or dependent behaviors, requirements or conditions that qualify its parent policy assertion.

A policy-aware client supports a policy assertion if the client engages the behavior or requirement or condition indicated by the assertion. A policy-aware client supports a policy alternative if the client engages the behaviors represented by all the assertions in the alternative. A policy-aware client supports a policy if the client engages the behaviors represented by at least one of the policy alternatives.

In the previous section, we saw how the normal form of a policy expression represents a policy as a collection of policy alternatives. By policy language design, the normal form of a policy expression directly maps to the policy data model:

• Each child element of Policy/ExactlyOne/All maps to a policy assertion.

• Each Policy/ExactlyOne/All element and policy assertions which correspond to its children map to a policy alternative.

• The Policy/ExactlyOne element maps to a collection of policy alternatives.

• The Policy wrapper element and policy alternatives which correspond to the Policy/ExactlyOne element map to a policy.

The diagram below describes this mapping from the normal form of a policy expression to the policy data model.

Figure 3-2. Mapping from Normal Form to Policy Data Model

3.4 Compatible Policies

A provider, like Company-X, and a requester, like the policy-aware client used in our example, may represent their capabilities and requirements for an interaction as policies and want to limit their message exchanges to mutually compatible policies. Web Services Policy defines an intersection mechanism for selecting compatible policy alternatives when there are two or more policies.

The example below is a copy of Company-X’s policy expression (from 3.2 Normal Form for Policy Expressions). As we saw before, Company-X offers four policy alternatives. Of them, one of the policy alternatives requires the use of addressing and transport-level security.

<Policy>
  <ExactlyOne>
    <All> <!-- - - - - - - - - -  Company-X’s Policy Alternative (a) -->
       <!-- - - - - - - - - - - - - - - - - - Policy Assertion (c1) -->
       <wsam:Addressing>…</wsam:Addressing>
       <!-- - - - - - - - - - - - - - - - - - Policy Assertion (c2) -->
      <sp:TransportBinding>…</sp:TransportBinding>
    </All>
    …
  </ExactlyOne>
</Policy>

The client application developer's organization requires the use of addressing and transport-level security for any interaction with Company-X’s Web services. The developer represents these behaviors using a policy expression illustrated in the example below in normal form. This policy expression contains one policy alternative that requires the use of addressing and transport-level security.

<Policy>
  <ExactlyOne>
    <All> <!-- - - - - - - - - - - - - -  Client’s Policy Alternative -->
       <!-- - - - - - - - - - - - - - - - - - Policy Assertion (t1) -->
     <sp:TransportBinding>…</sp:TransportBinding>
       <!-- - - - - - - - - - - - - - - - - - Policy Assertion (t2) -->
      <wsam:Addressing>…</wsam:Addressing>
    </All>
  </ExactlyOne>
</Policy>

The developer lets her policy-aware client select a compatible policy alternative in Company-X’s policy. How does this client select a compatible policy alternative? It is simple – it uses the policy intersection. That is, the policy-aware client uses these two policy expressions (the client’s and Company-X’s) and the policy intersection to select a compatible policy alternative for this interaction. Let us look at the details of policy intersection.

For two policy assertions to be compatible they must have the same QName. And, if either assertion has a nested policy, both assertions must have a nested policy and the nested policies must be compatible. For example, policy assertions (c2) and (t1) have the same QName, sp:TransportBinding. For this discussion, let us assume that these two assertions have compatible nested policies. These two assertions are compatible because they have the same QName and their nested policies are compatible.

Two policy alternatives are compatible if each policy assertion in one alternative is compatible with a policy assertion in the other and vice-versa. For instance in Examples 3.6 and 3.7, policy assertions (c1) and (c2) in Company-X’s policy alternative are compatible with policy assertions (t2) and (t1) in the client’s policy alternative. Company-X’s policy alternative (a) and the client’s policy alternative are compatible because assertions in these two alternatives are compatible.

Two policies are compatible if a policy alternative in one is compatible with a policy alternative in the other. For example, Company-X’s policy alternative (a) is compatible with the client’s policy alternative. Company-X’s policy and the client’s policy are compatible because one of Company-X’s policy alternative is compatible with the client’s policy alternative.

For this interaction, the developer’s policy-aware client can use policy alternative (a) to satisfy Company-X’s conditions or requirements.

Similarly, policy intersection can be used to check if providers expose endpoints that conform to a standard policy. For example, a major retailer might require all their supplier endpoints to be compatible with an agreed upon policy.

Consider a similar scenario between Company X and the client where nested policy expressions exist in the policy alternatives. The nested policy expressions are compared for compatibility in the context of their parent policy assertions during policy intersection. For example, take these two incompatible policies in Examples 3.8 and 3.9:

Company X    
(P001)<wsp:Policy wsu:Id="..." >
(P002)  <wsp:ExactlyOne>
(P003)    <wsp:All>
(P004)      <sp:EndorsingSupportingTokens 
(P005)        xmlns:sp="..."> <!-- parent policy assertion a -->      
(P006)        <wsp:Policy> <!-- nested policy a1  -->
(P007)          <sp:X509Token  sp:IncludeToken=".../IncludeToken/AlwaysToRecipient"> 
(P008)            <wsp:Policy>       
(P009)              <sp:RequireThumbprintReference />
(P010)              <sp:WssX509V3Token10 />
(P011)            </wsp:Policy>
(P012)          </sp:X509Token>
(P013)        </wsp:Policy>
(P014)      </sp:EndorsingSupportingTokens>... 
(P015)    </wsp:All>
(P016)  </wsp:ExactlyOne>
(P017)</wsp:Policy>

Client
(P001)<wsp:Policy wsu:Id="..." >
(P002)   <wsp:ExactlyOne>
(P003)     <wsp:All>
(P004)       <sp:SignedSupportingTokens 
(P005)         xmlns:sp="..."> <!-- parent policy assertion b -->      
(P006)         <wsp:Policy> <!-- nested policy b1 -->
(P007)           <sp:X509Token  sp:IncludeToken=".../IncludeToken/AlwaysToRecipient"> 
(P008)             <wsp:Policy>       
(P009)               <sp:RequireThumbprintReference />
(P010)               <sp:WssX509V3Token10 />
(P011)             </wsp:Policy>
(P012)          </sp:X509Token>
(P013)        </wsp:Policy>
(P014)      </sp:SignedSupportingTokens>... 
(P015)    </wsp:All>
(P016)  </wsp:ExactlyOne>
(P017)</wsp:Policy>
          

In this scenario as illustrated in Examples 3.8 and 3.9, the EndorsingSupportingTokens and SignedSupportingTokens assertions are incompatible even though their nested policy expressions are compatible. This is because the parent policy assertions EndorsingSupportingTokens and SignedSupportingTokens have different QNames.

3.5 Attaching Policy Expressions to WSDL

In 2. Basic Concepts: Policy Expression, we looked into how Company-X attached their policy expressions to the WSDL binding element. In addition to the WSDL binding element, a policy expression can be attached to other WSDL elements such as service, port, operation and message. These elements are the WSDL policy attachment points in a WSDL document.

The WSDL attachment points are partitioned (as illustrated below) into four policy subjects: message, operation, endpoint and service. When attached, capabilities and requirements represented by a policy expression apply to a message exchange or message associated with (or described by) a policy subject.

Figure 3-3. Policy Subjects and Effective Policy in WSDL

The WSDL service element represents the service policy subject. Policy expressions associated with a service policy subject apply to any message exchange using any of the endpoints offered by that service.

The WSDL port, binding and portType elements collectively represent the endpoint policy subject. Policy expressions associated with an endpoint policy subject apply to any message exchange made using that endpoint.

The WSDL binding/operation and portType/operation elements collectively represent the operation policy subject. Policy expressions associated with an operation policy subject apply to the message exchange defined by that operation.

The WSDL binding/operation/input, portType/operation/input, and message element collectively represent the message policy subject for the input message. The WSDL binding/operation/output, portType/operation/output, and message element collectively represent the message policy subject for the output message. The WSDL binding/operation/fault, portType/operation/fault, and message element collectively represent the message policy subject for the fault message. Policy expressions associated with a message policy subject apply only to that message.

In the example below, the policy expression is attached to an endpoint policy subject.

<wsdl:binding name="SecureBinding" type="tns:RealTimeDataInterface" >
  <PolicyReference URI="#secure" />
  <wsdl:operation name="GetRealQuote">…</wsdl:operation>
  …
</wsdl:binding>

If multiple policy expressions are attached to WSDL elements that collectively represent a policy subject then the effective policy of these policy expressions applies. The effective policy is the combination of the policy expressions that are attached to the same policy subject. For example, the effective policy of an endpoint policy subject is the combination of policy expressions attached to a WSDL port element, policy expressions attached to the binding element referenced by this port, and policy expressions attached to the portType element that is supported by this port. Let us consider how to combine policy expressions in the next section.

Most of the policy assertions are designated for the endpoint, operation or message policy subject. The commonly used WSDL attachment points are:

3.6 Policy Retrieval

Just as other service metadata languages, Web Services Policy does not mandate any specific policy retrieval mechanism. Any combination of any retrieval mechanisms in any order may be used for referencing policy expressions. Example retrieval mechanisms are:

• Do nothing. A policy expression with the referenced IRI is already known to be available in a local cache or chip (embedded systems).

• Use the referenced IRI and retrieve an existing policy expression from the containing XML document: a policy element with an XML ID.

• Use the referenced IRI and retrieve a policy expression from some policy repository (local or remote), registry or catalog. Policy tools or policy-aware clients may use any protocols (say UDDI or Web Services Metadata Exchange) for such metadata retrieval. These protocols may require additional out of band information.

• Attempt to resolve the referenced IRI on the Web. This may resolve to a policy element or a resource that contains a policy element.

If the referenced policy expression is in the same XML document as the reference, then the policy expression should be identified using the wsu:Id|xml:id (XML ID) attribute and referenced using an IRI reference to this XML ID value.

WSDL 1.1 [WSDL 1.1] section 2.1 and WSDL 2.0 [WSDL 2.0 Core Language] chapter 4 allow to import or include WSDL documents into another WSDL document with the wsdl11:import, wsdl20:import, and wsdl20:include statements. The importing and imported WSDL documents constitute separate XML documents each. If e.g. the importing WSDL document references a policy in the imported WSDL document, the rules for policy references between separate XML documents apply as described in 2.10 Referencing Policy Expressions.

3.7 Combine Policies

Multiple policy expressions may be attached to WSDL constructs. Let us consider how Company-X could have used multiple policy expressions in a WSDL document. In the example below, there are two policy expressions #common2 and #secure2 attached to the SecureBinding WSDL binding and RealTimeDataPort WSDL port descriptions.

<Policy wsu:Id=”common2”>
  <mtom:OptimizedMimeSerialization wsp:Optional="true"/>
  <wsam:Addressing>…</wsam:Addressing>
</Policy>
<Policy wsu:Id=”secure2”>
  <ExactlyOne>
   <sp:TransportBinding>…</sp:TransportBinding>
   <sp:AsymmetricBinding>…</sp:AsymmetricBinding >
  </ExactlyOne>
</Policy>
<wsdl:binding name="SecureBinding" type="tns:RealTimeDataInterface" >
  <PolicyReference URI="#secure2" />
  <wsdl:operation name="GetRealQuote">…</wsdl:operation>
  …
</wsdl:binding>
<wsdl:service name=”RealTimeDataService”>
  <wsdl:port name=”RealTimeDataPort” binding=”tns:SecureBinding”>
    <PolicyReference URI="#common2"/>
    …
  </wsdl:port>
</wsdl:service>

As we discussed before, the WSDL port, binding and portType elements collectively represent the endpoint policy subject. In the example above, the #common2 and #secure2 policy expressions attached to the SecureBinding WSDL binding and RealTimeDataPort WSDL port descriptions collectively apply to any message exchange associated with the RealTimeDataPort WSDL port.

As in the example above, multiple policy expressions may be attached to Web service constructs that collectively represent a single policy subject. When there are multiple policy expressions attached to the same policy subject then the effective policy or combination of these policy expressions apply to the associated policy subject.

The effective policy is the combination of two or more policy expressions attached to the same policy subject. The combination of two policy expressions, also known as the merged policy expression, is a new policy expression that combines these two policy expressions using the All policy operator.

The policy expression below is the combination of the two policy expressions attached to the SecureBinding WSDL binding and RealTimeDataPort WSDL port descriptions. The #common2 policy expression has two policy alternatives. The #secure2 policy expression has two policy alternatives. The combination of these two policies is equivalent to Company-X’s secure policy in 2. Basic Concepts: Policy Expression and has four policy alternatives. In other words, the combination of two policies is the cross product of alternatives in these two policies.

<Policy>
  <All>
    <Policy>
     <mtom:OptimizedMimeSerialization wsp:Optional="true"/>
      <wsam:Addressing>…</wsam:Addressing>
    </Policy>
    <Policy>
      <ExactlyOne>
       <sp:TransportBinding>…</sp:TransportBinding>
       <sp:AsymmetricBinding>…</sp:AsymmetricBinding >
      </ExactlyOne>
    </Policy>
  </All>
</Policy>

Of course, the above policy expression can be normalized. There are four policy alternatives in the normal form. As we have seen in the policy data model, a policy is an unordered collection of policy alternatives. That is, the order of policy alternatives is insignificant. Therefore, the order of combining these policy expressions is insignificant.

3.8 Extensibility and Versioning

<Policy>
  <ExactlyOne>
    <All>
      <wsam:Addressing>…</wsam:Addressing>
     <sp:TransportBinding>…</sp:TransportBinding>
    </All>
  </ExactlyOne>
</Policy>

<Policy>
  <ExactlyOne>
    <All>
      <wsam:Addressing>…</wsam:Addressing>
     <sp:TransportBinding>…</sp:TransportBinding>
    </All>
    <All> <!-- - - - - - - - - - - - - - - - NEW Policy Alternative -->
      <wsam:Addressing>…</wsam:Addressing>
      <sp:AsymmetricBinding>…</sp: AsymmetricBinding >
    </All>
  </ExactlyOne>
</Policy>

<Policy>
  <ExactlyOne>
    <All>
      <company-x:EndOfLife wsp:Ignorable="true"/>Mar-31-2008</company-x:EndOfLife>
      <wsam:Addressing>…</wsam:Addressing>
      <sp:TransportBinding>…</sp:TransportBinding>
    </All>
                
    <!-- NEW Policy Alternative -->
    <All> 
      <company-x:EndOfLife wsp:Ignorable="true">Mar-31-2999</company-x:EndOfLife>
        <wsam:Addressing>…</wsam:Addressing>
        <sp:AsymmetricBinding>…</sp:AsymmetricBinding>
      </All>
  </ExactlyOne>
</Policy>

3.9 Parts of a Policy Assertion

As we discussed, a policy assertion identifies a domain specific behavior or requirement or condition. A policy assertion has a QName that identifies its behavior or requirement or condition. A policy assertion may contain assertion parameters and a nested policy.

Let us look at the anatomy of a policy assertion from the security domain. The policy expression in the diagram below uses the sp:IssuedToken policy assertion. This assertion illustrates the use of assertion parameters and nested policy.

Figure 3-4. sp:IssuedToken Policy Assertion

The sp:IssuedToken element is a policy assertion that identifies the use of a security token – such as SAML token - issued by a third party for protecting messages. A policy assertion is an XML element. The QName of this element represents the behavior identified by this policy assertion.

The sp:IssuedToken policy assertion has three parameters: @sp:IncludeToken, sp:Issuer and sp:RequestSecurityTokenTemplate.

The sp:IncludeToken attribute is a parameter that contains information on whether a security token should be included in messages or an external reference to the key of this security token should be used. The sp:Issuer parameter is an endpoint reference to a security token issuer. The sp:RequestSecurityTokenTemplate parameter contains the necessary information to request a security token from the specified issuer. Parameters are the opaque payload of a Policy Assertion, carry useful information for engaging the behavior described by an assertion and are preserved through policy processing such as normalize, merge and intersection. requesters may use policy intersection to select a compatible policy alternative for an interaction. Assertion parameters do not affect the outcome of policy intersection.

For the sp:Issuer policy assertion parameter, the assertion author uses the natural XML structural relationships (the child elements and attributes) and encodes the relationship between an assertion and its parameters in a machine readable form. Assertion parameters may be represented as child XML elements or attributes of an assertion. The policy language allows assertion authors to strongly tie the relationship between an assertion and its parameters using the natural XML structural relationships.

The sp:IssuedToken policy assertion has a nested policy expression. The sp:RequireInternalReference element is a nested policy assertion of the sp:IssuedToken policy assertion. The sp:RequireInternalReference assertion requires the use of an internal reference for referencing the issued token. A nested policy assertion further qualifies a dependent behavior of its parent policy assertion. As mentioned earlier, requesters may use policy intersection to select a compatible policy alternative for an interaction. Nested policy assertions affect the outcome of policy intersection.

The sp:IssuedToken security policy assertion identifies a visible domain specific behavior: the use of a security token – such as SAML token - issued by a third party for protecting messages. This behavior is relevant to a Web service interaction. For the sake of discussion, let us assume that Company-X requires the use of a SAML token issued by a third party. Service providers, like Company-X, must convey this usage and all the necessary information to obtain this security token for Web service developers. This is a key piece of metadata for a successful interaction with Company-X’s Web services.

4.1 Policy Framework

WS-Policy Framework 1.5 specifies that any child element that is not known inside a Policy, ExactlyOne or All will be treated as an assertion. The default value for wsp:Optional is "false". After normalization, such an element will be inside an ExactlyOne/All operator.

Let us show an example with a hypothetical new operator that is a Choice with a minOccurs and a maxOccurs attributes, ala XSD:Choice, in a new namespace. We use the wsp16 prefix to indicate a hypothetical Policy Language 1.6 that is intended to be compatible with Policy Language 1.5:

<wsp:Policy>
  <wsp:ExactlyOne>
    <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
      ...
    </wsp16:Choice>
    <wsp:All>
       ...
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

The normalization rule for wsp:Optional="false" would be applied to the wsp16:Choice, yielding the following expression:

<wsp:Policy>
  <wsp:ExactlyOne>
    <wsp:ExactlyOne>
      <wsp:All>
         <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
          ...
        </wsp16:Choice>
      </wsp:All>
    </wsp:ExactlyOne>
    <wsp:All>
       ...
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

Alternatively, the wsp:Optional could be set to "true" on the choice, as in:

<wsp:Policy>
  <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2"
wsp:Optional="true">
      ...
  </wsp16:Choice>
</wsp:Policy>

The normalized form will be:

<wsp:Policy>
  <wsp:ExactlyOne>
     <wsp:All>
         <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
          ...
        </wsp16:Choice>
      </wsp:All>
     <wsp:All/>
  </wsp:ExactlyOne>
</wsp:Policy>

Because the wsp16:Choice alternative isn't understood in either normalized form, it will not be chosen as one of the alternatives and will effectively be ignored. Policy intersection may be more difficult with such compatible extensions. For example, the previous will "look" like it has a wsp16:Choice typed assertion. To determine intersection with a Policy that does not have the wsp16:Choice type assertion, domain specific processing would have to be done. However, there is an alternative that does not have the wsp16:Choice, so intersection would yield the expected result.

Best practice: insert new elements in an optional alternative or mark with wsp:Optional="true".

Incompatible versions of the Policy language may be indicated by a new namespace name for at least the new and/or incompatible elements or attributes. Imagine that the Choice operator is required by a future version of Policy, then there will be a new namespace for the Policy element. We use the wsp20 prefix to indicate a hypothetical Policy Language 2.0 that is intended to be incompatible with Policy Language 1.5:

<wsp20:Policy>
  <wsp20:ExactlyOne>
    <wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
      ...
    </wsp20:Choice>
    ...
  </wsp20:ExactlyOne>
</wsp20:Policy> 

The new Policy operator could be embedded inside an existing Policy element:

<wsp:Policy>
    <wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
      ...
    </wsp20:Choice>
    ...
</wsp20:Policy> 

This will be treated as an Assertion for normalization and intersection computation. This will result in only one alternative that requires the wsp20:Choice, the intended behaviour for incompatible changes.

Best practice: use a new namespace for new incompatible construct and insert inside either: new Policy element OR existing All for future incompatible policy extensions.

A future version of WS-Policy could support the current operators in the existing namespace, such as:

<wsp20:Policy>
  <wsp:ExactlyOne>
    <wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
      ...
    </wsp20:Choice>
    ...
  </wsp:ExactlyOne>
</wsp20:Policy> 

It is difficult to predict whether this functionality would be useful. The future version of WS-Policy doesn't appear to be precluded from doing this.

4.2 Policy Attachment

Policy attachment provides WSDL 1.1 and UDDI attachment points. It appears that exchange of Policy will be in the context of WSDL or UDDI. WRT WSDL, the policy model is an extension of the WSDL definition. As such, it is likely that future versions of Policy will be exchanged as multiple Policy expressions within a WSDL. One alternative is that there would be a separate WSDL for each version of Policy. The problem of how to specify and query for compound documents is very difficult, so it is more likely that each version of Policy will be exchanged within a WSDL.

We show an example of a new version of policy that allows QName reference to Policies in the PolicyReference:

<wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
       <wsoap12:binding style="document"
          transport="http://schemas.xmlsoap.org/soap/http" />
        <wsp:Policy>
          <wsp:ExactlyOne>
                <wsp:All>
                <wsp:PolicyReference URI="#RmPolicy"
wsdl11:required="true" />
              <wsp:PolicyReference URI="#X509EndpointPolicy"
wsdl11:required="true" />
                </wsp:All>
                <wsp:All>
                <wsp16:PolicyReferenceByQName ref="rmp:RMAssertion"
wsdl11:required="true" />
              <wsp16:PolicyReferenceByQName ref="sp:AsymmetricBinding"
wsdl11:required="true" />
                </wsp:All>
         </wsp:ExactlyOne>
        </wsp:Policy>
  <wsdl11:operation name="GetLastTradePrice" > ....
  ...

The PolicyReference element is element or attribute extensible. One example of an addition is a list of backup URIs for the PolicyReference:

<wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
       <wsoap12:binding style="document"
          transport="http://schemas.xmlsoap.org/soap/http" />
        <wsp:Policy>
          <wsp:ExactlyOne>
                <wsp:All>
                <wsp:PolicyReference URI="" wsp16:alternateURIs="URI*"
wsdl11:required="true" />
              <wsp:PolicyReference URI="" wsp16:alternateURIs="URI*"
wsdl11:required="true" />
                </wsp:All>
         </wsp:ExactlyOne>
        </wsp:Policy>
  <wsdl11:operation name="GetLastTradePrice" > ....
  ...

The policy framework specification says that any unknown attributes are ignored. A Policy 1.5 processor will not understand the wsp16:alternateURI attribute, it will be ignored. A Policy 1.6 processor will understand the alternate URIs so it won't be ignored.

PolicyAttachment and AppliesTo also have extensibility points. We choose not to illustrate these at this time.