RE: [tag] TAML Conformance Rewording

["Jacques R. Durand" <JDurand@us.fujitsu.com>]

I tend to agree with Stephen:
Your comments Dennis can - I believe - be considered as procedural +
consistency, but "non substantial" in terms of affecting the content and
can be dealt with after the PR without entailing a new PR period.

These points are well taken though, and I let Stephen decide of how much
can go in the final candidate that I need to reference when initiating
the ballot end of week.

I think the conf clause for the markup is still the most important that
needs fixing prior to PR.

Regards,
Jacques

 

-----Original Message-----
From: Dennis E. Hamilton [mailto:dennis.hamilton@acm.org] 
Sent: Wednesday, February 03, 2010 1:52 PM
To: stephen.green@documentengineeringservices.com; Jacques R. Durand
Cc: TAG TC List
Subject: RE: [tag] TAML Conformance Rewording

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.ph
>> p
>>
>>
>