Assertion Authors are 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 Assertion 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.

When using the WS-Policy Framework, any Assertion Authors defining 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.

An assertion author should also specify a policy subject. For instance, if a policy assertion were to be used with WSDL, an assertion description should specify a WSDL policy subject.

An example of a domain specification that 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 alternative 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 requesters that are capable of adapting to the constraints and capabilities expressed in a WS-Policy document and modifying their own configurations dynamically.

A provider who expresses capabilities and requirements of a Web service as policies can be any web service implementation that can specify its on-the-wire message behavior as a policy expression that conforms to the Web Services Policy 1.5 - Framework [] and Web Services Policy 1.5 - Attachment [] specifications. The Web Services Policy 1.5 - Attachment specification has defined a set of subjects and an extensible mechanism for attaching policies to web services subjects.

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 Assertion Authors are encouraged to 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, choices between alternatives can be indicated by an "exactly one" operator. This basic set of operators allows Assertion 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 Assertion Authors are To facilitate proper progressionlook of an assertion, assertion authors should start with a relatively simple workingdomain that has defined three assertions. Assertion assertion that allows extensibility. As the design work progresses, one may add more parameters or nested policy assertions tohas meet one's interoperability needs.

Starta with Simple Assertion Anpolicy assertionexpressions. How author should start with a simple working assertion that parameters should allows assertion enumerate? parameter extensibility.

Newdependent Assertion Authors are encouraged to look at always good to see an example of a relativelyworking simple domain that has defined three assertions.your design Assertion Authors are encouraged to look at or to see an example ofmeet your a complexneeds. Best domain that has been decomposed into a set of policy expressions. 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 is. Use a unique QName to identify a distinct behavior and provide an XML outline (plus an XML schema document) to specify the syntax of an assertion. apply.

Use Unique QNames An assertion author should use a unique QName to identify a distinct behavior.

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. An example is the following:

Best Specifypractice: Semantics Clearlya > unique An assertion description must clearly and completely specify the semantics of a policy assertion.

Provide an XML Outline > An assertion description should provide an XML outline (plus plus an XML schema document) to specify the syntax of the assertion.

WS-Policy is intended to communicate the requirements, capabilities 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. Note that there are other specifications that target specification of semantics of a message, such as .

IfFor example, if the messages could not be made self describing by utilizing additional properties present expressed in the message as required by the assertion, it would be necessary possible to determine the behaviors engaged at runtime by additional means. A generalexpressing, protocolin policy, that aids in determining such behaviors may be utilized,by however a standardparticular endpoint, protocol for this purpose is currentlyrequired not available to ensure interoperability. Thus,in a private protocol shouldthe latter be used with care.

Another approach is to useuses of the assertion to selectively apply to subjects. For example,framework. As a dedicated endpoint may be allocated to ensure the engagementinto of a behavioraccount that is expressed by a policy assertion. This approach can be considered concepts when messages cannot be self describing.

Policydesigning assertions should not be used toand express the semantics of athe assertion message.types. Firstly, an assertion type indicates a runtime behavior. Secondly, Assertion 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.

Not If the messages could not be made self describing by utilizing additional properties Necessary to Understandthe message a Message Anrequired assertion author should not define policy assertions to determine the behaviors engaged at runtime by additional means. representA general information that isaids in determining such behaviors necessary tobe utilized, understand a message.

Forstandard protocol for example, if theis currently details of a message's encryption ( e.g., the cipher used, etc) are expressed inwith policy that Another isn't attached to use of the message,assertion to it isn't possible to later decipher it. Thisa dedicated is very different from expressing, in policy,ensure what ciphers (and soa behavior forth) are supported by a particular endpoint, or thoseapproach can that are required in a particular message; thedescribing. latterBest practice: Policy assertions should are the intended uses of the WS-Policysemantics of a framework.

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 a community supporting implementations of these capabilities 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 Assertion 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.

It is the responsibility of the assertion authors to avoid duplication of assertions. 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 An assertion author should reuse an existing assertion (rather than create a new one) whenever possible.assertions.

Policy assertion parameters are the opaque payload ofdefine policy an assertion. Parametersparameters carry additional useful informationassertion. Policy for engaging the behaviorare described by an. Policy assertion and are preserved through policy processingpayload such as normalize,assertion. Assertion merge and policy intersection. Requestersuseful may use policyinformation necessary intersection to select a compatible policydescribed alternative forby an interaction. Assertion parameters do not affect the outcome of policy intersection unless the assertion specifies domain specific compatibility processing semantics are specified for policy intersection.

assertion. In the XML representation of a policy assertion, the child elements and attributes of the assertion excluding child elements and attributes from the policy xml language namespace name are the assertion parameters.

Use Parameters for Useful Information An assertion author should represent useful (or additional) information necessary for engaging the behavior represented by a policy assertion as assertion parameters.

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). These Policy Assertion two parameters identifyParameters Best the parts of a wire messagefor specifying that should be protected.of These parameters carry additionalengaging the useful information for engagingby the behavior.

policy intersection.

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.

The following design questions below can help to determine when to use nested policy expressions:

If the answers are yes to both of these questions then leveraging nested policy expressions is something to consider. Keep in mind that a nested policy expression participates in the policy intersection algorithm. If a requester uses policy intersection to select a compatible policy alternative then the assertions in a nested policy expression play a first class role in the outcome. If there is a nested policy expression, an assertion description should declare it and enumerate the nested policy assertions that are allowed. There is one caveat to watch out for: policy assertions with deeply nested policy can greatly increase the complexity of a policy and should be avoided when they are not needed.

Use Nested Assertions for Dependent Behaviors An assertion author should represent dependent behaviors that are relevant to a compatibility test and apply to the same policy subject using nested policy assertions.

Declare Nested Assertions If there is a nested policy expression, an assertion description should declare it and enumerate the nested policy assertions that are allowed.

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.

Assertion 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. The tradeoff is the generality vs. the flexibility and complexity of the comparison expected for a domain.

If the assertion authors want to delegate the processing to the framework, utilizing nesting should be considered. Otherwise, domain specific comparison algorithms may need to be devised and be delegated to the specific domain handlers that are not visible to the WS-Policy framework. However, domain specific intersection processing reduces interop and increases the burden to implement an assertion.

Discourage Domain Specific Intersection An assertion description should only specify domain specific intersection semantics when policy intersection is insufficient.

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

Securing messages is a complex usage scenario. The WS-SecurityPolicy Assertion 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 Web service application developers.

Assertion authors should note the effect of nested policy expressions on policy intersection in their nested policy design. The result of intersecting an assertion that contains an empty nested policy expression with an assertion of the same type without a nested policy expression is that the assertions are not compatible. Therefore, when providers require dependent behaviors these behaviors should be explicitly specified as assertions in a nested policy expression. When the definition of an assertion allows for nested dependent behaviors, but the use of the assertion only contains an empty nested policy expression, this specific use indicates the specification of no nested dependent behaviors. This use must not be interpreted as being compatible with "any" of the nested dependent behaviors that are allowed by the assertion, unless otherwise specified by the assertion definition.

As an example, WS-Security Policy defines 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 intersection algorithm alone.

Assertionsconsider. Document Ignorable Behaviormind > that An assertion description should use in the wsp:Ignorablepolicy intersection algorithm. If a requester uses policy intersection attribute to indicateselect a compatible policy alternative that the behaviorassertions in a nested policy expression play a first class indicated by the QNameoutcome. There is one caveat to watch out for: policy assertions with deeply nested policy can greatly increase may be ignored by policy intersection.

they Ignorableare Attribute inneeded. Best XMLpractice: > If An assertion authors want to delegate the processing XMLto the framework, utilizing outline should allowbe considered. Otherwise, domain specific comparison algorithms may need to be devised and be delegated for the usespecific domain handlers of the wsp:Ignorable attribute to indicate ignorable behavior.

Optional behaviors represent behaviors that may be engaged by a consumer. When using the compact authoring form for assertions, such behaviors are marked by using wsp:Optional attribute withthat has a value of value, "true". (In order to simplify reference to such assertions, we just use the phrase “optional assertions” in this section.) During the process of normalization the runtime behavior is indicated by two policy alternatives, one with and one without the assertion. In a consumer/provider scenario, the choice of engaging the runtime behavior is upon the consumer by selectingalthough the appropriate policy alternative. Thecapable provider may influencethe runtime what is possible by choosing whether orreference not to include policysuch assertions, alternatives in a policy expression, by using theassertions wsp:Optional attribute. Ansection. Optional assertion author shouldruntime The clearly indicate in thean example assertion definitionthat it is possible to be optional and to allow the use of the wsp:Optional attribute inThe primer the XML definition.

Assertionassertion XML should allow use of MIME Multipart/Related serialization wsp:Optional attribute An, assertion XML outline should allow thePolicy-aware clients use of the wsp:Optional attribute to indicateand optional behaviors.

Tothey giveselect an a general example, the definition of assertion syntaxMIME Serialization for amessages. The hypothetical assertion such as SampleAssertion, shoulddeclare allow attribute extensibilitybehavior is as part of the XML definition, allowing the wsp:Optionalformat (MIME attribute to be used:

Theto portion of the assertion definition that would describes policy subjects and assertion attachment shouldself describing. indicate thatFor wsp:Optional can be used to indicatea web service that the behaviorasserts is optional for the policy subject.

Assertionformat description shouldthe message explicitly indicate that wsp:Optional is allowed. Anmessage assertion descriptionto the should use the wsp:Optional attribute to indicatemessage, the that the behaviorcan indicated by the QNamepolicy alternate isthat contains optional for the associated policy subject.

selected.

Continuing the example with the hypothetical SampleAssertion, thebehaviors, like section on Assertion Attachment should includeOptimized discussionMIME Serialization of optionality.

Since optional behaviors indicate optionality for both the provider and the consumer, behaviors that must always be engaged by a consumer must not be marked as "optional" with a value "true" since thispresence of two alternatives due to normalization would allow the consumer to choose select the policy alternative that does not contain the assertion, and thus making the behavior not engagingbeing engaged in an interaction. As demonstrated in the MIME optimization behavior, behaviors must be engaged with respect to messages that are targeted to the provider so that the provider can determine that the behavior.

Limitoptional behavior is engaged. In other words, the use of Optionalself describing Assertions Assertionnature Authors should not[] use optional assertions for behaviors that must not be present forgotten with regard to the client's ability to detect and select the alternative if it is to participate in compatible policy expressions.

exchange.

The target scope of an optional assertion is an important factor for Assertion Authors to consider as it determines the granularity where the behavior is optionally engaged. For example, if the assertion is targeted for an endpoint policy subject, it is expected to govern all the messages that are indicated by the specific endpoint when optional behavior is engaged . Since the behavior would be applicable to policy subject that is designated, it is important for the Assertion Authors to choose the appropriate level of granularity for optional behaviors, to consider whether a specific message or all messages, etc. are targeted. Attaching optional assertions to outbound-messages using message policy subject require some care. An explicit, out of band mechanism may be necessary to enable a client to indicate that the optional behavior is engaged. Currently such a mechanism is outside the scope of WS-Policy Framework.

When optional behaviors are indicated by attaching assertions with only one side of an interaction, such as an inbound message of a request-response, the engagement of the rest of the interaction will be undefined. For example, if a request-response interaction will only specified MTOM optimization for an inbound message, it would not be undefined.clear whether the outbound message from the provider could also utilize the behavior. Therefore, the Assertion Authors are encouraged to consider how the attachment on a message policy subject on a response message should be treated when optional behaviors are specified for message exchanges within a request response for response messages, using message policy subject. Leaving the semantics not specified or incompletely specified may result in providers making assumptions. assumptions (i.e. if the incoming message utilized the optimization, the response will be returned utilizing the MTOM serialization). Similarly, if engagement of a behavior is only specified for an outbound message, the Assertion Authors should consider describing the semantics if the incoming messages also utilized the behavior. This is especially important if the assertion is applicable to more than one specific policy subject. One approach that is currently taken by WS-RM Policy [] is to introduce both message and endpoint policy subjects for one of its assertions and require the use of endpoint policy subject when message policy subject is used via attachment.

Consider Best entire message exchange pattern when specifying Assertions thatOptional may be optional Assertion Authors should associate optional assertions with the appropriate endpoint and use the smallest possible granularity to limit the degree to which optionality applies.

Behaviors must be engaged with respect to messages that are targeted to the provider so that the provider canstate how determine that the optional behavior is engaged. In other words, the need for self describing messages [] should not be forgotten. An explicit, out of band mechanism might be necessary to enable a client to indicate that the optional behavior is engaged. (Such anenabled out of band mechanism is outside the scope of WS-Policy Framework).

Indicate use of an Optional Assertion When a given behavior may be optional, it must be possible for both message participants toby determine that the assertion is selected by both parties, either out of band or aswould reflected by the message content.

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).