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

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

At 2008-01-13 20:38 +0000, you wrote:
>These are my comments on the specification document.  Cheers, Tony.
>--
>#1: A4 page 4: 2nd paragraph in introduction jumps in too quickly 
>with insufficient explanation of the problem context.  It is also 
>too oblique in its initial references to code lists.

I'm not sure I follow your concerns.  The second paragraph defines 
code lists and leads to the third that talks about genericode.

>An introduction needs to introduce the concepts for people who are 
>not already experts.

Which is why the introduction covers a number of areas where this 
specification can be used.  I don't expect the reader to know what 
context/value association files are, but I do expect the reader to 
know what XML is and what code lists are.  I don't see that it is the 
role of this specification to define in detail what code lists are.

>I personally find the introduction confusing as written.

I thought I progressed concepts from basic issues through to the need 
and use of CVA files.  In order I wrote:

  - what schemas are used for
  - what code lists are used for
  - how code lists can be used in broad or narrow document contexts
  - what a CVA file is
  - how a CVA file accomplishes what it does
  - example of how a CVA file is used in document creation
  - example of how a CVA file is used in document validation

Would it help if I had titled subsections?

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.

>#2: A4 page 4: Is the introduction meant to be normative?  It is not 
>marked as non-normative as some other sections are.

Changed.

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

>#4: A4 page 4: Why "meta data" rather than "metadata"?  I don't 
>believe "meta" is a word in its own right.

Changed.

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

>#6: A4 page 4: Don't write "an example could be".  An example *is* 
>something, there is no need to be tentative about it.

Changed.

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

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

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

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

>#11: A4 page 6: "on the expression of on the" contains a typo.

Changed.

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

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

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

Does anyone else have a problem with this?

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

>#16: Section 2.2: Why is Schematron defined here?

Because it was referenced in the introduction.

I'll continue with the other points when I get the time (I'm teaching 
again this week), but I wanted to get these initial responses out in 
order to get the feedback from committee members.

Thanks for taking the time for a detailed response.

. . . . . . . . . . . . . Ken

>#17: Section 2.3: I think your definition of "lexical validation" 
>needs to be defined, since some people would suggest that value 
>validation is just part of lexical validation.
>
>#18: A4 page 10: Could inclusion also have precedence based on a 
>"priority" attribute, as it is in XSLT?  That would be a familiar 
>approach for many of the community that this specification is aimed at.
>
>#19: A4 page 11: "single key comprised of multiple column 
>references" - this is called a "compound key" in the genericode specification.
>
>#20: A4 page 11: I'm concerned about the lack of support for 
>genericode compound keys.  They can be supported in the 
>specification in the same way that W3C XML Schema supports them.  I 
>would like to see them supported in the specification, even if some 
>implementations don't support them.
>
>#21: A4 page 13: "foreign content" - the meaning of this isn't 
>sufficiently clear; it sounds too much like "foreign-language content".
>
>#22: Conformance D1: Why "genericode.xsd"?
>
>#23: Conformance D4: This needs to change, as there shouldn't be 
>*any* genericode files that are not conformant with the CVA specification.
>
>#24: Conformance A2: Why is this necessary?  Also, what are 
>"association results", and how do they differ from other results 
>(like "validation results")?
>
>#25: Conformance A3: As noted, we should consider changing this to 
>reflect the way precedence works with XSLT templates.
>
>#26: Conformance A4: what about "xml:base"?  This should be 
>supported at (possibly) all levels for relative URI resolution.
>
>#27: Conformance A6: should optional "priority" attributes also apply here?
>--
>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/
>
>---------------------------------------------------------------------
>To unsubscribe from this mail list, you must leave the OASIS TC that
>generates this mail.  You may a link to this group and all your TCs in OASIS
>at:
>https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php


--
Comprehensive in-depth XSLT2/XSL-FO1.1 classes: Austin TX,Jan-2008
World-wide corporate, govt. & user group XML, XSL and UBL training
RSS feeds:     publicly-available developer resources and training
G. Ken Holman                 mailto:gkholman@CraneSoftwrights.com
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/m/
Box 266, Kars, Ontario CANADA K0A-2E0    +1(613)489-0999 (F:-0995)
Male Cancer Awareness Nov'07  http://www.CraneSoftwrights.com/m/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal