2002/ws/desc/test-suite assert-yourself.html,NONE,1.1

Update of /sources/public/2002/ws/desc/test-suite
In directory hutz:/tmp/cvs-serv23157/test-suite

Added Files:
	assert-yourself.html 
Log Message:
Created document that describes testable assertions.

--- NEW FILE: assert-yourself.html ---
<html>
<head>
<title>Assert Yourself!</title>
</head>
<body>
<h1>Assert Yourself!</h1>
<address><a href="mailto:ryman@ca.ib.com">Arthur Ryman, IBM</a></address>
<address>Updated 2005-12-07</address>

<h2>Introduction</h2>
<p>This document describes how to add <em>testable assertions</em> to
the WSDL 2.0 specifications and assigns sections to members of the
Working Group. The task of identifying all the testable assertions is
very important since it will help us create a comprehensive test suite.
It will also help implementers produce high quality implementations.</p>

<h2>What is a Testable Assertion?</h2>
<p>A testable assertion is a normative requirement in our specifications
that can be checked by a validation program. Testable assertions should
include one of the <a href="http://www.faqs.org/rfcs/rfc2119.html">RFC
2119</a> keyowrds. Initially, we should focus on the keywords MUST, MUST
NOT, SHALL, SHALL NOT, and REQUIRED since these are map to error
conditions. We should also address the keywords SHOULD, SHOULD NOT,
RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL since these map to
warnings and we want users of the specification to follow Best
Practices.</p>

<h2>How Do I Markup a Testable Assertion?</h2>
<p>We have defined a special XML tag: <code>&lt;assert&gt;</code> that
is placed around the testable assertion. This tag has the following
attributes:
<ul>
	<li>id - a required identifier. The identifier consists of a
	descriptive prefix and a four-digit numeric suffix separated by a dash,
	as in <code>Import-0001</code> . The numeric suffix must be globally
	unique across all our specifications. Once this number is assigned, it
	never changes. It may be removed but will never be reused. The
	identifier as a whole must be stable since implementers will refer to
	it.</li>
	
	<li>class - a required classification of the assertion. The valid classes are: document, component, message, and exchange.
	A document assertion is a requirement on WSDL 2.0 documents, e.g. that a document must not import its own namespace.
	A component assertion is a requirement on WSDL 2.0 components, e.g. that an Interface must not extend itself. 
	A message assertion is a requirement on concrete Web service messages, e.g. that a SOAP message body satsifies a certain XML schema.
	An exchange assertion is a requirement on Web service message exchanges, e.g. that a fault may replace a message.</li>
	
	<li>required - an optional boolean that indicates if the assertion is a requirment. The default is true. Set this to false for
	SHOULD, SHOULD NOT, etc. (Note: this is currently unsupported. I'll add it later.)</li>
	</p>
</ul>
</body>
</html>

Received on Wednesday, 7 December 2005 23:04:55 UTC