Subject: AI-2006-03-15-01 - Guidance on creating assertions
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.