- From: Asir Vedamuthu via cvs-syncmail <cvsmail@w3.org>
- Date: Sat, 25 Nov 2006 23:40:13 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv25811
Modified Files:
ws-policy-primer.html ws-policy-primer.xml
Log Message:
Implemented the resolution [1] for issue 3792 [2]. Editors Action Item 80 [3]: moved Sections 4.2 Parts of a Policy Assertion [4] and 4.4.8 Versioning Policy Language [5] into Section 3. Advanced Concepts: Policy Expression; moved Section 4 Advanced Concepts II: Policy Assertion Design [6] into the Guidelines document.
[1] http://www.w3.org/Bugs/Public/show_bug.cgi?id=3792#c2
[2] http://www.w3.org/Bugs/Public/show_bug.cgi?id=3792
[3] http://www.w3.org/2005/06/tracker/wspolicyeds/actions/80
[4] http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#parts-of-a-policy-assertion
[5] http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#versioning-policy-language
[6] http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#advanced-concepts-2-policy-assertion-design
Index: ws-policy-primer.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-primer.html,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -d -r1.25 -r1.26
--- ws-policy-primer.html 21 Nov 2006 20:36:43 -0000 1.25
+++ ws-policy-primer.html 25 Nov 2006 23:40:09 -0000 1.26
@@ -60,7 +60,7 @@
complete normative description of the Web Services Policy language. </p></div><div>
<h2><a name="status">Status of this Document</a></h2><p><strong>This document is an editors' copy that has
no official standing.</strong></p><p></p></div><hr><div class="toc">
-<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#introduction">Introduction</a><br>2. <a href="#basic-concepts-policy-expression">Basic Concepts: Policy Expression</a><br> 2.1 <a href="#web-services-policy">Web Services Policy</a><br> 2.2 <a href="#simple-message">Simple Message</a><br> 2.3 <a href="#secure-message">Secure Message</a><br> 2.4 <a href="#other-assertions">Other Assertions</a><br> 2.5 <a href="#combining-policy-assertions">Combining Policy Assertions</a><br> 2.6 <a href="#optional-policy-assertion">Optional Policy Assertion</a><br> 2.7 <a href="#nested-policy-expressions">Nested Policy Expressions</a><br> 2.8 <a href="#Referencing_Policy_Expressions">Referencing Policy Expressions</a><br> 2.9 <a href="#attaching-policy-expressions-to-wsdl">Attaching Policy Expresions to WSDL</a><br> 2.10 <a href="#policy-automates-web-services-interaction">Policy Automates Web Services Interaction</a><br>3. <a href="#advanced-concepts-1-policy-expression">Advanced Concepts I: Policy Expression</a><br> 3.1 <a href="#policy-expression">Policy Expression</a><br> 3.2 <a href="#normal-form-for-policy-expressions">Normal Form for Policy Expressions</a><br> 3.3 <a href="#policy-data-model">Policy Data Model</a><br> 3.4 <a href="#compatible-policies">Compatible Policies</a><br> 3.5 <a href="#attaching-policy-expressions-to-wsdl2">Attaching Policy Expressions to WSDL</a><br> 3.6 <a href="#combine-policies">Combine Policies</a><br> 3.7 <a href="#extensibility-and-versioning">Extensibility and Versioning</a><br>4. <a href="#advanced-concepts-2-policy-assertion-design">Advanced Concepts II: Policy Assertion Desin</a><br> 4.1 <a href="#role-of-policy-assertions">Role of Policy Assertions</a><br> 4.2 <a href="#parts-of-a-policy-assertion">Parts of a Policy Assertion</a><br> 4.3 <a href="#when-to-design-policy-assertions">When to design policy assertions?</a><br> 4.3.1 <a href="#opt-in-behavior">Opt-in behavior</a><br> 4.3.2 <a href="#shared-behavior">Shared behavior</a><br> 4.3.3 <a href="#visible-behavior">Visible behavior</a><br> 4.4 <a href="#guidelines-for-designing-assertions">Guidelines for Designing Assertions</a><br> 4.4.1 <a href="#optional-behaviors">Optional Behaviors</a><br> 4.4.2 <a href="#assertion-vs-assertion-parameter">Assertion vs. assertion parameter</a><br> &bsp; 4.4.3 <a href="#leveraging-nested-policy">Leveraging Nested Policy</a><br> 4.4.4 <a href="#minimal-approach">Minimal approach</a><br> 4.4.5 <a href="#QName_and_XML_Information_Set_representation">QName and XML Information Set representation</a><br> 4.4.6 <a href="#Policy_subject_and_attachment_points">Policy subject and attachment points</a><br> 4.4.7 <a href="#versioning-behaviors">Versioning behaviors</a><br> 4.4.8 <a href="#versioning-policy-language">Versioning Policy Language</a><br> 4.4.8.1 <a href="#versioning-policy-framework">Policy Framework</a><br> 4.4.8.2 <a href="#versioning-policy-attachment">Polcy Attachment</a><br> 4.5 <a href="#describing-policy-assertions">Describing Policy Assertions</a><br>5. <a href="#conclusion">Conclusion</a><br></p>
+<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#introduction">Introduction</a><br>2. <a href="#basic-concepts-policy-expression">Basic Concepts: Policy Expression</a><br> 2.1 <a href="#web-services-policy">Web Services Policy</a><br> 2.2 <a href="#simple-message">Simple Message</a><br> 2.3 <a href="#secure-message">Secure Message</a><br> 2.4 <a href="#other-assertions">Other Assertions</a><br> 2.5 <a href="#combining-policy-assertions">Combining Policy Assertions</a><br> 2.6 <a href="#optional-policy-assertion">Optional Policy Assertion</a><br> 2.7 <a href="#nested-policy-expressions">Nested Policy Expressions</a><br> 2.8 <a href="#Referencing_Policy_Expressions">Referencing Policy Expressions</a><br> 2.9 <a href="#attaching-policy-expressions-to-wsdl">Attaching Policy Expresions to WSDL</a><br> 2.10 <a href="#policy-automates-web-services-interaction">Policy Automates Web Services Interaction</a><br>3. <a href="#advanced-concepts-policy-expression">Advanced Concepts: Policy Expression</a><br> 3.1 <a href="#policy-expression">Policy Expression</a><br> 3.2 <a href="#normal-form-for-policy-expressions">Normal Form for Policy Expressions</a><br> 3.3 <a href="#policy-data-model">Policy Data Model</a><br> 3.4 <a href="#compatible-policies">Compatible Policies</a><br> 3.5 <a href="#attaching-policy-expressions-to-wsdl2">Attaching Policy Expressions to WSDL</a><br> 3.6 <a href="#combine-policies">Combine Policies</a><br> 3.7 <a href="#extensibility-and-versioning">Extensibility and Versioning</a><br> 3.8 <a href="#parts-of-a-policy-assertion">Parts of a Policy Assertion</a><br>&nbp; 3.9 <a href="#versioning-policy-language">Versioning Policy Language</a><br> 3.9.1 <a href="#versioning-policy-framework">Policy Framework</a><br> 3.9.2 <a href="#versioning-policy-attachment">Policy Attachment</a><br>4. <a href="#conclusion">Conclusion</a><br></p>
<h3><a name="appendix" id="appendix">Appendices</a></h3><p class="toc">A. <a href="#security-considerations">Security Considerations</a><br>B. <a href="#xml-namespaces">XML Namespaces</a><br>C. <a href="#references">References</a><br>D. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br>E. <a href="#change-description">Changes in this Version of the Document</a> (Non-Normative)<br>F. <a href="#change-log">Web Services Policy 1.5 - Primer Change Log</a> (Non-Normative)<br></p></div><hr><div class="body"><div class="div1">
<h2><a name="introduction"></a>1. Introduction</h2><p>This document, <em>Web Services Policy 1.5 - Primer</em>, provides an introductory description of the
Web Services Policy language and should be read alongside the formal descriptions contained
@@ -72,7 +72,7 @@
describes those features in the context of concrete examples.</p><p><a href="#basic-concepts-policy-expression"><b>2. Basic Concepts: Policy Expression</b></a> covers the basic mechanisms of Web
Services Policy. It describes how to declare and combine capabilities and requirements of a
Web service as policy expressions, attach policy expressions to WSDL constructs such as
- endpoint and message, and re-use policy expressions.</p><p><a href="#advanced-concepts-1-policy-expression"><b>3. Advanced Concepts I: Policy Expression</b></a> this is the first advanced section
+ endpoint and message, and re-use policy expressions.</p><p><a href="#advanced-concepts-policy-expression"><b>3. Advanced Concepts: Policy Expression</b></a> this is the advanced section
that provides more in-depth materials for policy implementers and assertion authors. It
explains the basics of normalizing policy expressions, merging policies, determining the
compatibility (intersection) of policies, the policy data model, the policy expression and
@@ -435,11 +435,11 @@
complexity is absorbed by policy-aware clients (or tools) and is invisible to these Web
service developers.</p><p>Web Services Policy extends the foundation on which to build interoperable Web services,
hides complexity from developers and automates Web service interactions.</p></div></div><div class="div1">
-<h2><a name="advanced-concepts-1-policy-expression"></a>3. Advanced Concepts I: Policy Expression</h2><p>In <a href="#basic-concepts-policy-expression"><b>2. Basic Concepts: Policy Expression</b></a>, we covered the basics of Web Services
- Policy language. This is the first advanced section that provides more in-depth materials
+<h2><a name="advanced-concepts-policy-expression"></a>3. Advanced Concepts: Policy Expression</h2><p>In <a href="#basic-concepts-policy-expression"><b>2. Basic Concepts: Policy Expression</b></a>, we covered the basics of Web Services
+ Policy language. This is the advanced section that provides more in-depth materials
for Web Services Policy implementers and assertion authors. This section covers the
following topics:</p><ul><li><p>What is a policy expression?</p></li><li><p>What is the normal form of a policy expression and how to normalize policy
- expressions?</p></li><li><p>What is the policy data model?</p></li><li><p>How to select a compatible policy alternative?</p></li><li><p>How to attach policy expressions to WSDL constructs?</p></li><li><p>How to combine policies?</p></li><li><p>What are the extensibility points?</p></li></ul><div class="div2">
+ expressions?</p></li><li><p>What is the policy data model?</p></li><li><p>How to select a compatible policy alternative?</p></li><li><p>How to attach policy expressions to WSDL constructs?</p></li><li><p>How to combine policies?</p></li><li><p>What are the extensibility points?</p></li><li><p>What are the parts of a policy assertion?</p></li></ul><div class="div2">
<h3><a name="policy-expression"></a>3.1 Policy Expression</h3><p>A policy expression is the XML representation and interoperable form of a Web Services
Policy. A policy expression consists of a <code>Policy</code> wrapper element and a
variety of child and descendent elements. Child and descendent elements from the policy
@@ -803,38 +803,17 @@
intervention. As you would recognize, there is nothing new in this practice. This is
similar to how a proxy generator that generates code from WSDL creates code for all the
known WSDL constructs and allows Web service developers to fill in code for custom or
- unknown constructs in the WSDL.</p></div></div><div class="div1">
-<h2><a name="advanced-concepts-2-policy-assertion-design"></a>4. Advanced Concepts II: Policy Assertion Design</h2><p>In the previous section, we covered in-depth materials for Web Services Policy
- implementers. This is the second advanced section that walks through the dimensions of a
- policy assertion for assertion authors. This section covers the following topics:</p><ul><li><p>What is the role of policy assertions?</p></li><li><p>What are the parts of a policy assertion?</p></li><li><p>When to design policy assertions?</p></li><li><p>What are the guidelines for designing policy assertions?</p></li><li><p>What are the minimum requirements for describing policy assertions?</p></li></ul><div class="div2">
-<h3><a name="role-of-policy-assertions"></a>4.1 Role of Policy Assertions</h3><p>As you have seen, Web Services Policy is a simple language that has four elements
- -<code>Policy, All</code>, <code>ExactlyOne</code> and <code>PolicyReference</code> -
- and one attribute - <code>wsp:Optional</code>. Policy is a flexible language to represent
- consistent combinations of behaviors using policy operators: <code>Policy, All</code> and
- <code>ExactlyOne.</code> Policy is an expressive language and capable of representing
- behaviors from a variety of domains. Let us look for the key parts that unlock this
- potential.</p><p>Service providers combine behaviors for an interaction from domains such as messaging,
- security, reliability and transactions. To enable clients to engage these behaviors,
- services require some way to advertise these behaviors. Providers require machine readable
- metadata pieces that identify these behaviors. A policy assertion is a machine-readable
- metadata piece that requires the use of a behavior identified by the assertion. Web
- service developers can use policy-aware clients that recognize these assertions and engage
- their corresponding behaviors automatically.</p><p>Policy assertions are the key parts and play a central role to unlock the potential
- offered by the Web Services Policy language. Assertions are defined by product designers,
- protocol authors, protocol implementers and Web service developers.</p><p>Policy assertion authors identify behaviors required for Web services interactions and
- represent these behaviors as policy assertions. By designing policy assertions, assertion
- authors make a significant contribution to automate Web services interactions and enable
- advanced behaviors.</p></div><div class="div2">
-<h3><a name="parts-of-a-policy-assertion"></a>4.2 Parts of a Policy Assertion</h3><p>As we discussed, a policy assertion identifies a domain specific behavior or requirement
+ unknown constructs in the WSDL.</p></div><div class="div2">
+<h3><a name="parts-of-a-policy-assertion"></a>3.8 Parts of a Policy Assertion</h3><p>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.</p><p>Let us look at the anatomy of a policy assertion from the security domain. The policy
expression in the diagram below uses the <code>sp:IssuedToken</code> policy assertion.
- This assertion illustrates the use of assertion parameters and nested policy.</p><div class="figure" style="text-align: center"><br><img src="policy-assertion.jpg" alt="sp:IssuedToken Policy Assertion"><p style="text-align:left"><i><span>Figure 4-1. </span>sp:IssuedToken Policy Assertion</i></p><br></div><p>The <code>sp:IssuedToken</code> element is a policy assertion that identifies the use of
+ This assertion illustrates the use of assertion parameters and nested policy.</p><div class="figure" style="text-align: center"><br><img src="policy-assertion.jpg" alt="sp:IssuedToken Policy Assertion"><p style="text-align:left"><i><span>Figure 3-4. </span>sp:IssuedToken Policy Assertion</i></p><br></div><p>The <code>sp:IssuedToken</code> 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.</p><p>The <code>sp:IssuedToken</code> policy assertion has three parameters:
- <code>@sp:IncludeToken</code>, <code>sp:Issuer</code>
- and <code>sp:RequestSecurityTokenTemplate</code>.</p><p>The <code>sp:IncludeToken</code> attribute is a parameter that contains information on
+ <code>@sp:IncludeToken</code>, <code>sp:Issuer</code>
+ and <code>sp:RequestSecurityTokenTemplate</code>.</p><p>The <code>sp:IncludeToken</code> 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 <code>sp:Issuer</code> parameter is an
endpoint reference to a security token issuer. The
@@ -850,8 +829,8 @@
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.</p><p>The <code>sp:IssuedToken</code> policy assertion has a nested policy expression. The
- <code>sp:RequireInternalReference</code> element is a nested policy assertion of the
- <code>sp:IssuedToken</code> policy assertion. The
+ <code>sp:RequireInternalReference</code> element is a nested policy assertion of the
+ <code>sp:IssuedToken</code> policy assertion. The
<code>sp:RequireInternalReference</code> 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
@@ -863,161 +842,14 @@
by a third party. Service providers, like Contoso, 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 Contoso’s Web services.</p></div><div class="div2">
-<h3><a name="when-to-design-policy-assertions"></a>4.3 When to design policy assertions?</h3><p>As we illustrated in the previous section, requiring the use of a security token issued
- by a third party is represented as a policy assertion. In simple words, a policy assertion
- identifies a domain specific behavior:</p><ul><li><p>That is a requirement</p></li><li><p>That is relevant to an interoperable Web service interaction</p></li><li><p>That is relevant to an interaction that involves two or more Web service
- participants</p></li><li><p>That applies to its associated policy subject such as service, endpoint, operation
- and message.</p></li></ul><p>Given that interoperability and automation are the motivations, policy assertions that
- represent opt-in, shared and visible behaviors are useful pieces of metadata. Such
- assertions enable tooling and improve interoperability. The key to understanding when to
- design policy assertions is to have clarity on the characteristics of a behavior
- represented by a useful policy assertion: opt-in, shared and visible.</p><div class="div3">
-<h4><a name="opt-in-behavior"></a>4.3.1 Opt-in behavior</h4><p>An opt-in behavior refers to a requirement that providers and requesters must
- deliberately choose to engage for a successful web service interaction. Examples of such
- behaviors are the use of optimization, message-level security, reliable messaging and
- atomic transaction. Policy assertions are not necessary to interoperate on widespread
- assumed behaviors. An example of an assumed behavior is the use of UTF-8 or UTF-16 text
- encoding for XML messages. </p></div><div class="div3">
-<h4><a name="shared-behavior"></a>4.3.2 Shared behavior</h4><p>A shared behavior refers to a requirement that is relevant to an interoperable Web
- service interaction and involves two or more participants. If an assertion only
- describes one participant’s behavior (non-shared behavior) then the assertion is not
- relevant to an interoperable interaction. Non-shared behaviors do not add any value for
- tooling or interoperability. An example of a non-shared behavior is the use of logging
- or auditing by the provider.</p><p>requesters may use the policy intersection to select a compatible policy alternative
- for a Web service interaction. If an assertion only describes one participant’s behavior
- then this assertion will not be present in the other participants’ policy and the policy
- intersection will unnecessarily produce false negatives.</p></div><div class="div3">
-<h4><a name="visible-behavior"></a>4.3.3 Visible behavior</h4><p>A visible behavior refers to a requirement that manifests on the wire. Web services
- provide interoperable machine-to-machine interaction among disparate systems. Web
- service interoperability is the capability of disparate systems to exchange data using
- common data formats and protocols such as messaging, security, reliability and
- transaction. Such data formats and protocols manifest on the wire. Providers and
- requesters only rely on these wire messages that conform to such formats and protocols
- for interoperability. If an assertion describes a behavior that does not manifest on the
- wire then the assertion is not relevant to an interoperable interaction.</p><p>For example, say an assertion describes the privacy notice information of a provider
- and there is an associated regulatory safeguard in place on the provider’s side. Such
- assertions may represent business or regulatory level metadata but do not add any value
- to interoperability.</p><p>If an assertion has no wire- or message-level visible behavior, then the interacting
- participants may require some sort of additional non-repudiation mechanism to indicate
- compliance with the assertion. Introducing an additional non-repudiation mechanism adds
- unnecessary complexity to processing a policy assertion.</p></div></div><div class="div2">
-<h3><a name="guidelines-for-designing-assertions"></a>4.4 Guidelines for Designing Assertions</h3><p>The policy language allows assertion authors to invent their own XML dialects to
- represent policy assertions. The policy language builds on natural XML nesting and
- leverages XML Schema validation. The policy language relies only on the QName of the
- policy assertion XML element. Everything else is left for the policy assertion authors to
- design. The policy language offers plenty of options to assertion authors such as
- independent assertions, dependent assertions, nested policies and assertion parameters.</p><p>The description of a policy assertion should identify a single domain specific behavior
- in an objective manner and answer the following questions:</p><ul><li><p>What is the behavior? (In the previous section, we discussed the characteristics of a
- behavior represented by a useful policy assertion.)</p></li><li><p>What are the assertion parameters?</p></li><li><p>Are there any dependent behaviors, and how are they represented?</p></li><li><p>What is the assertion’s QName and XML information set representation?</p></li><li><p>What is the policy subject of this behavior?</p></li><li><p>What are the attachment points?</p></li></ul><p>As you would have expected, the policy assertion design is more than a technical design.
- Given that interoperability and automation are the motivations, policy assertion design is
- a business process to reach agreements with relevant stakeholders for interoperability and
- tooling. Setting aside the business aspects of the design, the rest of this section walks
- through a few tradeoffs or dimensions to consider and provides technical guidelines for
- designing policy assertions.</p><div class="div3">
-<h4><a name="optional-behaviors"></a>4.4.1 Optional Behaviors</h4><p>A policy assertion identifies a domain specific behavior that is a requirement relevant
- to a Web Service interaction. Policy assertions can be marked optional using
- the <code>wsp:Optional</code> attribute marker to represent behaviors that may be
- engaged (capabilities) for an interaction. It is important to note that behavior (policy
- assertion) and optional representation (<code>wsp:Optional</code> attribute) are
- distinct ideas of the Web Services Policy language. Conflating these distinct ideas
- unnecessarily disrupts scenarios that depend on the policy intersection: if an assertion
- indicates an optional behavior and this assertion is not present in the other
- participants’ policy then the policy intersection will unnecessarily produce false
- negatives.</p><p>Best practice: use the <code>wsp:Optional</code> attribute to indicate optional
- behaviors.</p></div><div class="div3">
-<h4><a name="assertion-vs-assertion-parameter"></a>4.4.2 Assertion vs. assertion parameter</h4><p>Policy assertion parameters are the opaque payload of an assertion. Parameters carry
- additional useful information for engaging the behavior described by an assertion and
- are preserved through policy processing such as normalize, merge and policy
- 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.</p><p>In the example below, <code>sp:Body</code> and <code>sp:Header</code> elements are the
- two assertion parameters of the <code>sp:SignedParts</code> policy assertion (this
- assertion requires the parts of a message to be protected). These two parameters
- identify the parts of a wire message that should be protected. These parameters carry
- additional useful information for engaging the behavior that is irrelevant to
- compatibility tests.</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-1. </span>Policy Assertion with Assertion Parameters</i></p><div class="exampleInner"><pre><Policy>
- <sp:SignedParts>
- <sp:Body />
- <sp:Header />
- </sp:SignedParts>
- …
-</Policy></pre></div></div><p>Best practice: represent useful (or additional) information necessary for engaging the
- behavior represented by a policy assertion as assertion parameters.</p></div><div class="div3">
-<h4><a name="leveraging-nested-policy"></a>4.4.3 Leveraging Nested Policy</h4><p>As we have seen before, a nested policy expression further qualifies the dependent
- behaviors of its parent policy assertion. When we consider nested policy there is always
- two or more policy assertions involved. The following design questions below can help
- you to determine when to use nested policy expressions:</p><p>Are these assertions designed for the same policy subject? </p><p>Do these assertions represent dependent behaviors?</p><p>If the answers are yes to both of these questions then leveraging nested policy
- expressions is a good idea. 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. 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.</p><p>Best practice: represent dependent behaviors that apply to the same policy subject
- using nested policy assertions.</p></div><div class="div3">
-<h4><a name="minimal-approach"></a>4.4.4 Minimal approach</h4><p>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. </p><p>Best practice: start with a simple working assertion that allows extensibility.</p></div><div class="div3">
-<h4><a name="QName_and_XML_Information_Set_representation"></a>4.4.5 QName and XML Information Set representation</h4><p>As mentioned before, 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.</p><p>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.</p><p>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.</p></div><div class="div3">
-<h4><a name="Policy_subject_and_attachment_points"></a>4.4.6 Policy subject and attachment points</h4><p>A behavior identified by a policy assertion applies to the associated policy subject.
- If a policy assertion is to be used with WSDL, policy assertion authors must specify a
- WSDL policy subject. What is the policy subject of this behavior?</p><ul><li><p>If the behavior applies to any message exchange using any of the endpoints offered
- by a service then the subject is the service policy subject.</p></li><li><p>If the behavior applies to any message exchange made using an endpoint then the
- subject is the endpoint policy subject.</p></li><li><p>If the behavior applies to any message exchange defined by an operation then the
- subject is the operation policy subject.</p></li><li><p>If the behavior applies to an input message then the subject is the message policy
- subject - similarly for output and fault message policy subjects.</p></li></ul><p>For a given WSDL policy subject, there may be several attachment points. For example,
- there are three attachment points for the endpoint policy subject: the
- <code>port</code>, <code>binding</code> and <code>portType</code> element. Policy
- assertion authors should identify the relevant attachment point when defining a new
- assertion. To determine the relevant attachment points, authors should consider the
- scope of the attachment point. For example, an assertion should only be allowed in the
- <code>portType</code> element if the assertion reasonably applies to any endpoint that
- ever references that <code>portType</code>. Most of the known policy assertions are
- designed for the endpoint, operation or message policy subject. The commonly used
- attachment points for these policy subjects are outlined in <a href="#attaching-policy-expressions-to-wsdl2"><b>3.5 Attaching Policy Expressions to WSDL</b></a>.</p><p>The service policy subject is a collection of endpoint policy subjects. The endpoint
- policy subject is a collection of operation policy subjects and etc. As you can see, the
- WSDL policy subjects compose naturally. It is quite tempting to associate the identified
- behavior to a broader policy subject than to a fine granular policy subject. For
- instance, it is convenient to attach a supporting token assertion (defined by the Web
- Services Security Policy specification) to an endpoint policy subject instead of a
- message policy subject. For authoring convenience, an assertion author may allow the
- association of an assertion to multiple policy subjects. If an assertion is allowed to
- be associated with multiple policy subjects then the assertion author has the burden to
- describe the semantics of multiple instances of the same assertion attached to multiple
- policy subjects at the same time. The best practice is to choose the most granular
- policy subject that the behavior applies to.</p><p>Best practice: specify a policy subject, choose the most granular policy subject that
- the behavior applies to and specify a preferred attachment point.</p></div><div class="div3">
-<h4><a name="versioning-behaviors"></a>4.4.7 Versioning behaviors</h4><p>Over time, there may be multiple equivalent behaviors emerging in the Web Service
- interaction space. Examples of such multiple equivalent behaviors are WSS: SOAP Message
- Security 1.0 vs. 1.1 and WS-Addressing August 2004 version vs. WS-Addressing W3C
- Recommendation. These equivalent behaviors are mutually exclusive for an interaction.
- Such equivalent behaviors can be modeled as independent assertions. The policy
- expression in the example below requires the use of WSS: SOAP Message Security 1.0.</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-2. </span>Message-level Security and WSS: SOAP Message Security 1.0</i></p><div class="exampleInner"><pre><Policy>
- <sp:Wss10>…</sp:Wss10>
-</Policy></pre></div></div><p>The policy expression in the example below requires the use of WSS: SOAP Message
- Security 1.1. These are multiple equivalent behaviors and are represented using distinct
- policy assertions.</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-3. </span>Message-level Security and WSS: SOAP Message Security 1.1</i></p><div class="exampleInner"><pre><Policy>
- <sp:Wss11>…</sp:Wss11>
-</Policy></pre></div></div><p>Best practice: use independent assertions for modeling multiple equivalent
- behaviors.</p></div><div class="div3">
-<h4><a name="versioning-policy-language"></a>4.4.8 Versioning Policy Language</h4><p>
- <table border="1" summary="Editorial note"><tr><td align="left" valign="top" width="50%"><b>Editorial note</b></td><td align="right" valign="top" width="50%"> </td></tr><tr><td colspan="2" align="left" valign="top">
- The WG is contemplating moving some or all of this material into a non-normative appendix of the framework or attachment document. User feedback is solicited
- </td></tr></table>
+<h3><a name="versioning-policy-language"></a>3.9 Versioning Policy Language</h3><p>
+ <table border="1" summary="Editorial note"><tr><td align="left" valign="top" width="50%"><b>Editorial note</b></td><td align="right" valign="top" width="50%"> </td></tr><tr><td colspan="2" align="left" valign="top">
+ The WG is contemplating moving some or all of this material into a non-normative appendix of the framework or attachment document. User feedback is solicited
+ </td></tr></table>
</p><p>Over time, the Policy WG or third parties can version or extend the Policy Language with new or modified constructs. These constructs may be compatible or incompatible with previous versions. Some of the possible new constructs that have been mentioned previously are: new operators, operator cardinality, policy identification, compact syntax, Policy Inclusion, security, referencing, attachment points, alternative
-priority, effective dating, negotiation. </p><p>WS-Policy provides extensibility points on 6 elements with a combination of attribute and/or element extensibility.
-The possible extensibility points with their current extensibility - including some outstanding issues related to extensibility - are:</p><ol><li><p>Policy: element from ##other namespace and any attribute</p></li><li><p>PolicyReference: any attribute and a proposal to add any element ExactlyOne, All: element from ##other namespace, no attribute extensibility</p></li><li><p>PolicyAttachment: element from ##other namespace and any attribute</p></li><li><p>AppliesTo: any element and any attribute</p></li></ol><div class="div4">
-<h5><a name="versioning-policy-framework"></a>4.4.8.1 Policy Framework</h5><p>WS-Policy Framework 1.5 specifies that any element that is not known inside a Policy, ExactlyOne or All will be treated as an assertion. The default value for wsp:Optional="false", which means after normalization it will be inside an ExactlyOne/All operator. </p><p>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:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-4. </span>Policy containing 1.5 and 1.6 Policies.</i></p><div class="exampleInner"><pre><wsp:Policy>
+ priority, effective dating, negotiation. </p><p>WS-Policy provides extensibility points on 6 elements with a combination of attribute and/or element extensibility.
+ The possible extensibility points with their current extensibility - including some outstanding issues related to extensibility - are:</p><ol><li><p>Policy: element from ##other namespace and any attribute</p></li><li><p>PolicyReference: any attribute and a proposal to add any element ExactlyOne, All: element from ##other namespace, no attribute extensibility</p></li><li><p>PolicyAttachment: element from ##other namespace and any attribute</p></li><li><p>AppliesTo: any element and any attribute</p></li></ol><div class="div3">
+<h4><a name="versioning-policy-framework"></a>3.9.1 Policy Framework</h4><p>WS-Policy Framework 1.5 specifies that any element that is not known inside a Policy, ExactlyOne or All will be treated as an assertion. The default value for wsp:Optional="false", which means after normalization it will be inside an ExactlyOne/All operator. </p><p>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:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 3-13. </span>Policy containing 1.5 and 1.6 Policies.</i></p><div class="exampleInner"><pre><wsp:Policy>
<wsp:ExactlyOne>
<wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
...
@@ -1026,7 +858,7 @@
...
</wsp:All>
</wsp:ExactlyOne>
-</wsp:Policy></pre></div></div><p>The normalization rule for wsp:Optional="false" would be applied to the wsp16:Choice, yielding the following expression:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-5. </span>Normalized Policy containing 1.5 and 1.6 Policies</i></p><div class="exampleInner"><pre><wsp:Policy>
+</wsp:Policy></pre></div></div><p>The normalization rule for wsp:Optional="false" would be applied to the wsp16:Choice, yielding the following expression:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 3-14. </span>Normalized Policy containing 1.5 and 1.6 Policies</i></p><div class="exampleInner"><pre><wsp:Policy>
<wsp:ExactlyOne>
<wsp:ExactlyOne>
<wsp:All>
@@ -1040,12 +872,12 @@
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy></pre></div></div><p>Alternatively, the wsp:Optional could be set to "true" on the choice, as
-in:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-6. </span>Policy containing explicit wsp:Optional="true"</i></p><div class="exampleInner"><pre><wsp:Policy>
+ in:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 3-15. </span>Policy containing explicit wsp:Optional="true"</i></p><div class="exampleInner"><pre><wsp:Policy>
<wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2"
wsp:Optional="true">
...
</wsp16:Choice>
-</wsp:Policy></pre></div></div><p>The normalized form will be:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-7. </span>Normalized policy</i></p><div class="exampleInner"><pre><wsp:Policy>
+</wsp:Policy></pre></div></div><p>The normalized form will be:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 3-16. </span>Normalized policy</i></p><div class="exampleInner"><pre><wsp:Policy>
<wsp:ExactlyOne>
<wsp:All>
<wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
@@ -1055,8 +887,8 @@
<wsp:All/>
</wsp:ExactlyOne>
</wsp:Policy></pre></div></div><p>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.
-</p><p>Note: it is possible to add new names to the existing namespace, such as: </p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-8. </span>Policy containing 1.5 and 1.6 Policies all in the 1.5 namespace</i></p><div class="exampleInner"><pre><wsp:Policy>
+ 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.
+ </p><p>Note: it is possible to add new names to the existing namespace, such as: </p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 3-17. </span>Policy containing 1.5 and 1.6 Policies all in the 1.5 namespace</i></p><div class="exampleInner"><pre><wsp:Policy>
<wsp:ExactlyOne>
<wsp:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
...
@@ -1066,7 +898,7 @@
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy></pre></div></div><p>Notice that using a new namespace can result in backwards and forwards compatibility if normalization results in an optional alternative. </p><p>Best practice: insert new elements in an optional alternative or mark with wsp:Optional="true". </p><p>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:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-9. </span>Policy containing 2.0 only Policies.</i></p><div class="exampleInner"><pre><wsp20:Policy>
+ 1.5:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 3-18. </span>Policy containing 2.0 only Policies.</i></p><div class="exampleInner"><pre><wsp20:Policy>
<wsp20:ExactlyOne>
<wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
...
@@ -1074,21 +906,21 @@
...
</wsp20:ExactlyOne>
</wsp20:Policy> </pre></div></div><p>The new Policy operator could be embedded inside an existing Policy
-element:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-10. </span>Policy containing 2.0 (incompatible with 1.5) Policies embedded in wsp 1.5 Policy.</i></p><div class="exampleInner"><pre><wsp:Policy>
+ element:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 3-19. </span>Policy containing 2.0 (incompatible with 1.5) Policies embedded in wsp 1.5 Policy.</i></p><div class="exampleInner"><pre><wsp:Policy>
<wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
...
</wsp20:Choice>
...
-</wsp20:Policy> </pre></div></div><p>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.</p><p>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.</p><p>A future version of WS-Policy could support the current operators in the existing namespace, such as:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-11. </span>Policy containing 1.5 operator in 2.0 Policy</i></p><div class="exampleInner"><pre><wsp20:Policy>
+</wsp20:Policy> </pre></div></div><p>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.</p><p>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.</p><p>A future version of WS-Policy could support the current operators in the existing namespace, such as:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 3-20. </span>Policy containing 1.5 operator in 2.0 Policy</i></p><div class="exampleInner"><pre><wsp20:Policy>
<wsp:ExactlyOne>
<wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
...
</wsp20:Choice>
...
</wsp:ExactlyOne>
-</wsp20:Policy> </pre></div></div><p>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.</p></div><div class="div4">
-<h5><a name="versioning-policy-attachment"></a>4.4.8.2 Policy Attachment</h5><p>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. </p><p>We show an example of a new version of policy that allows QName reference to Policies in the PolicyReference:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-12. </span>WSDL containing 1.5 and 2.0 (compatible with 2.0) Policy References.</i></p><div class="exampleInner"><pre><wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
+</wsp20:Policy> </pre></div></div><p>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.</p></div><div class="div3">
+<h4><a name="versioning-policy-attachment"></a>3.9.2 Policy Attachment</h4><p>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. </p><p>We show an example of a new version of policy that allows QName reference to Policies in the PolicyReference:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 3-21. </span>WSDL containing 1.5 and 2.0 (compatible with 2.0) Policy References.</i></p><div class="exampleInner"><pre><wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
<wsoap12:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http" />
<wsp:Policy>
@@ -1108,7 +940,7 @@
</wsp:ExactlyOne>
</wsp:Policy>
<wsdl11:operation name="GetLastTradePrice" > ....
- ...</pre></div></div><p>The PolicyReference element is attribute extensible. One example of an addition is a list of backup URIs for the PolicyReference:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 4-13. </span>WSDL containing 1.5 and 2.0 (compatible with 2.0) Policy References.</i></p><div class="exampleInner"><pre><wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
+ ...</pre></div></div><p>The PolicyReference element is attribute extensible. One example of an addition is a list of backup URIs for the PolicyReference:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 3-22. </span>WSDL containing 1.5 and 2.0 (compatible with 2.0) Policy References.</i></p><div class="exampleInner"><pre><wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
<wsoap12:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http" />
<wsp:Policy>
@@ -1122,17 +954,8 @@
</wsp:ExactlyOne>
</wsp:Policy>
<wsdl11:operation name="GetLastTradePrice" > ....
- ...</pre></div></div><p>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.</p><p>PolicyAttachment and AppliesTo also have extensibility points. We choose not to illustrate these at this time.</p></div></div></div><div class="div2">
-<h3><a name="describing-policy-assertions"></a>4.5 Describing Policy Assertions</h3><p>Thus far, we walked through the dimensions of a policy assertion and guidelines for
- authoring policy assertions. Let us look at what are the minimum requirements for
- describing policy assertions in specifications:</p><ol><li><p>Description must clearly and completely specify the syntax (plus an XML Schema
- document) and semantics of a policy assertion.</p></li><li><p>If there is a nested policy expression, description must declare it and enumerate the
- nested policy assertions that are allowed. </p></li><li><p>A policy alternative may contain multiple instances of the same policy assertion.
- Description must specify the semantics of parameters and nested policy (if any) when
- there are multiple instances of a policy assertion in the same policy alternative.
- </p></li><li><p>If a policy assertion is to be used with WSDL, description must specify a WSDL policy
- subject – such as service, endpoint, operation and message.</p></li></ol></div></div><div class="div1">
-<h2><a name="conclusion"></a>5. Conclusion</h2><p>Service providers use Web Services Policy to represent combinations of behaviors
+ ...</pre></div></div><p>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.</p><p>PolicyAttachment and AppliesTo also have extensibility points. We choose not to illustrate these at this time.</p></div></div></div><div class="div1">
+<h2><a name="conclusion"></a>4. Conclusion</h2><p>Service providers use Web Services Policy to represent combinations of behaviors
(capabilities and requirements). Web service developers use policy-aware clients that
understand policy expressions and engage the behaviors represented by providers
automatically. These behaviors may include security, reliability, transaction, message
@@ -1281,7 +1104,14 @@
on public-ws-policy@w3.org</a> are also gratefully
acknowledged.
</p></div><div class="div1">
-<h2><a name="change-description"></a>E. Changes in this Version of the Document (Non-Normative)</h2><p>A list of substantive changes since the previous publication is below:</p><ul><li><p>Replaced URI with IRI.</p></li><li><p>Added a new section - Versioning Policy Language.</p></li><li><p>Moved 'Security Considerations' section to the Web Services Policy 1.5 - Framework.</p></li></ul></div><div class="div1">
+<h2><a name="change-description"></a>E. Changes in this Version of the Document (Non-Normative)</h2><p>A list of substantive changes since the Working Draft dated 18 October, 2006 is below:</p><ul><li><p>Moved
+ Sections <a href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#parts-of-a-policy-assertion">
+ 4.2 Parts of a Policy Assertion</a> and
+ <a href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#versioning-policy-language">
+ 4.4.8 Versioning Policy Language</a> into Section <a href="#advanced-concepts-policy-expression"><b>3. Advanced Concepts: Policy Expression</b></a>;
+ moved Section
+ <a href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#advanced-concepts-2-policy-assertion-design">
+ 4 Advanced Concepts II: Policy Assertion Design</a> into the Guidelines document.</p></li></ul></div><div class="div1">
<h2><a name="change-log"></a>F. Web Services Policy 1.5 - Primer Change Log (Non-Normative)</h2><a name="ws-policy-primer-changelog-table"></a><table border="1"><tbody><tr><th rowspan="1" colspan="1">Date</th><th rowspan="1" colspan="1">Author</th><th rowspan="1" colspan="1">Description</th></tr><tr><td rowspan="1" colspan="1">20060816</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Created first draft per action item <a href="http://www.w3.org/2006/07/12-ws-policy-minutes.html#action02">2</a> from the
Austin F2F. This draft is based on a <a href="http://lists.w3.org/Archives/Public/public-ws-policy/2006Jul/0001.html">contribution</a> from Microsoft.</td></tr><tr><td rowspan="1" colspan="1">20060829</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Implemented the
<a href="http://www.w3.org/2006/08/23-ws-policy-minutes.html#action06">resolution</a>
@@ -1320,5 +1150,17 @@
</td></tr><tr><td rowspan="1" colspan="1">20061121</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Implemented the
<a href="http://www.w3.org/2006/11/15-ws-policy-minutes.html#item08">resolution</a> for issue
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3966">3966.</a>
- Editors Action Item <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/81">81.</a>
+ Editors Action Item <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/81">81</a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20061125</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Reset Section <a href="#change-description"><b>E. Changes in this Version of the Document</b></a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20061125</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Implemented the
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3792#c2">resolution</a> for issue
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3792">3792.</a>
+ Editors Action Item <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/80">80:</a> moved
+ Sections <a href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#parts-of-a-policy-assertion">
+ 4.2 Parts of a Policy Assertion</a> and
+ <a href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#versioning-policy-language">
+ 4.4.8 Versioning Policy Language</a> into Section <a href="#advanced-concepts-policy-expression"><b>3. Advanced Concepts: Policy Expression</b></a>;
+ moved Section
+ <a href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#advanced-concepts-2-policy-assertion-design">
+ 4 Advanced Concepts II: Policy Assertion Design</a> into the Guidelines document.
</td></tr></tbody></table><br></div></div></body></html>
\ No newline at end of file
Index: ws-policy-primer.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-primer.xml,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -d -r1.21 -r1.22
--- ws-policy-primer.xml 21 Nov 2006 20:36:43 -0000 1.21
+++ ws-policy-primer.xml 25 Nov 2006 23:40:10 -0000 1.22
@@ -96,7 +96,7 @@
Services Policy. It describes how to declare and combine capabilities and requirements of a
Web service as policy expressions, attach policy expressions to WSDL constructs such as
endpoint and message, and re-use policy expressions.</p>
- <p><specref ref="advanced-concepts-1-policy-expression"/> this is the first advanced section
+ <p><specref ref="advanced-concepts-policy-expression"/> this is the advanced section
that provides more in-depth materials for policy implementers and assertion authors. It
explains the basics of normalizing policy expressions, merging policies, determining the
compatibility (intersection) of policies, the policy data model, the policy expression and
@@ -637,10 +637,10 @@
hides complexity from developers and automates Web service interactions.</p>
</div2>
</div1>
- <div1 id="advanced-concepts-1-policy-expression">
- <head>Advanced Concepts I: Policy Expression</head>
+ <div1 id="advanced-concepts-policy-expression">
+ <head>Advanced Concepts: Policy Expression</head>
<p>In <specref ref="basic-concepts-policy-expression"/>, we covered the basics of Web Services
- Policy language. This is the first advanced section that provides more in-depth materials
+ Policy language. This is the advanced section that provides more in-depth materials
for Web Services Policy implementers and assertion authors. This section covers the
following topics:</p>
<ulist>
@@ -666,6 +666,9 @@
<item>
<p>What are the extensibility points?</p>
</item>
+ <item>
+ <p>What are the parts of a policy assertion?</p>
+ </item>
</ulist>
<div2 id="policy-expression">
<head>Policy Expression</head>
@@ -1144,6 +1147,7 @@
insignificant. Therefore, the order of combining these policy expressions is
insignificant.</p>
</div2>
+
<div2 id="extensibility-and-versioning">
<head>Extensibility and Versioning</head>
<p>Web Services Policy language is an extensible language by design. The
@@ -1217,53 +1221,6 @@
known WSDL constructs and allows Web service developers to fill in code for custom or
unknown constructs in the WSDL.</p>
</div2>
- </div1>
- <div1 id="advanced-concepts-2-policy-assertion-design">
- <head>Advanced Concepts II: Policy Assertion Design</head>
- <p>In the previous section, we covered in-depth materials for Web Services Policy
- implementers. This is the second advanced section that walks through the dimensions of a
- policy assertion for assertion authors. This section covers the following topics:</p>
- <ulist>
- <item>
- <p>What is the role of policy assertions?</p>
- </item>
- <item>
- <p>What are the parts of a policy assertion?</p>
- </item>
- <item>
- <p>When to design policy assertions?</p>
- </item>
- <item>
- <p>What are the guidelines for designing policy assertions?</p>
- </item>
- <item>
- <p>What are the minimum requirements for describing policy assertions?</p>
- </item>
- </ulist>
- <div2 id="role-of-policy-assertions">
- <head>Role of Policy Assertions</head>
- <p>As you have seen, Web Services Policy is a simple language that has four elements
- -<code>Policy, All</code>, <code>ExactlyOne</code> and <code>PolicyReference</code> -
- and one attribute - <code>wsp:Optional</code>. Policy is a flexible language to represent
- consistent combinations of behaviors using policy operators: <code>Policy, All</code> and
- <code>ExactlyOne.</code> Policy is an expressive language and capable of representing
- behaviors from a variety of domains. Let us look for the key parts that unlock this
- potential.</p>
- <p>Service providers combine behaviors for an interaction from domains such as messaging,
- security, reliability and transactions. To enable clients to engage these behaviors,
- services require some way to advertise these behaviors. Providers require machine readable
- metadata pieces that identify these behaviors. A policy assertion is a machine-readable
- metadata piece that requires the use of a behavior identified by the assertion. Web
- service developers can use policy-aware clients that recognize these assertions and engage
- their corresponding behaviors automatically.</p>
- <p>Policy assertions are the key parts and play a central role to unlock the potential
- offered by the Web Services Policy language. Assertions are defined by product designers,
- protocol authors, protocol implementers and Web service developers.</p>
- <p>Policy assertion authors identify behaviors required for Web services interactions and
- represent these behaviors as policy assertions. By designing policy assertions, assertion
- authors make a significant contribution to automate Web services interactions and enable
- advanced behaviors.</p>
- </div2>
<div2 id="parts-of-a-policy-assertion">
<head>Parts of a Policy Assertion</head>
<p>As we discussed, a policy assertion identifies a domain specific behavior or requirement
@@ -1278,8 +1235,8 @@
policy assertion is an XML element. The QName of this element represents the behavior
identified by this policy assertion.</p>
<p>The <code>sp:IssuedToken</code> policy assertion has three parameters:
- <code>@sp:IncludeToken</code>, <code>sp:Issuer</code>
- and <code>sp:RequestSecurityTokenTemplate</code>.</p>
+ <code>@sp:IncludeToken</code>, <code>sp:Issuer</code>
+ and <code>sp:RequestSecurityTokenTemplate</code>.</p>
<p>The <code>sp:IncludeToken</code> 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 <code>sp:Issuer</code> parameter is an
@@ -1298,8 +1255,8 @@
policy language allows assertion authors to strongly tie the relationship between an
assertion and its parameters using the natural XML structural relationships.</p>
<p>The <code>sp:IssuedToken</code> policy assertion has a nested policy expression. The
- <code>sp:RequireInternalReference</code> element is a nested policy assertion of the
- <code>sp:IssuedToken</code> policy assertion. The
+ <code>sp:RequireInternalReference</code> element is a nested policy assertion of the
+ <code>sp:IssuedToken</code> policy assertion. The
<code>sp:RequireInternalReference</code> 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
@@ -1313,294 +1270,30 @@
necessary information to obtain this security token for Web service developers. This is a
key piece of metadata for a successful interaction with Contoso’s Web services.</p>
</div2>
- <div2 id="when-to-design-policy-assertions">
- <head>When to design policy assertions?</head>
- <p>As we illustrated in the previous section, requiring the use of a security token issued
- by a third party is represented as a policy assertion. In simple words, a policy assertion
- identifies a domain specific behavior:</p>
- <ulist>
- <item>
- <p>That is a requirement</p>
- </item>
- <item>
- <p>That is relevant to an interoperable Web service interaction</p>
- </item>
- <item>
- <p>That is relevant to an interaction that involves two or more Web service
- participants</p>
- </item>
- <item>
- <p>That applies to its associated policy subject such as service, endpoint, operation
- and message.</p>
- </item>
- </ulist>
- <p>Given that interoperability and automation are the motivations, policy assertions that
- represent opt-in, shared and visible behaviors are useful pieces of metadata. Such
- assertions enable tooling and improve interoperability. The key to understanding when to
- design policy assertions is to have clarity on the characteristics of a behavior
- represented by a useful policy assertion: opt-in, shared and visible.</p>
- <div3 id="opt-in-behavior">
- <head>Opt-in behavior</head>
- <p>An opt-in behavior refers to a requirement that providers and requesters must
- deliberately choose to engage for a successful web service interaction. Examples of such
- behaviors are the use of optimization, message-level security, reliable messaging and
- atomic transaction. Policy assertions are not necessary to interoperate on widespread
- assumed behaviors. An example of an assumed behavior is the use of UTF-8 or UTF-16 text
- encoding for XML messages. </p>
- </div3>
- <div3 id="shared-behavior">
- <head>Shared behavior</head>
- <p>A shared behavior refers to a requirement that is relevant to an interoperable Web
- service interaction and involves two or more participants. If an assertion only
- describes one participant’s behavior (non-shared behavior) then the assertion is not
- relevant to an interoperable interaction. Non-shared behaviors do not add any value for
- tooling or interoperability. An example of a non-shared behavior is the use of logging
- or auditing by the provider.</p>
- <p>requesters may use the policy intersection to select a compatible policy alternative
- for a Web service interaction. If an assertion only describes one participant’s behavior
- then this assertion will not be present in the other participants’ policy and the policy
- intersection will unnecessarily produce false negatives.</p>
- </div3>
- <div3 id="visible-behavior">
- <head>Visible behavior</head>
- <p>A visible behavior refers to a requirement that manifests on the wire. Web services
- provide interoperable machine-to-machine interaction among disparate systems. Web
- service interoperability is the capability of disparate systems to exchange data using
- common data formats and protocols such as messaging, security, reliability and
- transaction. Such data formats and protocols manifest on the wire. Providers and
- requesters only rely on these wire messages that conform to such formats and protocols
- for interoperability. If an assertion describes a behavior that does not manifest on the
- wire then the assertion is not relevant to an interoperable interaction.</p>
- <p>For example, say an assertion describes the privacy notice information of a provider
- and there is an associated regulatory safeguard in place on the provider’s side. Such
- assertions may represent business or regulatory level metadata but do not add any value
- to interoperability.</p>
- <p>If an assertion has no wire- or message-level visible behavior, then the interacting
- participants may require some sort of additional non-repudiation mechanism to indicate
- compliance with the assertion. Introducing an additional non-repudiation mechanism adds
- unnecessary complexity to processing a policy assertion.</p>
- </div3>
- </div2>
- <div2 id="guidelines-for-designing-assertions">
- <head>Guidelines for Designing Assertions</head>
- <p>The policy language allows assertion authors to invent their own XML dialects to
- represent policy assertions. The policy language builds on natural XML nesting and
- leverages XML Schema validation. The policy language relies only on the QName of the
- policy assertion XML element. Everything else is left for the policy assertion authors to
- design. The policy language offers plenty of options to assertion authors such as
- independent assertions, dependent assertions, nested policies and assertion parameters.</p>
- <p>The description of a policy assertion should identify a single domain specific behavior
- in an objective manner and answer the following questions:</p>
- <ulist>
- <item>
- <p>What is the behavior? (In the previous section, we discussed the characteristics of a
- behavior represented by a useful policy assertion.)</p>
- </item>
- <item>
- <p>What are the assertion parameters?</p>
- </item>
- <item>
- <p>Are there any dependent behaviors, and how are they represented?</p>
- </item>
- <item>
- <p>What is the assertion’s QName and XML information set representation?</p>
- </item>
- <item>
- <p>What is the policy subject of this behavior?</p>
- </item>
- <item>
- <p>What are the attachment points?</p>
- </item>
- </ulist>
- <p>As you would have expected, the policy assertion design is more than a technical design.
- Given that interoperability and automation are the motivations, policy assertion design is
- a business process to reach agreements with relevant stakeholders for interoperability and
- tooling. Setting aside the business aspects of the design, the rest of this section walks
- through a few tradeoffs or dimensions to consider and provides technical guidelines for
- designing policy assertions.</p>
- <div3 id="optional-behaviors">
- <head>Optional Behaviors</head>
- <p>A policy assertion identifies a domain specific behavior that is a requirement relevant
- to a Web Service interaction. Policy assertions can be marked optional using
- the <code>wsp:Optional</code> attribute marker to represent behaviors that may be
- engaged (capabilities) for an interaction. It is important to note that behavior (policy
- assertion) and optional representation (<code>wsp:Optional</code> attribute) are
- distinct ideas of the Web Services Policy language. Conflating these distinct ideas
- unnecessarily disrupts scenarios that depend on the policy intersection: if an assertion
- indicates an optional behavior and this assertion is not present in the other
- participants’ policy then the policy intersection will unnecessarily produce false
- negatives.</p>
- <p>Best practice: use the <code>wsp:Optional</code> attribute to indicate optional
- behaviors.</p>
- </div3>
- <div3 id="assertion-vs-assertion-parameter">
- <head>Assertion vs. assertion parameter</head>
- <p>Policy assertion parameters are the opaque payload of an assertion. Parameters carry
- additional useful information for engaging the behavior described by an assertion and
- are preserved through policy processing such as normalize, merge and policy
- 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.</p>
- <p>In the example below, <code>sp:Body</code> and <code>sp:Header</code> elements are the
- two assertion parameters of the <code>sp:SignedParts</code> policy assertion (this
- assertion requires the parts of a message to be protected). These two parameters
- identify the parts of a wire message that should be protected. These parameters carry
- additional useful information for engaging the behavior that is irrelevant to
- compatibility tests.</p>
- <example>
- <head>Policy Assertion with Assertion Parameters</head>
- <eg xml:space="preserve"><Policy>
- <sp:SignedParts>
- <sp:Body />
- <sp:Header />
- </sp:SignedParts>
- …
-</Policy></eg>
- </example>
- <p>Best practice: represent useful (or additional) information necessary for engaging the
- behavior represented by a policy assertion as assertion parameters.</p>
- </div3>
- <div3 id="leveraging-nested-policy">
- <head>Leveraging Nested Policy</head>
- <p>As we have seen before, a nested policy expression further qualifies the dependent
- behaviors of its parent policy assertion. When we consider nested policy there is always
- two or more policy assertions involved. The following design questions below can help
- you to determine when to use nested policy expressions:</p>
- <p>Are these assertions designed for the same policy subject? </p>
- <p>Do these assertions represent dependent behaviors?</p>
- <p>If the answers are yes to both of these questions then leveraging nested policy
- expressions is a good idea. 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. 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.</p>
- <p>Best practice: represent dependent behaviors that apply to the same policy subject
- using nested policy assertions.</p>
- </div3>
- <div3 id="minimal-approach">
- <head>Minimal approach</head>
- <p>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. </p>
- <p>Best practice: start with a simple working assertion that allows extensibility.</p>
- </div3>
- <div3 id="QName_and_XML_Information_Set_representation">
- <head>QName and XML Information Set representation</head>
- <p>As mentioned before, 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.</p>
- <p>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.</p>
- <p>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.</p>
- </div3>
- <div3 id="Policy_subject_and_attachment_points">
- <head>Policy subject and attachment points</head>
- <p>A behavior identified by a policy assertion applies to the associated policy subject.
- If a policy assertion is to be used with WSDL, policy assertion authors must specify a
- WSDL policy subject. What is the policy subject of this behavior?</p>
- <ulist>
- <item>
- <p>If the behavior applies to any message exchange using any of the endpoints offered
- by a service then the subject is the service policy subject.</p>
- </item>
- <item>
- <p>If the behavior applies to any message exchange made using an endpoint then the
- subject is the endpoint policy subject.</p>
- </item>
- <item>
- <p>If the behavior applies to any message exchange defined by an operation then the
- subject is the operation policy subject.</p>
- </item>
- <item>
- <p>If the behavior applies to an input message then the subject is the message policy
- subject - similarly for output and fault message policy subjects.</p>
- </item>
- </ulist>
- <p>For a given WSDL policy subject, there may be several attachment points. For example,
- there are three attachment points for the endpoint policy subject: the
- <code>port</code>, <code>binding</code> and <code>portType</code> element. Policy
- assertion authors should identify the relevant attachment point when defining a new
- assertion. To determine the relevant attachment points, authors should consider the
- scope of the attachment point. For example, an assertion should only be allowed in the
- <code>portType</code> element if the assertion reasonably applies to any endpoint that
- ever references that <code>portType</code>. Most of the known policy assertions are
- designed for the endpoint, operation or message policy subject. The commonly used
- attachment points for these policy subjects are outlined in <specref
- ref="attaching-policy-expressions-to-wsdl2"/>.</p>
- <p>The service policy subject is a collection of endpoint policy subjects. The endpoint
- policy subject is a collection of operation policy subjects and etc. As you can see, the
- WSDL policy subjects compose naturally. It is quite tempting to associate the identified
- behavior to a broader policy subject than to a fine granular policy subject. For
- instance, it is convenient to attach a supporting token assertion (defined by the Web
- Services Security Policy specification) to an endpoint policy subject instead of a
- message policy subject. For authoring convenience, an assertion author may allow the
- association of an assertion to multiple policy subjects. If an assertion is allowed to
- be associated with multiple policy subjects then the assertion author has the burden to
- describe the semantics of multiple instances of the same assertion attached to multiple
- policy subjects at the same time. The best practice is to choose the most granular
- policy subject that the behavior applies to.</p>
- <p>Best practice: specify a policy subject, choose the most granular policy subject that
- the behavior applies to and specify a preferred attachment point.</p>
- </div3>
- <div3 id="versioning-behaviors">
- <head>Versioning behaviors</head>
- <p>Over time, there may be multiple equivalent behaviors emerging in the Web Service
- interaction space. Examples of such multiple equivalent behaviors are WSS: SOAP Message
- Security 1.0 vs. 1.1 and WS-Addressing August 2004 version vs. WS-Addressing W3C
- Recommendation. These equivalent behaviors are mutually exclusive for an interaction.
- Such equivalent behaviors can be modeled as independent assertions. The policy
- expression in the example below requires the use of WSS: SOAP Message Security 1.0.</p>
- <example>
- <head>Message-level Security and WSS: SOAP Message Security 1.0</head>
- <eg xml:space="preserve"><Policy>
- <sp:Wss10>…</sp:Wss10>
-</Policy></eg>
- </example>
- <p>The policy expression in the example below requires the use of WSS: SOAP Message
- Security 1.1. These are multiple equivalent behaviors and are represented using distinct
- policy assertions.</p>
- <example>
- <head>Message-level Security and WSS: SOAP Message Security 1.1</head>
- <eg xml:space="preserve"><Policy>
- <sp:Wss11>…</sp:Wss11>
-</Policy></eg>
- </example>
- <p>Best practice: use independent assertions for modeling multiple equivalent
- behaviors.</p>
- </div3>
- <div3 id="versioning-policy-language"><head>Versioning Policy Language</head>
+ <div2 id="versioning-policy-language"><head>Versioning Policy Language</head>
<p>
- <ednote>
- <edtext>
- The WG is contemplating moving some or all of this material into a non-normative appendix of the framework or attachment document. User feedback is solicited
- </edtext>
- </ednote>
+ <ednote>
+ <edtext>
+ The WG is contemplating moving some or all of this material into a non-normative appendix of the framework or attachment document. User feedback is solicited
+ </edtext>
+ </ednote>
</p>
<p>Over time, the Policy WG or third parties can version or extend the Policy Language with new or modified constructs. These constructs may be compatible or incompatible with previous versions. Some of the possible new constructs that have been mentioned previously are: new operators, operator cardinality, policy identification, compact syntax, Policy Inclusion, security, referencing, attachment points, alternative
-priority, effective dating, negotiation. </p>
-<p>WS-Policy provides extensibility points on 6 elements with a combination of attribute and/or element extensibility.
-The possible extensibility points with their current extensibility - including some outstanding issues related to extensibility - are:</p>
-<olist>
-<item><p>Policy: element from ##other namespace and any attribute</p></item>
-<item><p>PolicyReference: any attribute and a proposal to add any element ExactlyOne, All: element from ##other namespace, no attribute extensibility</p></item>
-<item><p>PolicyAttachment: element from ##other namespace and any attribute</p></item>
-<item><p>AppliesTo: any element and any attribute</p></item>
-</olist>
-
-<div4 id="versioning-policy-framework"><head>Policy Framework</head>
-<p>WS-Policy Framework 1.5 specifies that any element that is not known inside a Policy, ExactlyOne or All will be treated as an assertion. The default value for wsp:Optional="false", which means after normalization it will be inside an ExactlyOne/All operator. </p>
-<p>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:</p>
-<example><head>Policy containing 1.5 and 1.6 Policies.</head>
-<eg><![CDATA[<wsp:Policy>
+ priority, effective dating, negotiation. </p>
+ <p>WS-Policy provides extensibility points on 6 elements with a combination of attribute and/or element extensibility.
+ The possible extensibility points with their current extensibility - including some outstanding issues related to extensibility - are:</p>
+ <olist>
+ <item><p>Policy: element from ##other namespace and any attribute</p></item>
+ <item><p>PolicyReference: any attribute and a proposal to add any element ExactlyOne, All: element from ##other namespace, no attribute extensibility</p></item>
+ <item><p>PolicyAttachment: element from ##other namespace and any attribute</p></item>
+ <item><p>AppliesTo: any element and any attribute</p></item>
+ </olist>
+
+ <div3 id="versioning-policy-framework"><head>Policy Framework</head>
+ <p>WS-Policy Framework 1.5 specifies that any element that is not known inside a Policy, ExactlyOne or All will be treated as an assertion. The default value for wsp:Optional="false", which means after normalization it will be inside an ExactlyOne/All operator. </p>
+ <p>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:</p>
+ <example><head>Policy containing 1.5 and 1.6 Policies.</head>
+ <eg><![CDATA[<wsp:Policy>
<wsp:ExactlyOne>
<wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
...
@@ -1610,10 +1303,10 @@
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>]]></eg>
-</example>
-<p>The normalization rule for wsp:Optional="false" would be applied to the wsp16:Choice, yielding the following expression:</p>
-<example><head>Normalized Policy containing 1.5 and 1.6 Policies</head>
-<eg><![CDATA[<wsp:Policy>
+ </example>
+ <p>The normalization rule for wsp:Optional="false" would be applied to the wsp16:Choice, yielding the following expression:</p>
+ <example><head>Normalized Policy containing 1.5 and 1.6 Policies</head>
+ <eg><![CDATA[<wsp:Policy>
<wsp:ExactlyOne>
<wsp:ExactlyOne>
<wsp:All>
@@ -1627,20 +1320,20 @@
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>]]></eg>
-</example>
-<p>Alternatively, the wsp:Optional could be set to "true" on the choice, as
-in:</p>
-<example><head>Policy containing explicit wsp:Optional="true"</head>
-<eg><![CDATA[<wsp:Policy>
+ </example>
+ <p>Alternatively, the wsp:Optional could be set to "true" on the choice, as
+ in:</p>
+ <example><head>Policy containing explicit wsp:Optional="true"</head>
+ <eg><![CDATA[<wsp:Policy>
<wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2"
wsp:Optional="true">
...
</wsp16:Choice>
</wsp:Policy>]]></eg>
-</example>
-<p>The normalized form will be:</p>
-<example><head>Normalized policy</head>
-<eg><![CDATA[<wsp:Policy>
+ </example>
+ <p>The normalized form will be:</p>
+ <example><head>Normalized policy</head>
+ <eg><![CDATA[<wsp:Policy>
<wsp:ExactlyOne>
<wsp:All>
<wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
@@ -1650,13 +1343,13 @@
<wsp:All/>
</wsp:ExactlyOne>
</wsp:Policy>]]></eg>
-</example>
-<p>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.
-</p>
-<p>Note: it is possible to add new names to the existing namespace, such as: </p>
-<example><head>Policy containing 1.5 and 1.6 Policies all in the 1.5 namespace</head>
-<eg><![CDATA[<wsp:Policy>
+ </example>
+ <p>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.
+ </p>
+ <p>Note: it is possible to add new names to the existing namespace, such as: </p>
+ <example><head>Policy containing 1.5 and 1.6 Policies all in the 1.5 namespace</head>
+ <eg><![CDATA[<wsp:Policy>
<wsp:ExactlyOne>
<wsp:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
...
@@ -1666,17 +1359,17 @@
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>]]></eg>
-</example>
-
-<p>Notice that using a new namespace can result in backwards and forwards compatibility if normalization results in an optional alternative. </p>
-
-<p>Best practice: insert new elements in an optional alternative or mark with wsp:Optional="true". </p>
-
-<p>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:</p>
-
-<example><head>Policy containing 2.0 only Policies.</head>
-<eg><![CDATA[<wsp20:Policy>
+ </example>
+
+ <p>Notice that using a new namespace can result in backwards and forwards compatibility if normalization results in an optional alternative. </p>
+
+ <p>Best practice: insert new elements in an optional alternative or mark with wsp:Optional="true". </p>
+
+ <p>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:</p>
+
+ <example><head>Policy containing 2.0 only Policies.</head>
+ <eg><![CDATA[<wsp20:Policy>
<wsp20:ExactlyOne>
<wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
...
@@ -1684,27 +1377,27 @@
...
</wsp20:ExactlyOne>
</wsp20:Policy> ]]></eg>
-</example>
-
-<p>The new Policy operator could be embedded inside an existing Policy
-element:</p>
-
-<example><head>Policy containing 2.0 (incompatible with 1.5) Policies embedded in wsp 1.5 Policy.</head>
-<eg><![CDATA[<wsp:Policy>
+ </example>
+
+ <p>The new Policy operator could be embedded inside an existing Policy
+ element:</p>
+
+ <example><head>Policy containing 2.0 (incompatible with 1.5) Policies embedded in wsp 1.5 Policy.</head>
+ <eg><![CDATA[<wsp:Policy>
<wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
...
</wsp20:Choice>
...
</wsp20:Policy> ]]></eg>
-</example>
-
-<p>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.</p>
-
-<p>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.</p>
-
-<p>A future version of WS-Policy could support the current operators in the existing namespace, such as:</p>
-<example><head>Policy containing 1.5 operator in 2.0 Policy</head>
-<eg><![CDATA[<wsp20:Policy>
+ </example>
+
+ <p>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.</p>
+
+ <p>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.</p>
+
+ <p>A future version of WS-Policy could support the current operators in the existing namespace, such as:</p>
+ <example><head>Policy containing 1.5 operator in 2.0 Policy</head>
+ <eg><![CDATA[<wsp20:Policy>
<wsp:ExactlyOne>
<wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
...
@@ -1712,18 +1405,18 @@
...
</wsp:ExactlyOne>
</wsp20:Policy> ]]></eg>
-</example>
-
-<p>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.</p>
-</div4>
-<div4 id="versioning-policy-attachment"><head>Policy Attachment</head>
-<p>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. </p>
-
-<p>We show an example of a new version of policy that allows QName reference to Policies in the PolicyReference:</p>
-
-<example><head>WSDL containing 1.5 and 2.0 (compatible with 2.0) Policy References.</head>
-<eg><![CDATA[<wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
+ </example>
+
+ <p>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.</p>
+ </div3>
+ <div3 id="versioning-policy-attachment"><head>Policy Attachment</head>
+ <p>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. </p>
+
+ <p>We show an example of a new version of policy that allows QName reference to Policies in the PolicyReference:</p>
+
+ <example><head>WSDL containing 1.5 and 2.0 (compatible with 2.0) Policy References.</head>
+ <eg><![CDATA[<wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
<wsoap12:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http" />
<wsp:Policy>
@@ -1744,12 +1437,12 @@
</wsp:Policy>
<wsdl11:operation name="GetLastTradePrice" > ....
...]]></eg>
- </example>
-
-<p>The PolicyReference element is attribute extensible. One example of an addition is a list of backup URIs for the PolicyReference:</p>
-
-<example><head>WSDL containing 1.5 and 2.0 (compatible with 2.0) Policy References.</head>
-<eg><![CDATA[<wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
+ </example>
+
+ <p>The PolicyReference element is attribute extensible. One example of an addition is a list of backup URIs for the PolicyReference:</p>
+
+ <example><head>WSDL containing 1.5 and 2.0 (compatible with 2.0) Policy References.</head>
+ <eg><![CDATA[<wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
<wsoap12:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http" />
<wsp:Policy>
@@ -1764,40 +1457,14 @@
</wsp:Policy>
<wsdl11:operation name="GetLastTradePrice" > ....
...]]></eg>
-</example>
-<p>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.</p>
-
-<p>PolicyAttachment and AppliesTo also have extensibility points. We choose not to illustrate these at this time.</p>
-</div4>
-</div3>
- </div2>
- <div2 id="describing-policy-assertions">
- <head>Describing Policy Assertions</head>
- <p>Thus far, we walked through the dimensions of a policy assertion and guidelines for
- authoring policy assertions. Let us look at what are the minimum requirements for
- describing policy assertions in specifications:</p>
- <olist>
- <item>
- <p>Description must clearly and completely specify the syntax (plus an XML Schema
- document) and semantics of a policy assertion.</p>
- </item>
- <item>
- <p>If there is a nested policy expression, description must declare it and enumerate the
- nested policy assertions that are allowed. </p>
- </item>
- <item>
- <p>A policy alternative may contain multiple instances of the same policy assertion.
- Description must specify the semantics of parameters and nested policy (if any) when
- there are multiple instances of a policy assertion in the same policy alternative.
- </p>
- </item>
- <item>
- <p>If a policy assertion is to be used with WSDL, description must specify a WSDL policy
- subject – such as service, endpoint, operation and message.</p>
- </item>
- </olist>
+ </example>
+ <p>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.</p>
+
+ <p>PolicyAttachment and AppliesTo also have extensibility points. We choose not to illustrate these at this time.</p>
+ </div3>
</div2>
</div1>
+
<div1 id="conclusion">
<head>Conclusion</head>
<p>Service providers use Web Services Policy to represent combinations of behaviors
@@ -2050,11 +1717,16 @@
</blist>
</div1> &acknowledgements; <inform-div1 id="change-description">
<head>Changes in this Version of the Document</head>
- <p>A list of substantive changes since the previous publication is below:</p>
+ <p>A list of substantive changes since the Working Draft dated 18 October, 2006 is below:</p>
<ulist>
- <item><p>Replaced URI with IRI.</p></item>
- <item><p>Added a new section - Versioning Policy Language.</p></item>
- <item><p>Moved 'Security Considerations' section to the &framework.title;.</p></item>
+ <item><p>Moved
+ Sections <loc href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#parts-of-a-policy-assertion">
+ 4.2 Parts of a Policy Assertion</loc> and
+ <loc href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#versioning-policy-language">
+ 4.4.8 Versioning Policy Language</loc> into Section <specref ref="advanced-concepts-policy-expression"/>;
+ moved Section
+ <loc href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#advanced-concepts-2-policy-assertion-design">
+ 4 Advanced Concepts II: Policy Assertion Design</loc> into the Guidelines document.</p></item>
</ulist>
</inform-div1>
<inform-div1 id="change-log">
@@ -2177,7 +1849,29 @@
<td>Implemented the
<loc href="http://www.w3.org/2006/11/15-ws-policy-minutes.html#item08">resolution</loc> for issue
<loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3966">3966.</loc>
- Editors Action Item <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/81">81.</loc>
+ Editors Action Item <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/81">81</loc>.
+ </td>
+ </tr>
+ <tr>
+ <td>20061125</td>
+ <td>ASV</td>
+ <td>Reset Section <specref ref="change-description"/>.
+ </td>
+ </tr>
+ <tr>
+ <td>20061125</td>
+ <td>ASV</td>
+ <td>Implemented the
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3792#c2">resolution</loc> for issue
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3792">3792.</loc>
+ Editors Action Item <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/80">80:</loc> moved
+ Sections <loc href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#parts-of-a-policy-assertion">
+ 4.2 Parts of a Policy Assertion</loc> and
+ <loc href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#versioning-policy-language">
+ 4.4.8 Versioning Policy Language</loc> into Section <specref ref="advanced-concepts-policy-expression"/>;
+ moved Section
+ <loc href="http://www.w3.org/TR/2006/WD-ws-policy-primer-20061018/#advanced-concepts-2-policy-assertion-design">
+ 4 Advanced Concepts II: Policy Assertion Design</loc> into the Guidelines document.
</td>
</tr>
</tbody>
Received on Saturday, 25 November 2006 23:40:37 UTC