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

["Considine, Toby (Campus Services IT)" <Toby.Considine@unc.edu>]

Very nice disquisition...

If we accept that the artifacts are normative, and assume each to be machine readable, does this create a quality checking process for each specification that each artifact be machine read, and that the machine readings produce the same result? Would guidelines in that area address some of the concerns?

tc

"A man should never be ashamed to own that he has been in the wrong, which is but saying ... that he is wiser today than yesterday." -- Jonathan Swift

Toby Considine
Chair, OASIS oBIX TC
Facilities Technology Office
University of North Carolina
Chapel Hill, NC
  
Email: Toby.Considine@ unc.edu
Phone: (919)962-9073 
http://www.oasis-open.org 
blog: www.NewDaedalus.com



-----Original Message-----
From: Matthew Dovey [mailto:m.dovey@jisc.ac.uk] 
Sent: Saturday, August 08, 2009 5:44 AM
To: Chris Kaler; Kelvin Lawrence; Mary McRae
Cc: chairs@lists.oasis-open.org
Subject: RE: [chairs] New rule on which document wins when there is ambiguity

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>