[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [tag] TAML Conformance Rewording
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 >> >> >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]