RE: [tag] TAML Conformance Rewording

["Dennis E. Hamilton" <dennis.hamilton@acm.org>]

I wanted to be thorough about this, so it took longer than I first expected.

Here is a systematic restatement of the conformance section, with supporting
alignment in other sections.  I looked this over very carefully and propose
some tightening at the same time:

I have done the following:

 1. Expanded 1.1 with of the ways terms are used in accordance with Annex H
of ISO/IEC Directives.

 2. Added [TAML-schema] to the Normative Reference section (so the URL is in
one place near the front)

 3. Touched up 2.1 with regard to a contradictory statement covered by the
Conformance section already.

 4. Removed redundant assertions from section 2.2 concerning the
authoritative schema and what an XML Schema validity assessment might take
into account.

 5. Added two subsections to Section 3 on XML Schema to establish the
difference between the authoritative schema and the informative version at
that place.

 6. Restated the Conformance section on the lines I proposed yesterday.

 - Dennis

CHANGES

A. In Section 1.1, Terminology

Replace the single sentence with

"""
Within this specification, the verbal forms "shall", "shall not", "should",
"should not", "may", "need not", "can" and "cannot" in bold letters are to
be interpreted as expressing normative provisions as described in Annex H of
[ISO/IEC Directives].
"""

This includes the full list, whether used or not, and also indicates what
exactly these are associated with (generically).

B. In Section 1.2, Normative References

B.1, insert, following the [TAM] entry, the following entry:

   [TAML-schema] "Test Assertion Markup Language version 1.0 XML Schema",
Stephen D. Green, Editor.  OASIS Open Test Assertion Guidelines TC.
February 2010.
http://docs.oasis-open.org/tag/taml/v1.0/testAssertionMarkupLanguage-v1.xsd

B.2 In the references on [XSD1] and [XSD2], cite specific versions that
apply at this time and that [TAML-schema] relies on, as required in the
OASIS Guidelines and Templates.  Do not use generic citations in normative
references.  E.g., use, if these are intended:

   [XSD1]  W3C Recommendation "XML Schema Part 1: Structures Second
Edition", Henry S. Thompson, David Beech, Murray Maloney, and Noah
Mendelsohn, Editors.  28 October 2004.
http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/

   [XSD2]  W3C Recommendation "XML Schema Part 2: Datatypes Second Edition",
Paul V. Biron and Ashok Malhotra, Editors.  28 October 2004.
http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/


B.3 I note that there were no W3C Recommendations for XML Schema in 2000,
and that the W3C is also careful to cross-reference between these two
specifications and others by specific-version citations.

C. In Section 2.1 Binding to Test Assertions, DELETE the last paragraph,
beginning "Elements 'testAssertion', 'testAssertionSet', ..."

This is because the statement doesn't accomplish anything and the
Conformance section handles what matters.  NOTE: In the Conformance section,
there is no mention of element testAssertionDocumentHeader as the root
element of a conformant instance.

D. In Section 2.2 Convention Used to Represent the XML Markup

D.1 In the second paragraph after the example, beginning "Finally, the
example contains ..." DELETE the final sentence: 

"""
In the Test Assertion Markup Language these extra elements will not be
validated by W3C XML Schema validation, they are skipped.
"""  

Why?  We don't know whether they will be validated or not.  They are simply
not constrained by our schema, but we don't need to observe anything about
that here.  Someone could introduce validation for elements borrowed from
other specifications, for example.  The Conformance section establishes what
matters here.

D.2 REPLACE the next-to-last paragraph of this section, beginning "The full
definition ..." with

"""
The authoritative schema for the syntax of Test Assertion Markup Language is
specified in Section 3.  The representations throughout this specification
are not to be taken as specifying the authoritative syntax.  The XML markup
representations support specification of semantics and semantic constraints
associated with the identified syntactic features. 
"""

D.3 In the final paragraph, beginning "The example contains the following
note ..." REMOVE the ">" after "{any attributes with non-schema namespace .
. . }"

D.4 In the final paragraph before the NOTE, DELETE the final sentence,

"""
In the Test Assertion Markup Language these extra attributes will not be
validated by W3C XML Schema validation, they are skipped.
"""

[Side Note: attributes don't belong to namespaces unless they have an
explicit prefix, and the phrase non-schema namespace probably doesn't
capture what is presumably meant: that other attribute names must have
prefixedName form and be in some explicit namespace other than that for
TAML.  I am not going to fuss with that here.]   

D.5 I am not sure the NOTE works, but I will not worry about that here. 


E. In Section 3 XML Schema add the following subsection headings and content
in front of the schema extract:

"""
3.1 Authoritative Schema [Normative]

The XML Schema for Test Assertion Markup Language and its XML Namespace is
specified using a separate file [TAML-schema].  The schema and its
interpretation is that established by the W3C Recommendations for XML
Schema, [XSD1] and [XSD2]. 

3.2 Informative Schema [Non-Normative]

The following extract of [TAML-schema] is provided as a convenience for
information purposes only.  The schema file [TAML-schema] is the sole
authoritative version.  
"""

F. Section 4, Conformance, Replace the section content with the following:

"""
A Conforming Test Assertion is a Test Assertion Markup Language
testAssertion element that is valid according to the XML Schema (section 3)
and satisfies all normative provisions in Sections 2.3 Test Assertion and
2.6 Reserved Tag Names.

A Conforming Test Assertion Set is a Test Assertion Markup Language
testAssertionSet element that is valid according to the XML Schema (section
3) and satisfies all normative provisions in Sections 2.3 Test Assertion,
2.4 Test Assertion Set, 2.5 Test Assertion Reference, and 2.6 Reserved Tag
Names.

Conforming Test Assertions and Conforming Test Assertion Sets are Conformant
Test Assertion Markup Language instances.
"""

These changes remove the use of "instance" where it doesn't add anything and
also smoothes the narrative somewhat.  I note that there is nothing here
which has anything about testAssertionDocumentHeader elements.

 
 - Dennis

-----Original Message-----
From: stephengreenubl@gmail.com [mailto:stephengreenubl@gmail.com] On Behalf
Of Stephen Green

Sent: Wednesday, February 03, 2010 09:00
To: Jacques R. Durand
Cc: dennis.hamilton@acm.org; tag@lists.oasis-open.org
Subject: Re: [tag] Proposed Conf Clause rewording for the TA markup:
http://lists.oasis-open.org/archives/tag/201002/msg00021.html
Minor change:
(including "Sections 2.3 (test assertions), " for test assertion set)

"Implementations of this specification that may claim conformance according
to this conformance clause are: (1) instances of test assertion, (2)
instances of test assertion set.

A conforming test assertion instance shall fulfill all mandatory normative
statements in Sections 2.3 (test assertions) and 2.6 (reserved tag names) of
this specification, and be valid according to the schema accompanying this
specification.

A conforming test assertion set instance shall fulfill all mandatory
normative statements in Sections 2.3 (test assertions), 2.4 (test assertions
set), 2.5 (test assertion references) and 2.6 (reserved tag names) of this
specification and be valid according to the schema accompanying this
specification.

This schema is copied in-line in Section 3 but in the case of any
discrepancies between the in-line copy and the schema accompanying this
specification it is the separate schema which shall be used as the
authoritative definition of the validating schema."


[ ... ]

On 3 February 2010 11:12, Stephen Green
<stephen.green@documentengineeringservices.com> wrote:
http://lists.oasis-open.org/archives/tag/201002/msg00020.html
> Here's text I propose adding (in place of existing
> markup conformance clause) to include most of
> Jacques' wording and address Dennis' comments:
>
> PROPOSED TEXT:
>
> "Implementations of this specification that may claim conformance
> according to this conformance clause are: (1) instances of test
> assertion, (2) instances of test assertion set.
>
> A conforming test assertion instance shall fulfill all mandatory
> normative statements in Sections 2.3 (test assertions) and 2.6
> (reserved tag names) of this specification, and be valid according to
> the schema accompanying this specification.
>
> A conforming test assertion set instance shall fulfill all mandatory
> normative statements in Sections 2.4 (test assertions set) 2.5 (test
> assertion references) and 2.6 (reserved tag names) of this
> specification, be valid according to the schema accompanying this
> specification.
>
> This schema is copied in-line in section 3 but in the case of any
> discrepancies between the in-line copy and the schema accompanying
> this specification it is the separate schema which shall be used as
> the authoritative definition of the validating schema."
>
>
> I've removed the text "and contain only conforming test assertions
> instances" from the section
> on test assertion set because strictly speaking the markup does allow
> for test assertions in
> other markup to be 'contained' in a set via the TA reference
> construct, as the spec mentions.
> Plus the fact that a TA set is valid by the schema necessarily means
> that its inline TAs are valid
> too.
>
> The last sentence merely makes explicit what is already in the TC rules
> but in case these rules change it seems as well to include this
clarification.
>
>
> Best regards
>
> Steve
> ---
> Stephen D Green
>
>
>
>
> On 3 February 2010 02:23, Jacques R. Durand <JDurand@us.fujitsu.com>
wrote:
http://lists.oasis-open.org/archives/tag/201002/msg00019.html
>> Agree with these updates - can you send out exactly the new complete
>> clause, Dennis?
>>
>> -jacques
>>
>> -----Original Message-----
>> From: Dennis E. Hamilton [mailto:dennis.hamilton@acm.org]
http://lists.oasis-open.org/archives/tag/201002/msg00018.html
>> Sent: Tuesday, February 02, 2010 5:21 PM
>> To: Jacques R. Durand; tag@lists.oasis-open.org
>> Subject: RE: [tag] Proposed Conf Clause rewording for the TA markup:
>>
>>  1. I favor the proposed text.  I did notice that the first sentence is
>> peculiar in that it ascribes agency to implementations.  How about
>>
>> Conforming instances of test assertions and conforming instances of test
>> assertion sets are conforming implementations of this specification.
>>
>> It might work better if it follows the current second and third
>> paragraphs.
>>
>>  2. I think referencing the Declared XML Namespace(s) link may end up
>> being circular.  I would refer to the "the schema accompanying this
>> specification (section 3)." At the top of Section 3, ahead of the
>> schema, I would put a paragraph that makes a normative citation to
>> [taml-schema], which is provided a full citation in the normative
>> references.  I would then have the explanation that the text shown in
>> the referenced schema is the authoritative one and the version in
>> Section 3 is informative.
>>
>> I think this works better than referencing the front matter and in
>> finding the schema indirectly through the Namespace Document.
>>
>>  - Dennis
>>
>>
>>
>> -----Original Message-----
>> From: Jacques R. Durand [mailto:JDurand@us.fujitsu.com]
http://lists.oasis-open.org/archives/tag/201002/msg00017.html
>> Sent: Tuesday, February 02, 2010 16:57
>> To: tag@lists.oasis-open.org
>> Subject: [tag] Proposed Conf Clause rewording for the TA markup:
>>
>> Based on today's discussion:
>> Proposed Conf Clause rewording for the TA markup spec:
>>
>> NOTE: Make sure to send any comment  on this before Thursday noon US PT
>> time
>> - the latest text to appear by this Thu noon PT is what Stephen will
>> pick up for update early Friday morning (US time)...IF there is no
>> objection raised on the mailing list in-between.
>>
>>
>>
>> [ ... ]
>>
>> PROPOSED TEXT:
>>
>> Implementations of this specification that may claim conformance
>> according to this conformance clause are: (1) instances of test
>> assertion, (2) instances of test assertion set.
>>
>> A conforming test assertion instance shall fulfill all mandatory
>> normative statements in Sections 2.3 (test assertions) and 2.6 (reserved
>> tag names) of this specification, and be valid according to the schema
>> accompanying this specification with the namespace as defined under
>> 'Declared XML Namespace(s)' in the heading area of this specification.
>>
>> A conforming test assertion set instance shall fulfill all mandatory
>> normative statements in Sections 2.4 (test assertions set) 2.5 (test
>> assertion references) and 2.6 (reserved tag names) of this
>> specification, be valid according to the schema accompanying this
>> specification with the namespace as defined under 'Declared XML
>> Namespace(s)' in the heading area of this specification, and contain
>> only conforming test assertions instances.
>>
>> This schema is copied in-line in section 3 but in the case of any
>> discrepancies between the in-line copy and the schema accompanying this
>> specification it is the separate schema which shall be used as the
>> authoritative definition of the validating schema.
>>
>>
>> -jacques
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe from this mail list, you must leave the OASIS TC that
>> generates this mail.  Follow this link to all your TCs in OASIS at:
>> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>>
>>
>