Re: NEW ISSUE: 3981 [Guidelines] Section 4 Relevance to Assertion Design

Dan, Asir and I reviewed the current Section 4.2 in Guidelines and
worked on a joint proposal for addressing [Issue 3981] by rewriting 4.2.


Our proposal below keeps the examples in the current text intact while
clarifying the relevance of styles and introduces a best practice as
follows. Note that the examples included below already exist in the
document. There is a small bug fix in the first one only. 

Thanks, 

--umit


[Issue 3981] http://www.w3.org/Bugs/Public/show_bug.cgi?id=3981


-----------------------------------

4.2 Authoring Styles 
WS-Policy supports two different authoring styles, compact form and
normal form. A compact form is one in which an expression consists of
three constructs: an attribute to decorate an assertion (to indicate
whether it is required or optional), semantics for recursively nested
policy operators, and a policy reference/inclusion mechanism. 
<wsp:Policy xmlns:wsp='http://www.w3.org/@@@@/@@/ws-policy'
 xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy' 
 xmlns:wsrmp='http://docs.oasis-open.org/ws-rx/wsrmp/200608'>
 <wsrmp:RMAssertion wsp:Optional="true"/>
 <wsp:ExactlyOne> 
  <wsp:All>
   <sp:TransportBinding>
    <wsp:Policy>
     <sp:TransportToken>
      <wsp:Policy>
       <sp:HttpsToken RequireClientCertificate='true' />
      </wsp:Policy>
     </sp:TransportToken>
   </sp:TransportBinding>
  </wsp:All>
 </wsp:ExactlyOne>
</wsp:Policy>
A policy expression in the compact form can be translated into its
normal form using the policy normalization algorithm described in the
Web Service Policy Framework (see section 4.3 Compact Policy
Expression). 
<wsp:Policy xmlns:wsp='http://www.w3.org/@@@@/@@/ws-policy'
 xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy' 
 xmlns:wsrmp='http://docs.oasis-open.org/ws-rx/wsrmp/200608'>
 <wsp:ExactlyOne> 
 
  <wsp:All>
   <wsrmp:RMAssertion>
      <sp:TransportBinding>
       <wsp:Policy>
          <sp:TransportToken>
            <wsp:Policy>
                  <sp:HttpsToken RequireClientCertificate='true' />
            </wsp:Policy>
          </sp:TransportToken>
      </wsp:Policy>
     </sp:TransportBinding>
  </wsp:All>
 
  <wsp:All>
      <sp:TransportBinding>
       <wsp:Policy>
          <sp:TransportToken>
            <wsp:Policy>
                  <sp:HttpsToken RequireClientCertificate='true' />
            </wsp:Policy>
          </sp:TransportToken>
       </wsp:Policy>
      </sp:TransportBinding>
  </wsp:All>
 
 </wsp:ExactlyOne>
</wsp:Policy>
These two forms of the same policy expression are semantically
equivalent. When multiple alternatives are present in a policy, the
normal form may express the choices more explicitly. On the other hand,
the compact form may be more readable for humans when an assertion is
marked as optional using the wsp:optional attribute as our example
illustrates above. 
A policy processor may normalize a policy expression originally authored
in compact form at any time without changing the semantics of the
policy. In general, it is not possible to guarantee in what form a
policy expression would be when it is processed. As a result, the
description for a policy assertion should not depend on the style used
to author a policy expression that contains the assertion.
Best practice: the semantics of an assertion should be independent of
the form (compact or normal form) of policy expressions that contain the
assertion. 
------------------------------------------------------------------------
--------------------------

----------------------

Dr. Umit Yalcinalp
Research Scientist
SAP Labs, LLC
Email: umit.yalcinalp@sap.com Tel: (650) 320-3095 
SDN: https://www.sdn.sap.com/irj/sdn/weblogs?blog=/pub/u/36238
--------
"Nearly all men can stand adversity, but if you want to test a man's
character, give him power." Abraham Lincoln.