Re: [oasis-member-discuss] Re: Membership and Public Review of OASISArtifact Standard Identification Scheme for Metadata

[William Cox <wtcox@comcast.net>]

Norm (and others) - comments interleaved below. Portions removed for 
greater visibility of discussion.

Thanks again to all for this opportunity to discuss these issues!

bill cox

Norman Walsh wrote:

SNIP

>|>* I think the document would benefit greatly from many, many more examples.
>|>  Especially complete examples of multiple products, with multiple versions,
>|>  in multiple languages, that have multiple schemas, and other ancillary
>|>  files.
>|>
>| Yes, it would. There's a bit of a circular wait - in some earlier versions
>| the examples weren't completely in sync with the then-rapidly changing
>| document; OASIS staff intended to do detailed examples as part of the
>| endgame.
>
>If we haven't reached the endgame yet then surely the recent message
>that suggested (some of) this would become normative at some board
>meeting in early March is premature?
>
The purpose of this document as evolved. The original intent was input 
to process declaration; I think that the document as-is is not in a 
policy form. The notions and requirements included are under 
consideration to become policy at some near-future date. 

>|>In more detail:
>|>
>|>Line 216 introduces the possibility that the TC Administrator might
>|>         create aliases for some or all existing artifacts.
>|>
>|>  Please don't[1].
>|>
>| The intent is to allow a full consistent naming structure (on
>| docs.oasis-open.org) even though some content is there already. The
>| alternative is to remove support for the old, promised-persistent URIs, or
>| to do another domain (documents.oasis-open.org?). I'd say this nmight be
>| the best of a set of bad choices.
>
>No, the alternative is to leave the old content alone and only impose
>new constraints on new documents. It seems to me that the confusion
>that will be caused by introducing aliases for existing documents
>vastly overshadows any possible benefits.
>
By new constraints, you seem to be talking about URIs only. 
Incidentally, metadata still needs to be somehow associated (used 
knowingly, rather than "included in") with older artifacts.

>|>Line 230 introduces "Artifact Identifier" which is also a name for
>|>         an Artifact.
>|>
>|>Line 234 introduces "Artifact Name"
>|>
>|>Line 237 introduces "Filename"
>|>
>|>Line 290 introduces "OASIS Defined Name"
>|>
>|>  Are all four of these terms necessary? If they are, the document
>|>  does not sufficiently distinguish between them.
>|>
>| Good point. Starting with the (non-normative) grammar might help a bit, but
>| the motivation and goals need to be in the document proper.
>
>Indeed. And does that mean you think all four terms are necessary?
>
Nope. Filename is an independent definition that is needed to describe 
the name of a file and how it's derived; usually that becomes the final 
component of an artifact URI, so the definition is needed. 

Off the top if my head, "Artifact Identifier" and "Artifact Name" 
shouldn't both be there. "OASIS Defined Name" should have text such as 
"An Artifact Name should be unambiguous [within a particular context]. 
TCs may define Artifact Names subject to certain rules (TC Defined 
Names), or may follow the OASIS Defined Name rules to create Artifact 
Names that are guaranteed to be unambiguous.

>|>Line 271 places a burden on the TC and the TC adminstrator for any
>|>         novel artifact type.
>|>
>|>  That really seems unneccessary. In fact, I think the administrator is
>|>  directly involved more often than necessary throughout the document.
>|>
>|>  Also, what does one do about artifact types that don't fit cleanly
>|>  into a single category? Suppose I publish a document that contains a
>|>  schema with annotations that contain the prose specification. Is
>|>  that a spec or a schema or something else? Do I have to get the TC
>|>  adminstrator involved to decide?
>|>
>| The intent was to approach the list as a cache, creating new cache elements
>| as the need arose.
>
>That doesn't really address my question about documents that don't fit
>cleanly into any single category
>
You're right. A TC needs to decide when it thinks a new category is 
needed (I think "annotatedSchema" is not a good example - your 
spec[ification] can't be in the form of an annotated schema per the 
templates, so the type should be "schema").  And the manager of the 
categories, the all-purpose TC Adminstrator, needs to manage the list 
and add items as needed. Embedding the "permanent" list in policy for 
periodic updates seems a waste of time, and adds process where none is 
needed.

>| There needs to be an adminstrative locus, and TCAdmin
>| seems the logical place.   On TC Admin decisions, creating persistent names
>| is partially the responsibility of the TC and partially that of TC
>| Admin/OASIS; the synchronization point is when the TC Admin agrees.
>
>Yes. I understand the process part, I think.
>
>|>Line 275 introduces dates of the form "YYYYMMDD".
>|>
>|>  Can we please the ISO standard YYYY-MM-DD format? And does this mean
>|>  that I can't use "23 Feb 2006" as the date on the cover page of my
>|>  specification?
>|>
>| Alas, the hyphen issues strike again. And 23 Feb 2006 is fine by me, but
>| the metadata format also needs to be there.
>
>Do you mean that I can put "23 Feb 2006" on my title page but I must
>also put "20060223" on there too?
>
I would. The date definition is in case a TC wants to use a date in the 
artifact name (see Chris Ferris' emails on the subject). A text 
statement and a metadata value aren't mutually exclusive.

>|>Line 283 makes PDF and HTML the mandatory normative formats.
>|>
>|>  This is an error. There must be exactly one normative form of the
>|>  specification. Any other state of affairs will lead to irresolvable
>|>  conflicts in the future. (The TC will produce it's work then disband.
>|>  Three years later, Hugecorp and Megabiz will discover that they're
>|>  software isn't interoperable because the HTML and PDF forms are
>|>  different.)
>|>
>|>  It remains my opinion that OASIS should standardize on XHTML as the
>|>  normative form for prose specifications and that it ought to provide
>|>  precisely the markup to be used for the beginning of the document
>|>  that includes all the metadata.
>|>
>|>  Extensive experience publishing dozens, perhaps hundreds, of
>|>  documents on the W3C TR page has convinced me that the metadata will
>|>  be wrong if it cannot be checked by machine. Getting all the
>|>  metadata right is simply the kind of boring, detail-oriented work
>|>  that human beings are just not cut out to perform. Even diligent and
>|>  consciencious editors will not get it right.
>|>
>| This is a broader topic, and will be addressed, but not here. The TC
>| Process calls this out. BTW, if the source is the same, the tools work, and
>| people review it, there's seldom a difference between the actual text of
>| the PDF, (X)HTML, and (say) a word processor document that generates both.
>
>"Seldom" is an unacceptable risk.
>
As we've all acknowledged as we beat this particular horse, this is NOT 
a mandate from the TAB or in ASIS - it's part of the TC process. I 
suspect we might all agree that distinguishing between a single 
normative form and two publication forms which must contain the same 
content would be useful. I've already proposed a change to update to 
XHTML, and the publication/normative distinction might be useful in 
conjunction with that.

Some of us read printed documents; the line numbering in the PDF makes 
reviews such as this one MUCH more useful and MUCH more productive, as 
your references are to lines rather than section+more context or 
sentence counting.

The issue of synchrony between the content of the PDf and content of the 
XHTML is a serious one, and I agree that it should be addressed.

"perfection in all areas" is a fine goal. Would you accept "really 
really infrequently, and the reviewers have to look really really 
closely"?  :-) seriously, I think this is a minor issue, and the benefits

SNIP

>I have no desire to chastise the editor. I have every confidence that
>the editor is working hard to produce a clear, precise and complete
>document. But there's still some work to be done :-)
>
The editor certainly is! And detailed comments and discussion as we've 
had on this list has been a huge benefit to the editor and to OASIS.

>|>Line 348 says that if I invent new metadata, I need the TC administrators
>|>         approval
>|>
>|>  Who decides if I've invented metadata? If I include some other name
>|>  value pairs in my document, are they metadata? How can you tell?
>|>  This seems unduly burdonsome and impossible to enforce.
>|>
>| See the caching analogy above. Good point.
>
>That misses the point, I think. To give an example, does the text
>"Element color: red" introduce new metadata? How can you tell?
>
Hmm. Does a phrase like "artifact-related metadata" help? I didn't think 
so... expression and display is an issue for the templates, not for the 
descriptive metadata. Perhaps a meta rule list "TCs may not create 
artifacts that differ only in [color | name capitalization } ...] ??

>
>|>Line 350 introduces a table that contains both "Artifact identifier"
>|>         and "OASIS Defined Name".
>|>
>|>  When are these different? And why? I thought they'd be the same in
>|>  the normal case. If they're the same, must they both be present?
>|>
>| Compromise along the way - the earlier drafts mandated a particular format
>| name, in a specific character set (which is now called an OASIS Defined
>| Name); later drafts relaxed this to allow meaningful unambiguous names as
>| defined by the TC as an alternative, reasoning that the TCs should be able
>| to keep track of their own artifact names. Either way works.;
>
>If either way works, can we just have one, please?
>
As above, I would suggest making it clear that the Artifact Identifier 
must be unambiguous [within TBD contexts], and that the OASIS Defined 
Name guarantees that. TCs can define names that conform only in 
character set and format, and those need approval/are subject to 
publication oversight by the TC Administrator. [yes, I know I said this 
a bit differently, trying different words]

>|>Line 408 defines the characters allowed in Artifact Identifiers.
>|>
>|>  Is the absence of "%" intentional? It would seem to preclude the
>|>  ability to encode non-ASCII characters in the name.
>|>
>| Yes, it was intentional. A future revision will address IRIs.
>
>My question has nothing to do with IRIs. There are lots of characters
>that can be represented in a URI with a percent escape that have
>nothing to do with IRIs.
>
I prefer to see simple, clear, restricted character set for names. 
Adding %-escapes would allow unneeded extensions, hence the current 
wording (changing the ECMA-6 notes to code points focused on the 
characters, per earlier comments).

>|>Lines 438 and 439 say that the "stage" is optional for schema and wsdl
>|>      artifact types
>|>
>|>  Why? Where is the rational for this. What makes them different from
>|>  catalogs or guidelines or any other type of artifact? If I invent a
>|>  new artifact type, do I get to say if the stage is optional? If not,
>|>  who does? The TC administrator, I assume, but it isn't stated.
>|>
>|>  I think it's wrong to make the stage optional for some types and not
>|>  others.
>|>
>| Original motivation, I think, was to allow a single schema namespace URI
>| without requiring a change for each developement version of a spec. This is
>| existing practices in a number of TCs.
>
>It is certainly a requirement that namespace URIs be allowed to remain
>unchanged through any number of revisions to a specification, but this
>is entirely independent of the names of schema and (AFAIK) WSDL
>documents.
>
We thought we were providing flexibility...Chris Ferris' and Ken 
Holman's comments also address this issue.

Perhaps the context issue solution might also address this? The goal was 
to allow current practice (you don't change the URI for the namespace or 
the schema location unless the schema changes in non-compatible ways).  
Also applies to next segment.

>|>Line 443 introduces a similar relaxation of the rules for revision when
>|>     the artificat type is schema.
>|>
>|>  Why? Where is the rational for this. What makes schemas different from
>|>  catalogs or guidelines or any other type of artifact? If I invent a
>|>  new artifact type, do I get to say if the revision is optional? If not,
>|>  who does? The TC administrator, I assume, but it isn't stated.
>|>
>| You're right; I'd assume the same thing.
>|
>|>  I think it's wrong to make the revision optional for some types and
>|>  not others.
>|>
>| the development argument seems persuasive to me. Happy to discuss further.
>
>If the development argument is persuasive for those two artifact
>types, it's persuasive (to me) for all of them, at least potentially.
>

>
>|>Line 451 introduces section 6 "Filenames"
>|>
>|>  I have no idea how Filenames differ from Artifact Identifiers
>|>  (section 5). Are artifact identifiers not always filenames? I'm
>|>  completely confused by this distinction.
>|>
>| Artifact identifers need not have form, in fact the philosophy is that
>| there is an artifact with (potentially) mulitple forms; Chris's point about
>| relaxNG and xsd schemas is a case in point, as is (x)html and pdf.
>
>If this section only exists to make the distinction that form is
>optional, couldn't we just say that in the other section and delete
>this section?
>
Sounds reasonable; I'll think about it.

>|>Line 482 says filenames MUST bear a reasonable and descriptive
>|>     relationship to the document title
>|>
>|>  Reasonable and descriptive to whom? And what is the document title
>|>  for a schema or stylesheet? At the very least, I think this should
>|>  be a SHOULD as I don't see how it can be enforced.
>|>
>| TCAdmin as part of the publication process for a persistent URI. And no,
>| they won't catch everything.
>
>So it's not really a MUST then, right?
>
It is if TCAdminstration enforces it!

>|>Line 646 reads "docs.oasis-open.org/[product]
>|>
>|>  Surely "docs.oasis-open.org/[tcShortName]/[product]" was intended?
>|>  Ditto lines 653 and 669.
>|>
>| Good point; the unique determination of TC from product would make either
>| OK, but some (including you) dispute that.... :-)
>
>Even if product is unique, leaving out the TC name seems to deprive
>the user of one of the very few pieces of metadata that I think might
>reasonably be encoded in the URI!
>
ACK

>
>                                        Be seeing you,
>                                          norm
>
>  
>