Re: [tag] TAML Conformance Rewording

[Stephen Green <stephen.green@documentengineeringservices.com>]

Mmm. These are good comments for after the public review
but I would have problems implemennting these in time for
Thursday as they have not been discussed enough and go
beyond what we were agreeing to change at the last meeting.

In particular, we do not really know with certainty the URL of
the accompanying schema.

Also, I would not feel easy with calling the inline schema
'informative'. In cases where the only document available is

the spec, though one could argue that the OASIS rules mean 
you might not be able to implement the spec alone, that seems
to go beyond the obvious fact that the schema in the spec is
likely to be sufficient and the possibility of a discrepancy is

a corner case / exceptional case.

This unease I have about calling the section 3 copy of the
schema informative (there are in fact no discrepancies between
it and the accompanying schema and we could always decide

to not have an accompanying schema as part of the standard)
means that I can't agree with including a 'normative reference'
to the accompanying schema. I would rather just drop the 
accompanying schema if that helps us call the spec schema

normative and avoid any need to make it a normative reference.

Nevertheless it is not usual to have to solve this problem this 
way: It is quite usual to provide two or more copies of the schema,
all normative - one in the spec and one for convenience as a

separate file. I see no reason to do as suggested to cater for this
(I see no real reason to incur a logistic problem with a normative
reference to an external schema needing a known URL  - the
namespace document seems sufficient and normal for this along

with the inline schema making a normative reference unnecessary).

I'd be happy to include the conformance clause wording for now
and leave the other issues open for discussion throughout or after
the public review (though I think we are OK as is). 

In other words I'm happy to use, if there is no disagreement, your 
words for the conformance clause:

"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."

but I'm not sure'd agree to make the other changes 
this side of the public review as they seem a little

unnecessary and strange (e.g having the inline
schema as informative). I guess this means I'd still
want to keep the final sentence

"The
schema in Section 3 is, for convenience, provided also as a separate file accompanying this specification, 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 do agree this poses problems (I'm not a hundred percent
agreeing with the rule that an external schema is more

'authoritative' than the inline one) but I appreciate that the
idea of 'authoritative' as a concept over and above the
concept of 'normative' is standard OASIS practise and
solves practical problems even if it does present others

(such as seeming to require another document which it is
not clear at the time of reading the spec whether or not it
even exists). I guess the problems may not actually be real
problems in practise so I'd be content to go along with normal

OASIS TC practise here. Otherwise we could just decide to
drop the accompanying schema and also my final sentence
from the conformance clause

"The
schema
in Section 3 is, for convenience, provided also as a separate file
accompanying this specification, 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."

and use your suggested conformance clause text and
just that. But that might pose problems for the
implementers and also for the namespace
document which might need the accompanying
schema.

In reality though this is developing into more than

just a last minute minor detail discussion and it
seems we might be falling back on our TC decision
that we run with the already uploaded spec

http://www.oasis-open.org/committees/download.php/36210/testassertionmarkuplanguage-draft-1-0-8.pdf

and schema

http://www.oasis-open.org/committees/download.php/36209/testAssertionMarkupLanguage-draft-1-0-8.xsd

at least until after public review.

It might be possible to resolve this before public 
review if there were a way to limit the change to
just a conformance clause change.

Best regards

Steve
---
Stephen D Green

On 3 February 2010 21:51, Dennis E. Hamilton <dennis.hamilton@acm.org> wrote:

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
>>
>>
>