Web Services Policy 1.5 - Framework

Editors' copy $Date: 2007/01/16 22:09:00 $ @@ @@@@ @@@@

2. Notations and Terminology

This section specifies the notations, namespaces, and terminology used in this specification.

2.1 Notational Conventions

This specification uses the following syntax within normative outlines:

  • The syntax appears as an XML instance, but values in italics indicate data types instead of literal values.

  • Characters are appended to elements and attributes to indicate cardinality:

    • "?" (0 or 1)

    • "*" (0 or more)

    • "+" (1 or more)

  • The character "|" is used to indicate a choice between alternatives.

  • The characters "(" and ")" are used to indicate that contained items are to be treated as a group with respect to cardinality or choice.

  • This document relies on the XML Information Set [XML Information Set]. Information items properties are indicated by the style [infoset property].

  • XML namespace prefixes (see Table 2-1) are used to indicate the namespace of the element or attribute being defined.

  • The ellipses characters "…" are used to indicate a point of extensibility that allows other Element or Attribute Information Items.

Elements and Attributes defined by this specification are referred to in the text of this document using XPath 1.0 [XPATH 1.0] expressions. Extensibility points are referred to using an extended version of this syntax:

  • An element extensibility point is referred to using {any} in place of the element name. This indicates that any element name can be used, from any namespace, unless specified otherwise such as in Section 4.3.3 Policy Operators.

  • An attribute extensibility point is referred to using @{any} in place of the attribute name. This indicates that any attribute name can be used, from any namespace.

Normative text within this specification takes precedence over normative outlines, which in turn take precedence over the XML Schema [XML Schema Structures] descriptions.

....

....

4.3 Compact Policy Expression

To express a policy in a more compact form while still using the XML Infoset, this specification defines three constructs: an attribute to decorate an assertion, semantics for recursively nested policy operators, and a policy reference/inclusion mechanism. A policy expression consists of a wsp:Policy wrapper element and a variety of child and descendent elements. Each is described in the subsections below.

To interpret a compact expression in an interoperable form, a compact expression may be converted to the corresponding normal form expression by the following procedure:

  1. Start with the [document element] property D of the Document Information Item (as defined in the XML Information Set [XML Information Set]) of the policy expression. The [namespace name] of D is always "http://www.w3.org/@@@@/@@/ws-policy". In the base case, the [local name] property of D is "Policy"; in the recursive case, the [local name] property of D is "Policy", "ExactlyOne", or "All".
  2. Expand Element Information Items (as defined in the XML Information Set [XML Information Set]) in the [children] property of D that are policy references per Section 4.3.5 Policy Inclusion.
  3. Convert each Element Information Item C in the [children] property of D into normal form.
    1. If the [namespace name] property of C is "http://www.w3.org/@@@@/@@/ws-policy" and the [local name] property of C is "Policy", "ExactlyOne", or "All", C is an expression of a policy operator; normalize C by recursively applying this procedure.
    2. Otherwise the Element Information Item C is an assertion; normalize C per Sections 4.3.1 Optional Policy Assertions and 4.3.2 Policy Assertion Nesting.
  4. Apply the policy operator indicated by D to the normalized Element Information Items in its [children] property and construct a normal form per Section 4.3.3 Policy Operators.

Note that an implementation may use a more efficient procedure and is not required to explicitly convert a compact expression into the normal form as long as the processing results are indistinguishable from doing so.

...

...

4.3.3 Policy Operators

Policies are used to convey a set of capabilities, requirements, and general characteristics of entities (see 1. Introduction). These are generally expressible as a set of policy alternatives. Policy operators (wsp:Policy , wsp:All and wsp:ExactlyOne elements) are used to group policy assertions into policy alternatives. In some instances, complex policies expressed in normal form can get relatively large and hard to manage. To compactly express complex policies, policy operators MAY be recursively nested; that is, one or more instances of wsp:Policy , wsp:All , and/or wsp:ExactlyOne MAY be nested within wsp:Policy , wsp:All , and/or wsp:ExactlyOne .

 

The schema outline for the wsp:Policy element (in the compact form) is as follows:

(01) <wsp:Policy … >
(02)   ( <wsp:Policy>…</wsp:Policy> |
(03)     <wsp:ExactlyOne>…</wsp:ExactlyOne> |
(04)     <wsp:All>…</wsp:All> |
(05)     <wsp:PolicyReference>…</wsp:PolicyReference> |
(06)     …
(07)   )* 
(08) </wsp:Policy> 

The following describes the Attribute and Element Information Items defined in the schema outline above:

/wsp:Policy
This element is the wsp:Policy operator.
/wsp:Policy/wsp:Policy
This element is a nested wsp:Policy operator.
/wsp:Policy/wsp:ExactlyOne
This element is a nested  wsp:ExactlyOne operator.
/wsp:Policy/wsp:All
This element is a nested wsp:All operator.
/wsp:Policy/wsp:PolicyReference
This element references a policy expression to be included per Section 4.3.5 Policy Inclusion.
/wsp:Policy/@{any}
Additional attributes MAY be specified but MUST NOT contradict the semantics of the [owner element]; if an attribute is not recognized, it SHOULD be ignored.
/wsp:Policy/{any}
Additio/nal elements MAY be specified but MUST NOT use the Web Services Policy language XML namespace name and MUST NOT contradict the semantics of the [parent element]; if an element is not recognized, it MUST be treated as an assertion.

The schema outline for the wsp:ExactlyOne element (in the compact form) is as follows:

(01) <wsp:ExactlyOne>
(02)   ( <wsp:Policy>…</wsp:Policy> |
(03)     <wsp:ExactlyOne>…</wsp:ExactlyOne> |
(04)     <wsp:All>…</wsp:All> |
(05)     <wsp:PolicyReference>…</wsp:PolicyReference> |
(06)     …
(07)   )* 
(08) </wsp:ExactlyOne> 

The following describes the Attribute and Element Information Items defined in the schema outline above:

/wsp:ExactlyOne
This element is the wsp:ExactlyOne operator.
/wsp:ExactlyOne/wsp:Policy
This element is a nested  wsp:Policy operator.
/wsp:ExactlyOne/wsp:ExactlyOne
This element is a nested wsp:ExactlyOne operator.
/wsp:ExactlyOne/wsp:All
This element is a nested wsp:All operator.
/wsp:ExactlyOne/wsp:PolicyReference
This element references a policy expression to be included per Section 4.3.5 Policy Inclusion.
/wsp:ExactlyOne/{any}
Additional elements MAY be specified but MUST NOT use the Web Services Policy language XML namespace name and MUST NOT contradict the semantics of the [parent element]; if an element is not recognized, it MUST be treated as an assertion.

The schema outline for the wsp:All element (in the compact form) is as follows:

(01) <wsp:All>
(02)   ( <wsp:Policy>…</wsp:Policy> |
(03)     <wsp:ExactlyOne>…</wsp:ExactlyOne> |
(04)     <wsp:All>…</wsp:All> |
(05)     <wsp:PolicyReference>…</wsp:PolicyReference> |
(06)     …
(07)   )* 
(08) </wsp:All> 

The following describes the Attribute and Element Information Items defined in the schema outline above:

/wsp:All
This element is the wsp:All operator.
/wsp:All/wsp:Policy
This element is a nested wsp:Policy operator.
/wsp:All/wsp:ExactlyOne
This element is a nested wsp:ExactlyOne operator.
/wsp:All/wsp:All
This element is a nested wsp:All operator.
/wsp:All/wsp:PolicyReference
This element references a policy expression to be included per Section 4.3.5 Policy Inclusion.
/wsp:All/{any}
Additional elements MAY be specified but MUST NOT use the Web Services Policy language XML namespace name and MUST NOT contradict the semantics of the [parent element]; if an element is not recognized, it MUST be treated as an assertion.

The following rules are used to transform a compact policy expression into a normal form policy expression:

Equivalence

Use of wsp:Policy as an operator within a policy expression is equivalent to wsp:All .

Empty

  • <wsp:All /> expresses a policy with zero policy assertions. Note that since wsp:Policy is equivalent to wsp:All , <wsp:Policy /> is therefore equivalent to <wsp:All />, i.e., a policy alternative with zero assertions.

  • <wsp:ExactlyOne /> expresses a policy with zero policy alternatives.

Commutative

In line with the previous statements that policy assertions within a policy alternative and policy alternatives within a policy are not ordered (see 3.2 Policy Alternative and 3.3 Policy, respectively), wsp:All and wsp:ExactlyOne are commutative. For example,

(01) <wsp:All> <!-- assertion 1 --> <!-- assertion 2 --> </wsp:All>

is equivalent to:

(01) <wsp:All> <!-- assertion 2 --> <!-- assertion 1 --> </wsp:All>

and:

(01) <wsp:ExactlyOne>
(02)   <!-- assertion 1 --> <!-- assertion 2 -->
(03) </wsp:ExactlyOne>

is equivalent to:

(01) <wsp:ExactlyOne>
(02)   <!-- assertion 2 --> <!-- assertion 1 -->
(03) </wsp:ExactlyOne>
Associative

wsp:All and wsp:ExactlyOne are associative. For example,

(01) <wsp:All>
(02)   <!-- assertion 1 -->
(03)   <wsp:All> <!-- assertion 2 --> </wsp:All>
(04) </wsp:All>

is equivalent to:

(01) <wsp:All> <!-- assertion 1 --> <!-- assertion 2 --> </wsp:All>

and:

(01) <wsp:ExactlyOne>
(02)   <!-- assertion 1 -->
(03)   <wsp:ExactlyOne> <!-- assertion 2 --> </wsp:ExactlyOne>
(04) </wsp:ExactlyOne>

is equivalent to:

(01) <wsp:ExactlyOne>
(02)   <!-- assertion 1 --> <!-- assertion 2 -->
(03) </wsp:ExactlyOne>
Idempotent

wsp:All and wsp:ExactlyOne are idempotent. For example,

(01) <wsp:All>
(02)   <wsp:All> <!-- assertion 1 --> <!-- assertion 2 --> </wsp:All>
(03) </wsp:All>

is equivalent to:

(01) <wsp:All> <!-- assertion 1 --> <!-- assertion 2 --> </wsp:All>

and:

(01) <wsp:ExactlyOne>
(02)   <wsp:ExactlyOne>
(03)     <!-- assertion 1 --> <!-- assertion 2 -->
(04)   </wsp:ExactlyOne>
(05) </wsp:ExactlyOne>

is equivalent to:

(01) <wsp:ExactlyOne>
(02)   <!-- assertion 1 --> <!-- assertion 2 -->
(03) </wsp:ExactlyOne>
Distributive

wsp:All distributes over wsp:ExactlyOne . For example,

(01) <wsp:All>
(02)   <wsp:ExactlyOne>
(03)     <!-- assertion 1 -->
(04)     <!-- assertion 2 -->
(05)   </wsp:ExactlyOne>
(06) </wsp:All>

is equivalent to:

(01) <wsp:ExactlyOne>
(02)   <wsp:All>
(03)     <!-- assertion 1 -->
(04)   </wsp:All>
(05)   <wsp:All>
(06)     <!-- assertion 2 -->
(07)   </wsp:All>
(08) </wsp:ExactlyOne>

Similarly by repeatedly distributing wsp:All over wsp:ExactlyOne,

(01) <wsp:All>
(02)   <wsp:ExactlyOne>
(03)     <!-- assertion 1 -->
(04)     <!-- assertion 2 -->
(05)   </wsp:ExactlyOne>
(06)   <wsp:ExactlyOne>
(07)     <!-- assertion 3 -->
(08)     <!-- assertion 4 -->
(09)   </wsp:ExactlyOne>
(10) </wsp:All>

is equivalent to:

(01) <wsp:ExactlyOne>
(02)   <wsp:All><!-- assertion 1 --><!-- assertion 3 --></wsp:All>
(03)   <wsp:All><!-- assertion 1 --><!-- assertion 4 --></wsp:All>
(04)   <wsp:All><!-- assertion 2 --><!-- assertion 3 --></wsp:All>
(05)   <wsp:All><!-- assertion 2 --><!-- assertion 4 --></wsp:All>
(06) </wsp:ExactlyOne>

Distributing wsp:All over an empty wsp:ExactlyOne is equivalent to no alternatives. For example,

(01) <wsp:All>
(02)   <wsp:ExactlyOne>
(03)     <!-- assertion 1 -->
(04)     <!-- assertion 2 -->
(05)   </wsp:ExactlyOne>
(06)   <wsp:ExactlyOne />
(07) </wsp:All>

is equivalent to:

(01) <wsp:ExactlyOne />

For example, given the following compact policy expression:

(01) <wsp:Policy
        xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"
        xmlns:wsp="http://www.w3.org/@@@@/@@/ws-policy" >
(02)   <sp:RequireDerivedKeys wsp:Optional="true" />
(03)   <wsp:ExactlyOne>
(04)     <sp:WssUsernameToken10 />
(05)     <sp:WssUsernameToken11 />
(06)   </wsp:ExactlyOne>
(07) </wsp:Policy>

Applying Section 4.3.1 Optional Policy Assertions to @wsp:Optional in Line (02), and distributing wsp:All over wsp:ExactlyOne per Section 4.3.3 Policy Operators for the assertions in Lines (04-05) yields:

(01) <wsp:Policy
        xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"
        xmlns:wsp="http://www.w3.org/@@@@/@@/ws-policy" >
(02)   <wsp:ExactlyOne>
(03)     <wsp:All> <!-- @wsp:Optional alternative with assertion -->
(04)       <sp:RequireDerivedKeys />
(05)     </wsp:All>
(06)     <wsp:All /> <!-- @wsp:Optional alternative without -->
(07)   </wsp:ExactlyOne>
(08)   <wsp:ExactlyOne>
(09)     <wsp:All>
(10)       <sp:WssUsernameToken10 />
(11)     </wsp:All>
(12)     <wsp:All>
(13)       <sp:WssUsernameToken11 />
(14)     </wsp:All>
(15)   </wsp:ExactlyOne>
(16) </wsp:Policy>

Note that the assertion listed in Line (02) in the first listing expands into the two alternatives in Lines (03-06) in the second listing.

Finally, noting that wsp:Policy is equivalent to wsp:All , and distributing wsp:All over wsp:ExactlyOne yields the following normal form policy expression:

(01) <wsp:Policy
        xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"
        xmlns:wsp="http://www.w3.org/@@@@/@@/ws-policy" >
(02)   <wsp:ExactlyOne>
(03)     <wsp:All>
(04)       <sp:RequireDerivedKeys />
(05)       <sp:WssUsernameToken10 />
(06)     </wsp:All>
(07)     <wsp:All>
(08)       <sp:RequireDerivedKeys />
(09)       <sp:WssUsernameToken11 />
(10)     </wsp:All>
(11)     <wsp:All>
(12)       <sp:WssUsernameToken10 />
(13)     </wsp:All>
(14)     <wsp:All>
(15)       <sp:WssUsernameToken11 />
(16)     </wsp:All>
(17)   </wsp:ExactlyOne>
(18) </wsp:Policy>

Note that the two alternatives listed in Lines (03-06) in the second listing are combined with the two alternatives listed in Lines (09-14) in the second listing to create four alternatives in the normalized policy, Lines (03-06), (07-10), (11-13), and (14-16).