OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

oasis-member-discuss message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


/ William Cox <wtcox@comcast.net> was heard to say:
|>* It's incomplete. There are many sections that simply don't describe
|>  the intent of the specification in adequate detail. I don't mean
|>  that as a criticism of the authors or the editors, it's simply a
|>  document that's still in a draft state.
|>
| Which sections specifically? (I should be wearing a bullet-proof vest, I
| think!)

Uhm. At least all the ones for which I provided more detailed comments :-)

|>* Mandatory metadata in the documents, especially in specifications,
|>  is a great idea. In fact, I think it should be made even more
|>  explicit right down to how the metadata is formatted in the
|>  normative XHTML. But the whole scheme for artifact names seems
|>  overly complicated and brittle.
|>
|>  If exampletc publishes V1.0 of a product specification in
|>
|>     http://docs.oasis-open.org/exampletc/product/v1.0/
|>
|>  does it really matter how the individual artifacts at the end of
|>  that path are named? Changing the names of all the stylesheets and
|>  schemas and included modules, etc., every time the spec is revised
|>  may have a significant cost in terms of development time.
|>
| It depends on the focus; if TC-defined names are used (as permitted) there
| might be less of a perceived problem. But I'd also like to know with what
| version/oasis standard an artifact belongs.

You do. It's "version 1.0" of "product" developed by "exampletc".

|>* The draft specifies two normative formats. I remain of the opinion
|>  that this is an unacceptable state of affairs.
|>
| The TC Process, Section 2.18, mandates this.

Ok, so it's not this document that's broken, but having two normative
formats is still broken.

| I think that XHTML (rather
| than HTML) should be in the next version of the TC process, and that the
| PDF is extremely useful for reviews such as this.  This is a complex issue,
| but not one that the TAB is trying to resolve here.

I don't object to publishing it in PDF and XHTML, I just believe it
must be the case that there is exactly one normative versoin.

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

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

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

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

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

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

|>Line 317 introduces the "TC defined name"
|>
|>  I don't understand this section. It begins by saying that this is a
|>  name for "the" artifact, then goes on to give an example that
|>  contains more than one artifact. It speaks of "effectively defining
|>  a container" without explaining what that means. I applaude the example,
|>  but I think it would be valuable to include a more complete example.
|>
|>Line 332 reads "In the absence of an OASISdefinedName for certain
|>         artifacts only a TCdefinedName is used"
|>
|>  What does that mean? Under what circumstances is the OASISdefinedName
|>  absent? For which "certain" artifacts is only a TCdefinedName used?
|>
| This text needs to be reworked. Going backwards from the grammar might
| help, but not enough.  How about we chastise the editor?

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 :-)

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

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

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

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

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

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

|>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!

                                        Be seeing you,
                                          norm

-- 
Norman.Walsh@Sun.COM / XML Standards Architect / Sun Microsystems, Inc.
NOTICE: This email message is for the sole use of the intended
recipient(s) and may contain confidential and privileged information.
Any unauthorized review, use, disclosure or distribution is prohibited.
If you are not the intended recipient, please contact the sender by
reply email and destroy all copies of the original message.

PGP signature



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]