RE: [chairs] New rule on which document wins when there is ambiguity

[Robin Cover <robin@oasis-open.org>]

With respect to revised text in Section 2.18 of the OASIS
TC Process [1] asserting that "... the definition in the
separate file prevails...", the following comment may be
useful.

While I cannot speak officially for the OASIS Board Process
Committee (and Board) responsible for the change, I did
participate in deliberations, and can share my understanding
of the Committee's intent.

In summary: the notion of precedence introduced by the word
"prevails" was NOT, as I recall, intended to address the
matter of (apparent discrepancy and) highest authority in
cases where (e.g.,):

a) an assertion in prose (embodied in the main prose document
    which is part of a specification) conflicts, or apparently
    conflicts with an assertion based upon declarations in
    a W3C XML schema file, RNG schema, DTD, Schematron schema, or
    other machine-readable text with computer language definitions

b) assertions in natural language prose impose *additional* semantic
    constraints that cannot be expressed fully in a grammar-based
    schema definition (ABNF, W3C XML Schema, RNG schema, DTD)

c) one kind of formal language description embedded, as
    display text, in the main prose document (part) of a
    specification conflicts with assertions made by a
    DIFFERENT kind of formal language description carried
    in a plain text (machine-readable) file that is also part
    of the specification [e.g., RNG schema in the prose is in conflict
    with a separate W3C XML Schema file definition]

RATHER, the "discrepancy" envisioned in the new TC Process
document (sentence containing "the separate file prevails")
and mentioned in Mary McRae's announcement [2] is simply a
situation arising from human editing error and/or machine
conversion error, where the TC's intent is to include the SAME
machine-readable formal language definition text in BOTH:

[i]  separate plain-text file, for use mainly by machines
[ii] the main prose specification document, as display text,
      for use mainly by human readers

Viz., the intent was that the text characters be identical
(modulo white space allowable for a particular formal
language representation) in BOTH [i] and [ii], but it's
discovered that by error, some textual difference has
crept in, and it was undetected at publication time.

The revised TC Process simply says that if a discovery is
made to show that the text in [i] and [ii] differ -- due
to some human or machine error that escaped proof-reading --
the text of the machine-readable file ('[ii]') is to be
considered authoritative.

Of course, arguments can be made (and have been discussed
at length) about whether this type of error is more likely
to "happen" in one context or the other, and whether this
type of error is more likely to be detected through the
use of one context or the other, etc. The committee decided
that the authoritative text should be declared to reside in
the machine-readable "plain text" file.

Caveat: the explanation above represents my understanding;
if it's incorrect, someone with (more) correct explanation
should provide commentary.

  - Robin Cover

---------- References

[1] http://www.oasis-open.org/committees/process-2009-07-30.php#specQuality
     OASIS Technical Committee Process
     Approved: 30-July-2009, Effective: 1-September-2009

     2.18 Specification Quality

     All normative computer language definitions that are part of
     the specification, such as XML instances, schemas and Java(TM)
     code, including fragments of such, must be well-formed and
     valid, and must be provided in separate plain text files.
     Each text file must be referenced from the specification.
     Where any definition in these separate files disagrees with
     the definition found in the specification, the definition in
     the separate file prevails.

     A specification may be composed of any number of files of
     different types, though any such multi-part specification must
     have a single specification name and version number.
     Irrespective of the number and status of the constituent parts,
     the specification as a whole must be approved by a single
     TC ballot.

[2] http://lists.oasis-open.org/archives/members/200908/msg00000.html
     Subject: Changes to OASIS TC Process Policy
     From: Mary McRae <mary.mcrae@oasis-open.org>
     To: members@lists.oasis-open.org,tc-announce@lists.oasis-open.org
     Date: Wed, 5 Aug 2009 15:25:22 -0400
     Message-ID: <E319656B-A933-4799-8C9F-D7F57914B22A@oasis-open.org>

     3. Schemas, XML instances, etc. associated with a specification.
     The Process now explicitly states that if a discrepancy occurs
     between the plain text file and the specification document, the
     definition in the separate file prevails. (See Section 2.18)

-- 

Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/who/staff.php#cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783


On Sat, 8 Aug 2009, Matthew Dovey wrote:

> I can see a logic to this rule.  Any real world implementation of a spec will be more likely (if not certainly) have components generated from machine readable files such as XML schemas. As such when there is a conflict between say an XML schema and a normative document although the normative document might be "right" and the XML schema "wrong", changing the normative document rather than the schema would have a lower impact of real world implementations than correcting the XML schema.
>
> I don't however agree that Chris's example is a problem - in such cases there isn't a conflict between the XML schema and the normative document - just that the normative document is a refinement of the XML schema. I don't see this new rule as implying that any XML schemas (etc.) must be regarded as completely self contained but that they must (as at present) be used in conjunction with the normative spec.  E.g. if the XML schema said <element> must be  string, whilst the normative spec stated that <element> must be a string with certain properties, there isn't a discrepancy and the new rule would not apply. However, if XML schema said <element> must be an integer, whilst the normative spec said the strings "null", "zero" etc. were valid values of <element> then there is a clear discrepancy, and the new rule would apply.
>
> However, I do agree, that there is a risk that the rule might be misinterpreted by some to mean that any XML schema can stand alone as the definition without reference to the normative documents. If the rule were to remain, this would need clarification (i.e. a proper definition of what is meant by "discrepancy").
>
> That said, like Chris and Kelvin, I'm not entirely happy with the rule.
>
> Firstly there is another situation where the rule is ambiguous. A spec may have (and quite often has) multiple machine readable files such as an XML schema and an RELAX NG schema. If there is a conflict between the RELAX NG schema and the normative doc, but not between the XML schema and normative document, which one prevails? There is an obvious common sense answer here, but the new rule muddies the water in this case rather than clarifies. However, in terms of impact, it really depends on which schema file has been used by real world implementations. If most use the RELAX NG schema, then it might be appropriate to change the XML schema and normative documents.
>
> Which brings be to my second reservation - I believe (since it is the only reason I can think of), that the motivation behind this rule is to reduce the impact caused by documentation errors, by identifying a correction which causes fewer changes to existing implementations (rather than a correction to what was originally intended). However, to me that seems to be a judgement call, not one that can be cast in a black and white rule. There may be cases where changing the schema to the normative spec causes a lot of pain for implementers with no real gain or benefit; however there may be other cases where the error in the schema has detrimental side-effects elsewhere in the spec.
>
> I would much rather see a set of guidelines for TCs in dealing with such situations so that they properly consider the impact on both for the integrity of the spec and the existing implementations when dealing with this sort of situation, so that a TC does not blindly force the normative spec to conform to the schema or vice versa without properly considering the ramifications of both and taking the better action in that situation.
>
> Matthew
>
>
>
>> -----Original Message-----
>> From: Chris Kaler [mailto:ckaler@microsoft.com]
>> Sent: 08 August 2009 07:40
>> To: Kelvin Lawrence; Mary McRae
>> Cc: chairs@lists.oasis-open.org
>> Subject: RE: [chairs] New rule on which document wins when there is
>> ambiguity
>>
>> I agree with Kelvin that this is a problem.  In some cases the XML schema
>> description cannot represent the rules specified in the text of a specification.
>> In such cases there is an inherent discrepancy because the schema and the
>> specification do not state the same thing.  To say that the schema file is
>> correct would be technically inaccurate.  As well, XSDs cannot fully represent
>> the RFC 2119 concepts.  I fear this will lead TCs to not include schema files.
>>
>>
>>
>> From: Kelvin Lawrence [mailto:klawrenc@us.ibm.com]
>> Sent: Friday, August 07, 2009 8:28 PM
>> To: Mary McRae
>> Cc: chairs@lists.oasis-open.org
>> Subject: [chairs] New rule on which document wins when there is ambiguity
>>
>>
>>
>> Fellow chairs,
>>
>> I am way less than 100% comfortable with the new rule #3 (documented at
>> [1]) stating that when there is a discrepancy between a normative
>> specification and an external document (such as a schema/xsd file) that the
>> external document shall always be assumed to be the correct one. I can think
>> of several cases in the TCs that I have either chaired or been involved with
>> that this has happened and in every case the spec was right and the external
>> document was wrong. I would like to understand why OASIS felt compelled
>> to *mandate* this process, I would have much preferred having the TC
>> process require each TC to unambiguously state, in the event of a
>> discrepancy, which document should be assumed to be correct.
>>
>> Am I alone in this concern or do others of you share my view?
>>
>> [1] http://lists.oasis-open.org/archives/members/200908/msg00000.html
>> <http://lists.oasis-open.org/archives/members/200908/msg00000.html>
>>
>> Cheers
>> Kelvin (WS-SX co-Chair)
>>
>> Kelvin R. Lawrence
>> Distinguished Engineer & CTO, Emerging Internet Software Standards
>> Member of the IBM Academy of Technology
>> (http://www.ibm.com/ibm/academy <http://www.ibm.com/ibm/academy>
>> ) IBM Software Group. 11500 Burnet Road, Austin, TX 78758.
>> e-mail: klawrenc@us.ibm.com  Twitter: @gfxman
>> BLOG: http://www.ibm.com/developerworks/blogs/page/KRL
>> <http://www.ibm.com/developerworks/blogs/page/KRL>
>
>