- From: Maryann Hondo via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 26 Dec 2006 19:03:28 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv9003
Modified Files:
ws-policy-guidelines.xml
Log Message:
implemented changes for editor action 106, bug entry 3983, reconciling terms for "Assertion Authors"
Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -d -r1.22 -r1.23
--- ws-policy-guidelines.xml 20 Dec 2006 19:52:22 -0000 1.22
+++ ws-policy-guidelines.xml 26 Dec 2006 19:03:25 -0000 1.23
@@ -93,7 +93,7 @@
A policy assertion is a machine readable metadata expression that
identifies behaviors required for Web services interactions.
<emph>&guideline.title;</emph>
- is a resource primarily for assertion authors and provides
+ is a resource primarily for Assertion Authors and provides
guidelines on the use of &framework.title; and
&attachment.title; specifications to create and use domain specific
assertions to enable interoperability.
@@ -117,7 +117,7 @@
</p>
</item>
<item>
- <p>WS-Policy assertion authors who need to know the features
+ <p>Assertion Authors who need to know the features
of the language and understand the requirements for
describing policy assertions.
</p>
@@ -132,7 +132,7 @@
</item>
<item>
<p>Providers of policy expressions who need to understand
- how to use the assertions authored by policy assertion authors
+ how to use the assertions authored by Assertion Authors
</p>
</item>
</ulist>
@@ -230,7 +230,7 @@
</ulist>
<p>There are already many examples in the industry that adhere to the above practices, such as <bibref ref="WS-RM-Policy"/>
- and <bibref ref="WS-SecurityPolicy"/>. Some common characteristics from these documents may be considered as <emph>best practices</emph> for new assertion authors:
+ and <bibref ref="WS-SecurityPolicy"/>. Some common characteristics from these documents may be considered as <emph>best practices</emph> for new Assertion Authors:
</p>
<ulist>
<item>
@@ -251,7 +251,7 @@
specification will be well informed and able to adequately specify assertions for their domain.
</p>
<p>It is expected that consumers of the metadata specified by
- the assertion authors will also benefit from understanding these
+ the Assertion Authors will also benefit from understanding these
practices as it will help them utilize the assertions in the
context of the WS-Policy framework. A result of following the
best practices will be an assertion specification that describes
@@ -282,14 +282,14 @@
</p>
<div3 id="domain-owners">
- <head> WS-Policy Authors</head>
- <p> WS-Policy Domain owners or WS-Policy authors are defined
+ <head> Assertion Authors</head>
+ <p>Assertion Authors are defined
by the WS-Policy Framework to be a community that chooses to
exploit the WS-Policy Framework by creating their own
specification to define a set of assertions that express the
capabilities and constraints of that target domain. The
WS-Policy Framework is based on a declarative model, meaning
- that it is incumbent on the WS-Policy authors to define both the semantics of
+ that it is incumbent on the Assertion Authors to define both the semantics of
the assertions as well as the scope of their target domain in their specification. The set
of metadata for any particular domain will vary in the granularity of assertion
specification required. It is the intent of
@@ -298,11 +298,11 @@
consumers and providers can utilize the framework consistently across domains.
</p>
<p>When using the WS-Policy Framework, any
- domain author defining new WS-Policy assertions
+ Assertion Authors defining new WS-Policy assertions
must adhere to the MUST's and SHOULD's in the specification
and should review the conformance section of the specification.
</p>
- <p>WS-Policy Domain authors must also specify how to associate
+ <p>Assertion Authors must also specify how to associate
the assertions they have defined with the policy subjects
identified by the WS-PolicyAttachment specification.
</p>
@@ -384,10 +384,10 @@
</div1>
<div1 id="general-guidelines">
- <head>General Guidelines for WS-Policy Assertion Authors</head>
- <p> As authors begin the task of inventing XML dialects to represent policy assertions they can take
+ <head>General Guidelines for Assertion Authors</head>
+ <p> As Assertion Authors begin the task of inventing XML dialects to represent policy assertions they can take
advantage of WS-Policy building on XML principles and XML Schema validation in their design. WS-Policy
- relies on the QName of a policy assertion being an XML element but allows authors to optionally
+ relies on the QName of a policy assertion being an XML element but allows Assertuib Authors to optionally
provide additional semantics through nesting assertions, or specifying assertion parameters.
This section covers several aspects of assertion design and provides some answers to the following questions:</p>
<ulist>
@@ -414,12 +414,12 @@
<div2 id="assertion-target">
<head>Assertions and Their Target Use</head>
- <p>WS-Policy authors need to have some definition of what the goal is for the assertions
- they author. WS-Policy authors should also understand the
+ <p>Assertion Authors need to have some definition of what the goal is for the assertions
+ they author. Assertion Authors should also understand the
functionality the WS-Policy framework provides and apply the
knowledge of framework processing when defining the set of assertions.
</p>
- <p>Assertions can be simple or they can be complex. WS-Policy authors may choose to specify one or two
+ <p>Assertions can be simple or they can be complex. Assertion Authors may choose to specify one or two
assertions or they may choose to specify many assertion
elements that require parameters or other nested
assertions. There are advantages to simplifying the set of
@@ -451,7 +451,7 @@
attachment in multiple WSDL files or Endpoint
References in which the same set of policies are expected to be applied.
</p>
- <p>Best practice: WS-Policy authors should include the following
+ <p>Best practice: Assertion Authors should include the following
items in the dialect specification:
</p>
<ulist>
@@ -581,13 +581,13 @@
</p>
<div3 id="minimal-approach">
<head>Minimal approach</head>
- <p>New policy authors are encouraged to try to not overload assertions. A single assertion indicates a single
+ <p>New Assertion Authors are encouraged to try to not overload assertions. A single assertion indicates a single
behavior. Sets of assertions can by grouped by an operator "all". This indicates that there is a relationship between
the assertions and they now constitute a policy alternative.
</p>
<p>If grouping is utilized, choices between alternatives can be indicated by
an "exactly one" operator. This basic set of operators allows
- authors a wide range of options for expressing the possible combinations of assertions within their domain.
+ Assertion Authors a wide range of options for expressing the possible combinations of assertions within their domain.
</p>
<p>It requires a good deal of effort to evaluate the
capabilities of a domain and capture them in a way that
@@ -596,8 +596,8 @@
domains is recommended to ensure that consumers and providers
are able to use the new domain assertions.
</p>
- <p>New authors are encouraged to look at <bibref ref="WS-RM-Policy"/> to see an example of a
- relatively simple domain that has defined three assertions. Domain authors are encouraged to look at <bibref
+ <p>New Assertion Authors are encouraged to look at <bibref ref="WS-RM-Policy"/> to see an example of a
+ relatively simple domain that has defined three assertions. Assertion Authors are encouraged to look at <bibref
ref="WS-SecurityPolicy"/> to see an example of a complex domain that has been decomposed into a set of policy expressions.
</p>
<p>How big should an assertion be? How many assertion parameters should the assertion
@@ -611,10 +611,10 @@
</div3>
<div3 id="QName_and_XML_Information_Set_representation">
<head>QName and XML Information Set representation</head>
- <p>Web Services Policy language allows assertion authors to invent
+ <p>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
+ 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>
@@ -646,18 +646,18 @@
endpoint, or those that are required in a particular message; the
latter are the intended uses of the WS-Policy framework.
</p>
- <p>As a result, the assertion authors should take into account that the following important concepts
+ <p>As a result, the Assertion Authors should take into account that the following important concepts
when designing assertions and documenting the semantics of the
assertion types.
</p>
<p>Firstly, an assertion type indicates a <emph>runtime</emph> behavior.
</p>
- <p>Secondly, authors need to indicate how the runtime behavior represented in the assertion type can be inferred or indicated
+ <p>Secondly, Assertion Authors need to indicate how the runtime behavior represented in the assertion type can be inferred or indicated
from a message at runtime. If there is a need for the behavior
to be represented in a persistent way or if there is a need for
additional data or metadata that is present in a message to be
persisted, it should be incorporated into the assertion design or
- in the message itself. In essence, the assertion authors should
+ in the message itself. In essence, the Assertion Authors should
consider how to make messages self describing when utilizing
their assertions by specifying additional properties, headers,
etc. that must be present in a message as part of their assertion design.
@@ -688,7 +688,7 @@
will determine whether a particular set of assertions
correctly characterize a domain. A new community should avoid
duplicating assertions that have already been defined as this
- will create ambiguity not clarification. New WS-Policy authors
+ will create ambiguity not clarification. New Assertion Authors
should focus on creating assertions for those specific
constraints and capabilities that do not overlap with other
domains but that communicate new functionality.
@@ -717,8 +717,7 @@
<div3 id="parameterized-assertions">
<head>Assertions with Parameters</head>
- <p>The framework allows WS-Policy
- domain authors to define parameters, for example, to
+ <p>The framework allows Assertion Authors to define parameters, for example, to
qualify an assertion. For some domains it will be appropriate
to specify these parameters instead of nesting assertion elements.
</p>
@@ -759,7 +758,7 @@
</p>
<p>We will use the WS-SecurityPolicy to illustrate the use of nested assertions.
</p>
- <p>Securing messages is a complex usage scenario. The WS-SecurityPolicy authors have defined the
+ <p>Securing messages is a complex usage scenario. The WS-SecurityPolicy Assertion Authors have defined the
<code>sp:TransportBinding</code> policy assertion to indicate
the use of transport-level security for protecting
messages. Just indicating the use of transport-level security
@@ -832,7 +831,7 @@
parameters in its algorithm</emph>.
</p>
- <p>Domain authors should recognize that the framework can
+ <p>Assertion Authors should recognize that the framework can
yield multiple assertions of the same type. The <emph>QName</emph>
of the assertion is the only vehicle for the framework to
match a specific assertion, NOT the contents of the
@@ -861,7 +860,7 @@
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: If the domain
+ <p>Best practice: If the assertion
authors want to delegate the processing to the framework,
utilizing nesting should be considered. Otherwise, domain
specific comparison algorithms will need to be devised and be
@@ -910,7 +909,7 @@
the provider can determine whether the policy alternate that
contains the MTOM assertion is being selected.</p>
- <p>Assertion authors should be aware that optional behaviors,
+ <p>Assertion Authors should be aware that optional behaviors,
like utilizing optional support for Optimized MIME
Serialization require some care considering the scoping of the assertion that is applicable. </p>
<ulist>
@@ -936,14 +935,14 @@
</item>
<item>
<p> The target scope of an optional assertion is an important factor for
- assertion authors to consider as it determines the
+ Assertion Authors to consider as it determines the
<emph>granularity</emph> where the behavior is optionally
engaged. For example, if the assertion is targeted for an
endpoint policy subject, it is expected to govern all the
messages that are indicated by the specific endpoint when
optional behavior is <emph> engaged </emph>. Since the
behavior would be applicable to policy subject that is
- designated, it is important for the policy assertion authors
+ designated, it is important for the Assertion Authors
to choose the appropriate level of granularity for optional
behaviors, to consider whether a specific message or all messages, etc. are targeted.
</p>
@@ -962,7 +961,7 @@
if a request-response interaction only specified MTOM
optimization for an inbound message, it would not be clear
whether the outbound message from the provider could also
- utilize the behavior. Therefore, the assertion authors are
+ utilize the behavior. Therefore, the Assertion Authors are
encouraged to consider how the attachment on a message
policy subject on a response message should be treated
when optional behaviors are specified for message
@@ -972,8 +971,8 @@
(i.e. if the incoming message utilized the optimization,
the response will be returned utilizing the MTOM
serialization). Similarly, if engagement of a behavior is
- only specified for an outbound message, the policy
- assertion authors should consider describing the
+ only specified for an outbound message, the
+ Assertion Authors should consider describing the
semantics if the incoming messages also utilized the
behavior. This is especially important if the assertion is
applicable to more than one specific policy subject. One
@@ -984,7 +983,7 @@
</p>
</item>
</ulist>
- <p>Best Practice: Optional assertion authors should explicitly state
+ <p>Best Practice: Optional Assertion Authors should explicitly state
how the behavior that is enabled by the assertion would be
engaged when they are designing their assertion, whether by
specific headers or some other means. See also <specref ref="self-describing"/>.
@@ -994,7 +993,7 @@
<div2 id="typing-assertions">
<head>Typing Assertions</head>
<p>Since a <emph>QName</emph> is the central mechanism for
- identifying a policy assertion, assertion authors should be
+ identifying a policy assertion, Assertion Authors should be
aware of the possible evolution of their assertions and how
this would impact the semantics of the assertion overtime. A namespace
associated with the assertion may be used to indicate a
@@ -1017,7 +1016,7 @@
</p>
<p>Thus our example encryption assertion would have a
subject of "message", and could only be attached to
- messages, where the assertion is valid. However, authors
+ messages, where the assertion is valid. However, Assertion Authors
need to be aware that <emph>policy attachment subjects are
not limited to the subjects defined in WSDL</emph>. The
external attachment model in WS-PolicyAttachment allows for
@@ -1055,7 +1054,7 @@
<head>Levels of Abstraction in WSDL </head>
<p>A behavior identified by a policy assertion applies to the
associated policy subject. If a policy assertion is to be used
- within WSDL, policy assertion authors must specify a WSDL
+ within WSDL, Assertion Authors must specify a WSDL
policy subject. The policy subject is determined with respect
to a behavior as follows:
</p>
@@ -1078,14 +1077,14 @@
the subject is the message policy subject - similarly for output and fault message policy subjects.</p>
</item>
</ulist>
- <p>WS-Policy authors that wish to utilize WSDL policy subjects need to understand how the assertions will be
+ <p>Assertion Authors that wish to utilize WSDL policy subjects need to understand how the assertions will be
processed in intersection and merging and the implications of
the processing for considering a specific attachment point and
policy subject. This topic is considered in detail in <bibref ref="WS-Policy-Primer"/>
</p>
<p>The current set of subjects as mapped to the WSDL 1.1
elements, can also constrain the assertion constructs. For Example, In WS-RM,
- the domain authors chose to support certain capabilities at
+ the Assertion Authors chose to support certain capabilities at
the endpoint level. This resulted in the finer granularity of
the assertion to apply at the message policy subject, but the
assertion semantics also indicates that the if
@@ -1098,7 +1097,7 @@
</p>
<p>If the capability is not really suitable and may imply
different semantics with respect to attachment points, the
- assertion authors should consider the following</p>
+ Assertion Authors should consider the following</p>
<ulist>
<item>
<p> Decompose the semantics with several assertions </p>
@@ -1110,9 +1109,9 @@
<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 port, binding and
- portType element. Policy assertion authors should identify the
+ portType element. Assertion Authors should identify the
relevant attachment point when defining a new assertion. To
- determine the relevant attachment points, authors should
+ determine the relevant attachment points, Assertion Authors should
consider the scope of the attachment point. For example, an
assertion should only be allowed in the portType element if
the assertion reasonably applies to any endpoint that ever
@@ -1155,7 +1154,7 @@
</div1>
<div1 id="lifecycle">
<head>Lifecycle of Assertions</head>
- <p>WS-Policy authors need to consider not just the expression of the current set of requirements but
+ <p>Assertion Authors need to consider not just the expression of the current set of requirements but
how they anticipate new assertions being added to the set. There are three aspects that govern an assertions lifecycle:</p>
<ulist>
<item>
@@ -1166,7 +1165,7 @@
<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.
</p>
- <p> Policy authors should review the WS-Policy Primer <bibref ref="WS-Policy-Primer"/>
+ <p> Assertion Authors should review the WS-Policy Primer <bibref ref="WS-Policy-Primer"/>
and the specifications <bibref ref="WS-Policy"/> <bibref ref="WS-PolicyAttachment"/>
for details on extensibility.
</p>
@@ -1190,7 +1189,7 @@
<p>The <bibref ref="WS-Policy-Primer"/> illustrates how
providers can utilize the identification mechanism defined in the Policy specification
to expose a complex policy expression as a reusable building block for
- other policy expressions by reference. Domain assertion
+ other policy expressions by reference. Assertion
authors, especially those defining complex assertions that
include nesting or complex types should consider specifying or recommending
naming conventions in order to promote reuse. Reuse through
@@ -1232,7 +1231,7 @@
<div1 id="inter-policy">
<head>Inter-domain Policy and Composition Issues</head>
- <p>Domain authors must be aware of the interactions between their
+ <p>Assertion Authors must be aware of the interactions between their
domain and other domains. For example, security assertions interact
with other protocol assertions in a composition. Although
modeling protocol assertions may appear to be an independent behavior,
@@ -1241,7 +1240,7 @@
example utilization of WS-Security Policy with other
protocols affects transport bindings and would result in nested
policy assertions when additional protocols are composed with
- <bibref ref="WS-Security2004"/>. Thus, domain authors should
+ <bibref ref="WS-Security2004"/>. Thus, Assertion Authors should
be aware of the compositional semantics with other related
domains. The protocol assertions that require composition
with WS-Security should be particularly aware of the nesting
@@ -1406,10 +1405,10 @@
second profile that included two security options. The details of
the Bindings, requires a more detailed exploration of some of the
other features of the WS-Policy Framework. </p>
- <p>When WS-Policy authors create sets of Policy assertions, like
+ <p>When Assertion Authors create sets of Policy assertions, like
WS-Security Policy they need to consider expressing the semantics
of their domain in a way that policy consumers, like Company A,
- can utilize them. In this case, the WS-SecurityPolicy authors
+ can utilize them. In this case, the WS-SecurityPolicy Assertion Authors
factored out common elements of security mechanisms and utilized a
feature of WS-Policy called "nested" assertions. In the case of
an <code>sp:TransportBinding</code> assertion, just indicating the use of
@@ -1521,7 +1520,7 @@
</wsdl:binding></eg>
</example>
<p>In some cases, companies may chose to implement their own
- assertions. When companies chose to become policy authors they need
+ assertions. When companies chose to become Assertion Authors they need
to consider not only the definition of the behavior that the
assertion represents but they need to consider how new assertions
will be intersected and merged with other assertions in the
@@ -1873,6 +1872,14 @@
after editorial reviews by co-editors.
</td>
</tr>
+ <tr>
+ <td>20061226</td>
+ <td>MH</td>
+ <td>Editorial revision: reconciled terms related to "Assertion Authors"
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/106">106</loc>
+ and bug http://www.w3.org/Bugs/Public/show_bug.cgi?id=3983
+ </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Tuesday, 26 December 2006 19:03:38 UTC