This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.

Bug 3989 - [Guidelines] Suggested Format
Summary: [Guidelines] Suggested Format
Status: RESOLVED FIXED
Alias: None
Product: WS-Policy
Classification: Unclassified
Component: Guidelines (show other bugs)
Version: FPWD
Hardware: PC Windows XP
: P2 normal
Target Milestone: ---
Assignee: Felix Sasaki
QA Contact: Web Services Policy WG QA List
URL:
Whiteboard:
Keywords:
Depends on:
Blocks: 3988
  Show dependency treegraph
 
Reported: 2006-11-18 01:30 UTC by Asir V Selvasingh
Modified: 2007-06-06 17:39 UTC (History)
0 users

See Also:


Attachments

Description Asir V Selvasingh 2006-11-18 01:30:53 UTC
Title: Suggested format for the Guidelines document.

Description:

Guidelines and best practices in the Guidelines document [1] are hidden in the prose. They are not easy to pull out.

Assertion authors would find it very useful if the Guidelines document identifies a scenario, articulates the problem statement at the assertion design level, enumerates the factors to be considered and highlights good practices.

The Architecture of the WWW document [2] is a good model to follow. Furthermore, providing the assertion authors with a list of good practice statements upfront (for instance [3]) would be very useful.

Justification: 

Guidelines and best practices are hidden in the prose. Assertion authors need to read this document multiple times and dig for guidelines and best practices. If the guidelines are clear and easy to find, the WG (and other WGs such as I18N WG) will find it easy to review the document, build consensus and adopt them.

Target: Guidelines for Assertion Authors.

Proposal:

We suggest using good practice statements as the center stage to describe the guidelines for assertion authors. We request the WG to consider the following possibilities:

a) Use a format similar to the Architecture of the WWW document
b) Provide a list of good practice statements upfront (after the Table of Contents or in the Introduction).
c) Both a and b.

[1] http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-guidelines.html?rev=1.8&content-type=text/html;%20charset=utf-8 
[2] http://www.w3.org/TR/webarch/ 
[3] http://www.w3.org/TR/webarch/#p10
Comment 1 Christopher Ferris 2007-03-14 18:48:59 UTC
When resolving this issue, we should check to ensure that the content of the removed section 4.6 is captured in the new best practices summary.

Removed section 4.6:

4.6 Typing Assertions

Since a QName is the central mechanism for 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 specific version of an assertion but this has its limitations. See section 5. Versioning Policy Assertions for more detail.

The typing must be done in combination with the scoping of the semantics to a policy subject. WS-PolicyAttachment provides a means of associating an assertion with arbitrary subjects, regardless of their nature. This flexibility can lead to ambiguity in the interpretation of policy; for example, if one attaches an assertion with the semantic "must be encrypted" to a SOAP endpoint, it's unclear what must be encrypted.

One way to disambiguate the semantic is to generally determine if an assertion is specific to a policy attachment mechanism. An example could be identifying whether the assertion expressed is associated with behaviors (endpoints) or artifacts (messages) and then constraining the use of an assertion to one of these subjects.

Thus our example encryption assertion would have a subject of "message", and could only be attached to messages, where the assertion is valid. However, Assertion Authors need to be aware that policy attachment subjects are not limited to the subjects defined in WSDL. The external attachment model in WS-PolicyAttachment allows for the definition of other domain expressions to be policy subjects. More of this topic is covered in the Web Services Policy Primer

Best Practice- To avoid confusion, assertion definitions should be precise about their semantics and include information that restricts their set of permissible policy subjects appropriately and indicates which QNames are associated with which subjects.

   1.

      Description must clearly and completely specify the syntax (plus an XML Schema document) and semantics of a policy assertion.
   2.

      If there is a nested policy expression, description must declare it and enumerate the nested policy assertions that are allowed.
   3.

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

      If a policy assertion is to be used with WSDL, description must specify a WSDL policy subject  such as service, endpoint, operation and message.
Comment 2 Christopher Ferris 2007-06-06 17:39:16 UTC
See http://www.w3.org/2007/06/06-ws-policy-irc#T17-38-36
Resolution: close issue 3989 with the updated Guidelines draft delivered by the editors for the Ottawa F2F