RE: [wss] Schema examples in text

["Philpott, Robert" <rphilpott@rsasecurity.com>]

I concur with Tim and Phill.  In my view, the XKMS, SAML, and XACML specs
are considerably easier to understand with the schema snippets in the spec
than the current WSS spec(s).

If the snippets are maintained via linked objects, can the burden on the
editors be minimized or is it made more difficult.

Rob Philpott 
RSA Security Inc. 
The Most Trusted Name in e-Security 
Tel: 781-515-7115 
Mobile: 617-510-0893 
Fax: 781-515-7020 
mailto:rphilpott@rsasecurity.com 


-----Original Message-----
From: Hallam-Baker, Phillip [mailto:pbaker@verisign.com] 
Sent: Tuesday, November 26, 2002 10:54 AM
To: 'Tim Moses'; Hallam-Baker, Phillip; 'Anthony Nadalin';
wss@lists.oasis-open.org
Subject: RE: [wss] Schema examples in text

Well that is what I did myself for SAML.

However doing it all to XKMS gave me what psychologists and
mice call 'the screaming heebie jebies'.

I agree it is valuable, automating the process cuts down on
confusion caused by inconsistencies.

	Phill

> -----Original Message-----
> From: Tim Moses [mailto:tim.moses@entrust.com]
> Sent: Tuesday, November 26, 2002 10:44 AM
> To: 'Hallam-Baker, Phillip'; 'Anthony Nadalin'; 
> wss@lists.oasis-open.org
> Subject: RE: [wss] Schema examples in text
> 
> 
> Phill et al - I believe providing the xsd in the body of the 
> specification considerably aids the reader.  She sees, in 
> front of her, the types of variables, the 
> cardinalty/optionality, whether variables are related by 
> choice or sequence; all things that the current presentation 
> avoids.  I was able to achieve the same result in XACML.  
> However, I am embarrassed to confess that I used nothing more 
> than the "cut and paste" facilities of Word.  Is that called 
> "working without a .NET"?  If it was hard work, I thought of 
> it as nothing more than the unhappy lot of the editor.
> 
> All the best.  Tim.
> 
> -----Original Message-----
> From: Hallam-Baker, Phillip [mailto:pbaker@verisign.com]
> Sent: Tuesday, November 26, 2002 9:58 AM
> To: 'Anthony Nadalin'; wss@lists.oasis-open.org
> Subject: RE: [wss] Schema examples in text
> 
> 
> Anthony Nadalin wrote:
> > I have not heard an over a lot of votes for or  against the 
> > proposal to use
> > schema in place of the current examples. We need to take a 
> > vote on this as
> > it will take a somewhat large effort to do this change.
>  
> 
> 
> I did the SAML core spec where we have fragments in the text, my
> conclusion is
> 
> 1) It is a great help to people reading the specification
> 2) It is a complete and utter pain without automated tools
> 3) I have some tools for processing XML which could probably
> 	be modified for Word that I wrote for doing XKMS.
> 
> To modify them what I need is some definitive description of
> how to link to an external file using Word.
> 
> The scheme I suggest is to take the schema and put it through
> the parsing tool to create a series of fragments based on
> XML comments, i.e the fragment:
> 
> 	<!-- MessageAbstractType -->
> 	<complexType name="MessageAbstractType" abstract="true">
> 		<sequence>
> 			<element ref="ds:Signature" minOccurs="0"/>
> 			<element ref="xkms:OpaqueClientData"
> minOccurs="0"/>
> 		</sequence>
> 	</complexType>
> 	<!-- /MessageAbstractType -->
> 	<!-- OpaqueClientData -->
> 	<element name="OpaqueClientData"
> type="xkms:OpaqueClientDataType"/>
> 	<complexType name="OpaqueClientDataType">
> 		<sequence minOccurs="0" maxOccurs="unbounded">
> 			<element ref="xkms:OpaqueData" minOccurs="0"/>
> 		</sequence>
> 	</complexType>
> 	<element name="OpaqueData" type="base64Binary"/>
> 	<!-- /OpaqueClientData -->
> 
> Would be written out to two files, MessageAbstractType.html and
> OpaqueClientData.html with appropriate lexical transformations
> (already coded).
> 
> Then the word file would link to the html fragments.
> 
> We would do the same thing again with examples.
> 
> Another advantage of this approach is that by using the validating
> reader I ensure that every example is correct (or at least matches
> .NET's idea of correct, although at this point .NET has proved 
> more accurate than xmlSpy.)
> 
> Only downside is that the tool requires the .NET framework.
> 
> 		Phill
> 
> 
>