Re: [codelist] Comments on context-value-association-0.2-D1-20071121-0250z

["Anthony B. Coates (Miley Watts)" <abcoates@mileywatts.com>]

On Mon, 14 Jan 2008 04:51:01 -0000, G. Ken Holman  
<gkholman@CraneSoftwrights.com> wrote:

> I'll await feedback from other committee members before I make wholesale  
> changes.  It isn't that I'm ignoring your comment, but I felt I wrote it  
> to meet the needs of the reader, and I'll see if others also find it  
> confusing.

Sure, fair enough.

>> #3: A4 page 4: "Schemata" is not a suitable way to refer to "XML  
>> schemas" here, because the "XML" context hasn't been established (and  
>> the correctness of writing "schemata" rather than "schemas" also hasn't  
>> been so well established - "schemas" is what readers will be familiar  
>> with).
>
> This was first written in the UBL project.  In that project it was  
> decided to use Oxford English and, therefore, "schemata" is used instead  
> of "schemas".  And if I said "XML schemas" then people might believe I'm  
> referring to the W3C document of the same name.  I'm talking about  
> schemas in general, so I personally see no problem with "schemata".
>
> Does anyone else think we need to change this?

I believe Paul agreed with me.  My concern is that "schemata" is more  
confusing than "schemas", because most people have never been to an XML  
conference, and don't know that "schemata" is a plural of "schema".  By  
the way, the Oxford dictionary accepts both "schemata" and "schemas" as  
plurals for "schema".

>> #5: A4 page 4: XML documents aren't hierarchies, they are documents  
>> where the data is structured hierarchically.  That isn't the same thing.
>
> I disagree.  But I've reworded the sentence "XML documents are  
> hierarchical arrangements of information items where some of those items  
> may be represented by an enumerated value."

That mixes two ideas, to the point of almost suggesting that XML documents  
have to allow enumerated values.  I would suggest it is better to have two  
separate sentences, viz.

----
XML documents are hierarchical arrangements of information items.  Some of  
those items may be represented by enumerated values.
----

>> #7: A4 page 4: Is the subset of XPath 1.0 also a subset of XPath 2.0?   
>> Can it just be referred to as a subset of XPath?  The subset needs  
>> defined somewhere, but doesn't appear to be defined anywhere.
>
> Yes, we've been through this.  I'll remove revisions.  Following  
> Schematron a language= attribute will be added.  In its absence XPath  
> 1.0 can be assumed.  I've mentioned what other values would be  
> representative.

That doesn't really answer the question about the subset, though.  The  
document clearly states that a *subset* of XPath 1.0 is used, but it  
wasn't obvious to me what that subset was (although Paul suggested he  
understood it, maybe I'm just thick).  If it is a subset, I think the  
subset deserves to be clearly spelled out.

>> #8: A4 page 5: There seems to be a natural connection between CVA files  
>> and OASIS XML Catalogs.  Can something be added to support that?
>
> I fail to see the connection.  A catalogue rewrites URIs and public  
> identifiers with other URIs.  But I acknowledge I could just be missing  
> the essence of what you are trying to say.  Can you elaborate on the  
> connection that you perceive?

CVA files reference genericode files via URIs, and it might be useful in  
some deployments to be able to apply rewriting rules or redirections to  
those URIs.  As OASIS has a specification for such rewriting/redirection  
of URIs, I thought it might be useful to make that connection.  It doesn't  
have to be a normative thing, of course.

>> #9: A4 page 6: Could some be added to the text surrounding Figure 2 to  
>> indicate that although the genericode files are the source of the code  
>> list information, it is not a requirement that the genericode files are  
>> accessed directly during validation?
>
> The diagram delineates the "one-time preparation" files from the  
> "run-time processing" files, and puts GC files in the former.  I've  
> updated the two paragraphs starting with "The data flow..." to highlight  
> those files that are accessed before being used at run-time.

The diagram has two sections "one-time preparation" and "run-time  
processing", but I don't think it makes it clear that the genericode files  
aren't typically accessed live at run-time.  It didn't make it clear to me  
(you had to point it out to me).  It would have helped me if there was  
some mention in the text.

>> #10: A4 page 6: "bakes in" may be too colloquial an expression for  
>> non-native English speakers to understand unambiguously.
>
> Would "hardwires" be too colloquial?

In truth, I would replace the whole sentence with something like

----
W3C Schemas are commonly written in a way that mixes structural  
constraints with value constraints, the latter including embedded lists of  
enumerated values for code lists and/or identifiers.
----

>> #12: A4 page 6: The text suggests that the CVA validation cannot be  
>> done before the structural (schema) validation.  However, we've already  
>> accepted that it can work if the two passes are done in parallel (for  
>> NVDL), and that suggests that actually the two passes could be done in  
>> either order, depending on which kinds of error you most interested in  
>> seeing first.  Is that a valid interpretation?
>
> It is but an example of a data flow.  We've already decided this  
> document doesn't normatively describe validation using CVA files.  It  
> isn't wrong, and having two additional alternative examples would  
> lengthen the introduction even further.

I'm not saying that there should be more examples, just that the phrase  
"This mandates the first-pass structural validation" suggests that there  
is no choice in the order in which the validation phases are performed.

>> #13: A4 page 7: Are code values really published for "concepts"?   
>> People don't think of countries and currencies as being concepts, so is  
>> there an alternative way this can be expressed?
>
> Can you (or anyone else on the list) suggest one?

I would replace "commonly-understood concepts" with something like  
"commonly-used items".

>> #14: A4 page 7: Isn't XPath a mandated technology?  Or, what qualifies  
>> as a technology?  It isn't obvious to me as I read the text.
>
> XPath is defined as part of the CVA specification.  The sentence context  
> of "mandated technology" is for the implementation of CVA files, not the  
> specification of XPath.  Schematron is not defined by the specification  
> and would be an example of a technology that could be used, but is not  
> mandated to be used.

XPath is still needed in any implementation.  The fact that it is built  
into Schematron doesn't mean that it isn't part of the implementation.

>> #15: A4 page 7: Can mention of particular implementations be moved to  
>> an appendix?
>
> The introduction is non-normative, and I feel not only is it innocuous  
> where it is, but it has a role in the introduction to tell the readers  
> that there exists a Schematron-based implementation *as an example of  
> implementation*.  It follows from the first sentence of that paragraph  
> that you cited in #14.
>
> I've left in the sentence but removed the citation and associated  
> reference so that the reader can just Google for the implementation if  
> they want to find it.  If others on the committee think that the  
> reference adds something for the reader, then I'll add it back in.

Actually, I don't think the specification should refer to implementations  
at all (we can do that on the TC web site), but I was prepared to accept  
your mentioning your implementation in an appendix.  I can't think of any  
other specifications that make specific reference to their implementations  
(OOXML excepted).

>> #16: Section 2.2: Why is Schematron defined here?
>
> Because it was referenced in the introduction.

I don't think the normative text should contain definitions that are only  
referenced in the non-normative text.  Those definitions can be moved to  
the non-normative text.

Cheers, Tony.
-- 
Anthony B. Coates
Senior Partner
Miley Watts LLP
Experts In Data
UK: +44 (20) 8816 7700, US: +1 (239) 344 7700
Mobile/Cell: +44 (79) 0543 9026
Data standards participant: genericode, ISO 20022 (ISO 15022 XML),  
UN/CEFACT, MDDL, FpML, UBL.
http://www.mileywatts.com/