WS-Policy Domain owners or WS-Policy authors are defined by the WS-Policy Framework to be a community that chooses to exploit the WS-Policy Framework by creating their own specification to define a set of assertions that express the capabilities and constraints of that target domain. The WS-Policy Framework is based on a declarative model, meaning that it is incumbent on the WS-Policy authors to define both the semantics of the assertions as well as the scope of their target domain in their specification. The set of metadata for any particular domain will vary in the granularity of assertion specification required. It is the intent of this document to help communities utilize the framework in such a way that multiple WS-Policy domains can co-exist and consumers and providers can utilize the framework consistently across domains.

WhenIn order to take advantage using the WS-Policy Framework, any domain author definingattempting to define new WS-Policy assertions must adhere to the MUST's and SHOULD's in the specification and should review the conformance section of the specification. specification.

WS-Policy Domain authors must also specify how to associate the assertions they have defined with the policy subjects identified by the WS-PolicyAttachment specification. specification

An example of a domain specification that includes these properties follows these practices is the WS-SecurityPolicy specification []. The WS-SecurityPolicy authors have defined their scope as follows:

"This document [WS-SecurityPolicy] defines a set of security policy assertions for use with the WS-Policy framework with respect to security features provided in WSS: SOAP Message Security, WS-Trust and WS-SecureConversation. This document takes the approach of defining a base set of assertions that describe how messages are to be secured. Flexibility with respect to token types, cryptographic algorithms and mechanisms used, including using transport level security is part of the design and allows for evolution over time. The intent is to provide enough information for compatibility and interoperability to be determined by web service participants along with all information necessary to actually enable a participant to engage in a secure exchange of messages."

An example of scoping individual assertions to policy subjects is also provided by the WS-Security Policy specification in Appendix A.

A consumer of WS-Policy Assertions can be any entity that is capable of parsing a WS-Policy XML element and selecting one alternative from the policy. This selected alternativeit is then used to govern the creation of a message to send to the subject to which the policy alternative was attached. The WS-Policy Attachment specification defines a set of attachment models for use with common web service subjects: WSDL definitions [, ], UDDI directory entries [, , ], and WS-Addressing Endpoint References (EPR) [].

In the degenerate case, a human could read the XML and determine if a message could be constructed conformant to the advertised policy.

It is expected that consumers of WS-Policy will include a wide range of client configurations, from stand alone client applications to "active" web service requestors that are capable of adapting to the constraints and capabilities expressed in a WS-Policy document and modifying their own configurations dynamically.

A provider of WS-Policy Assertions can be any web service implementation that can specify its on-the-wire message behavior as an XML expression that conforms to the WS-PolicyFramework and WS-Policy Attachment specifications. The WS-PolicyAttachment specification has defined a set of subjects and an extensible mechanism for attaching policies to web services subjects. When a web service provider chooses to make its capabilities and constraints available, it may also need to conform to requirements of other policy specifications it utilizes ( i.e., WS-SecurityPolicy).

When deploying services with policies it is useful for providers to anticipate how to evolve their services capabilities over time. If forward compatibility is a concern in order to accommodate compatibility with different and potentially new clients, providers should refer to and that describes service and policy assertion evolution.

New policy authors are encouraged tonot try to not overload assertions. A single assertion indicates a single behavior. Sets of assertions can by grouped by an operator "all". This indicates that there is a relationship between the assertions and they now constitute a policy alternative.

If grouping is utilized, choicesChoices between alternatives can be indicated by an "exactly one" operator. This basic set of operators allows authors a wide range of options for expressing the possible combinations of assertions within their domain.

It requires a good deal of effort to evaluate the capabilities of a domain and capture them in a way that reflects the options of the domain if the domain has a lot of assertions to define. Interoperability testing of new policy domains is recommended to ensure that consumers and providers are able to use the new domain assertions.

New authors are encouraged to look at to see an example of a relatively simple domain that has defined three assertions. Domain authors are encouraged to look at to see an example of a complex domain that has been decomposed into a set of policy expressions.

How big should an assertion be? How many assertion parameters should the assertion enumerate? How many dependent behaviors should the assertion enumerate? It is always good to start with a simple working policy assertion that allows extensibility. As your design work progresses, you may add more parameters or nested policy assertions to meet your interoperability needs.

Best practice: Start with a simple working assertion that allows extensibility.

Web Services Policy language allows assertion authors to invent their own XML dialects to represent policy assertions. The policy language relies only on the policy assertion XML element QName. This QName is unique and identifies the behavior represented by a policy assertion. Assertion authors have the option to represent an assertion parameter as a child element (by leveraging natural XML nesting) or an attribute of an assertion. The general guidelines on when to use XML elements versus attributes apply.

The syntax of an assertion can be represented using an XML outline (plus an XML schema document). If the assertion has a nested policy expression then the assertion XML outline can enumerate the nested assertions that are allowed.

Best practice: Use a unique QName to identify the behavior and provide an XML outline (plus an XML schema document) to specify the syntax of an assertion.

WS-Policy is intended to communicate the requirements, capabilities, preferences and behaviors of nodes that provide the message's path, not specifically to declare properties of the message semantics. One of the advantages of Web services is that an XML message can be stored and later examined (e.g. as a record of a business transaction) or interpreted by an intermediary; however, if information that is necessary to understand a message is not available, these capabilities suffer.

Policy assertions should not be used to express the semantics of a message. Rather, if a property is required to understand a message, it should be communicated in the message, or be made available by some other means (e.g., being referenced by a URI in the message) instead of being communicated as a policy element.

For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed in policy that isn't attached to the message, it isn't possible to later decipher it. This is very different from expressing, in policy, what ciphers (and so forth) are supported by a particular endpoint, or those that are required in a particular message; the latter are the intended uses of the WS-Policy framework.

As a result, the assertion authors should take into account that the following important concepts when designing assertions and documenting the semantics of the assertion types.

Firstly, an assertion type indicates a runtime behavior.

Secondly, authors need to indicate how the runtime behavior represented in the assertion type can be inferred or indicated from a message at runtime. If there is a need for the behavior to be represented in a persistent way or if there is a need for additional data or metadata that is present in a message to be persisted, it should be incorporated into the assertion design or in the message itself. In essence, the assertion authors should consider how to make messages self describing when utilizing their assertions by specifying additional properties, headers, etc. that must be present in a message as part of their assertion design.

If the messages could not be made self describing by utilizing additional properties present in the message as required by the assertion, it would be necessary to determine the behaviors engaged at runtime by additional means. A general protocol that aids in determining such behaviors may be utilized, however a standard protocol for this purpose is currently not available to ensure interoperability. Thus, a private protocol should be used with care.

Another approach is to use of the assertion to selectively apply to subjects. For example, a dedicated endpoint may be allocated to ensure the engagement of a behavior that is expressed by a policy assertion. This approach can be considered when messages cannot be self describing.

Best practice: Policy assertions should not be used to express the semantics of a message.

When considering the creation of a new domain of policy assertions, it is important to identify whether or not the domain is self-contained or at least if a subset of the domain can be well defined. A domain that expresses a broad set of capabilities will also need to have community supporting implementations to provide value to the consumers. Ultimately it is the consumers and providers that will determine whether a particular set of assertions correctly characterize a domain. A new community should avoid duplicating assertions that have already been defined as this will create ambiguity not clarification. New WS-Policy authors should focus on creating assertions for those specific constraints and capabilities that do not overlap with other domains but that communicate new functionality.

The model advocated for new assertion development is a cooperative marketplace [some might say it is an "opt-in" model]. The providers of services need to find value in the set of assertions or they will not include the assertions in their service descriptions.

A review by a broad community is the best way to ensure that the granularity of a set of domain assertions is appropriate.

Best practice: Avoid duplication of assertions.

The framework allows WS-Policy domain authors to define parameters,name value pairs, for example, to qualify an assertion. For some domains it will be appropriate to specify these parameters instead of nesting assertion elements.

Note that parameters of assertions include the following:

In the example below, sp:Body and sp:Header elements are the two assertion parameters of the sp:SignedParts policy assertion (this assertion requires the parts of a message to be protected). protected).

The framework provides the ability to "nest" policy assertions. For domains with a complex set of options, nesting provides one way to indicate dependent elements within a behavior. The granularity of assertions is determined by the authors and it is recommended that care be taken when defining nested policies to ensure that the options provided appropriately specify policy alternatives within a specific behavior.

We will use the WS-SecurityPolicy to illustrate the use of nested assertions.

Securing messages is a complex usage scenario. The WS-SecurityPolicy authors have defined 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 a Web service, the consumer must know not only that transport-level security is required, but also the transport token to use, the secure transport to use, the algorithm suite to use for performing cryptographic operations, etc. The sp:TransportBinding policy assertion can represent these dependent behaviors.

A policy assertion like the sp:TransportBinding identifies a visible behavior that is a requirement. A nested policy expression can be used to enumerate the dependent behaviors on the Transport binding. A nested policy expression is a policy expression that is a child element of another 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).

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, a policy-aware client that recognizes this policy assertion can engage transport-level security and its dependent behaviors automatically. This means the complexity of security usage is absorbed by a policy-aware client and hidden from these Web service application developers.

The main consideration for selecting parameters or nesting of assertions is that the framework intersection algorithm processes nested alternatives, but does not consider parameters in its algorithm.

Domain authors should recognize that the framework can yield multiple assertions of the same type. The QName of the assertion is the only vehicle for the framework to match a specific assertion, NOT the contents of the element. If the assertion is a parameterized assertion the authors must understand that this type of assertion will require additional processing by consumers in order to disambiguate the assertions or to understand the semantics of the name value pairs, complex content, attribute values contribution to the processing. Therefore, if the domain authors want to delegate the processing to the framework, utilizing nesting should be considered. Otherwise, domain specific comparison algorithms would need to be devised and be delegated to the specific domain handlers that are not visible to the WS-Policy framework. The tradeoff is the generality vs. the flexibility and complexity of the comparison expected for a domain.

Self Describing Messages

The WS-Policy is intended to communicate the requirements, capabilities, preferences and behaviors of nodes that provide the message's path, not specifically to declare properties of the message semantics. One of the advantages of Web services is following design questions below can help be stored and later examined (e.g. as a record of a business transaction) or interpreted by an intermediary; however, if information that is necessary to determineunderstand a when to usenot available, nested policy expressions:suffer.

Ife.g., the answerscipher used, etc) are yesexpressed in policy that isn't attached to boththe message, of these questionspossible to then leveraging nested policy expressionsThis is something to consider. Keep in policy, what ciphers (and so mindforth) are thatsupported by a nestedparticular endpoint, or those policy expression participates in the policy intersection algorithm.the latter If a requester uses policy intersection to selectframework. As a compatible result, the assertion authors should policytake into alternative then the following important concepts when designing assertions inand documenting the semantics of the assertion types. a nested policy expression play a first runtime behavior. Secondly, an assertion classshould also role in the outcome.assertion type can be inferred or indicated from a message at runtime. If There is onea need for caveat behavior to watchbe represented in a persistent way outor if for: policy assertions witha deeply nestedfor additional policy can greatly increase the complexity of a policymessage to be persisted, and should be avoided incorporated into the assertion design or in the message itself. In essence, the assertion authors should consider how to make messages self describing when theyutilizing their assertions by specifying additional properties, headers, etc. that must be present in a message as part are not needed.assertion design.

BestIf the messages could not be made self describing by utilizing additional properties present in the message as practice: If the domain authorsassertion, it would be want to determine the behaviors engaged at runtime by additional means. A general protocol that aids in determining such behaviors may be utilized, however a standard protocol for this purpose delegateis currently the processing to theensure interoperability. Thus, framework, utilizing nesting should be considered.used with care. Another approach is to Otherwise, domain specificof comparisonthe assertion algorithms will need to besubjects. For example, a dedicated devised and be delegated to ensure the specific domain handlersa behavior that areis expressed by a policy assertion. This approach can be considered when messages can not visible tobe the WS-Policy framework. describing.

Optional behaviors represent behaviors which may be engaged by a consumer. When using the compact authoring form for assertions, behaviors are marked by using wsp:Optional attribute that has a value, "true". During the process of normalization, the runtime behavior is indicated by two policy alternatives, one with and one without containing the assertion. In a consumer/provider scenario, the choice of engaging the runtime behavior is upon the consumer although the provider is capable of engaging the runtime behavior. In order to simplify reference to such assertions, we just use the term optional assertions in this section.

The document contains an example that proposes the use of as an optional behavior that can be engaged by a consumer. The primer proposes that an assertion that identifies the use of MIME Multipart/Related serialization (see , for messages to enable a Policy-aware clients to recognize the policy assertion and if they select an alternative with this assertion, they engage Optimized MIME Serialization for messages.

The semantics of this assertion declare that the behavior is reflected in messages: they use an optimized wire format (MIME Multipart/Related serialization). Note that in order for an optional behavior to be engaged, the wire message that would utilize the specific assertion must be self describing. For example, an inbound message to a web service that asserts MTOM, must evaluate, the protocol format of the message to determine whether the incoming message adheres to the Optimized MIME Serialization. By examining the message, the provider can determine whether the policy alternate that contains the MTOM assertion is being selected.

Assertion authors should be aware that optional behaviors, like utilizing optional support for Optimized MIME Serialization require some care considering the scoping of the assertion that is applicable.

Best Practice: Optional assertion authors should explicitly state how the behavior that is enabled by the assertion would be engaged when they are designing their assertion, whether by specific headers or some other means. See also .

If the best practices are followed, and the assertions are scoped according to their subject, then multiple policy domains may be combined without conflict. Each domain should define any limitations at the policy subject level that might impact interoperability (i.e. WS-SecurityPolicy - binding abstraction to group capabilities per message exchange).