AI-2006-03-15-01 - Guidance on creating assertions

["Martin Gudgin" <mgudgin@microsoft.com>]

Dear TC,

Prateek and I had an action item to come up with some proposed text
around guidance on designing assertions. 

Here is text to fulfill that action item.

Cheers

Gudge (on behalf of Prateek and himself).




Proposal

Add a new section to WS-SP as follows;

Guidance on creating New Token Assertions and Token Assertion
Extensibility

General Points:

A) Prefer distinct Qnames
B) Parameterize using nested policy where possible.
C) Parameterize using attributes and/or child elements where necessary.

Details:

Assertions in WS-SP are XML elements that are identified by their QName.
Matching of assertions per WS-Policy is performed by matching element
QNames. Matching does not take into account attributes that are present
on the assertion element. Nor does it take into account child elements
except for wsp:Policy elements. If a wsp:Policy element is present, then
matching occurs against the assertions nested inside that wsp:Policy
element recursively (ref to relevant section of WS-Policy).

When designing new assertions for use with WS-SP, the above matching
behaviour needs to be taken into account. In general, multiple
assertions with distinct QNames are preferably to a single assertion
that uses attributes and/or content to distinguish different cases. For
example, given two possible assertion designs;

1.	<A1/>
      <A2/>
      <A3/>

2.	<A Parameter='1' />
	<A Parameter='2' />
	<A Parameter='3' />

then design 1. would generally be prefered because it allows the policy
matching logic to provide more accurate matches between policies.

A good example of design 1. is the token assertions defined in section
5. The section defines 10 distinct token assertions, rather than a
single sp:Token assertion with, for example, a TokenType attribute.
These distinct token assertions make policy matching much more useful as
less false positives are generated when performing policy matching.

There are cases where using attributes or child elements as parameters
in assertion design is reasonable. Examples include cases when
implementations are expected to understand all the values for a given
parameter and when encoding the parameter information into the assertion
QName would result in an unmanageable number of assertions. A good
example is the sp:IncludeToken attribute that appears on the various
token assertions. Five possible values are currently specified for the
sp:IncludeToken attribute and implementations are expected to understand
the meaning of all 5 values. If this information was encoded into the
assertion QNames, each existing token assertion would require five
variants, one for each Uri value which would result in 45 assertions
just for the tokens defined in Section 5.

Nested policy is ideal for encoding parameters that can be usefully
matched using policy matching. For example, the token version assertions
defined in section 5 use such an approach. The overall token type
assertion is parameterized by the nested token version assertions.
Policy matching can use these parameters to find matches between
policies where the broad token type is support by both parties but they
might not support the same specific versions.

Note, when designing assertions for new token types such assertions
SHOULD allow the sp:IncludeToken attribute and SHOULD allow nested
policy.