Chris -
Thanks for the comments; I'm responding inline. Since this is the first
set of review comments I've addressed in this forum, I've been a bit
wordy.
bill cox
Christopher B Ferris wrote:
Jamie/TAB,
Here are my comments on the ASIS
draft
[1]:
line 264 - according an artifact
type
of "schema" may present problems when there are multiple
schema artifacts (e.g. a RelaxNG and
XML Schema expression of the "schema"). Although, it may be
that "form" could be used
as the qualifier. Perhaps the ASIS should make this unambiguous by
providing
examples of a schema that has both
an
xsd and rng expression.
line 346 - what does this mean?:
Selected
metadata SHALL be included in the name of the artifact pursuant to the
related separate documents.
First, what does "selected"
mean? Does it include the entire list of metadata components cite in
this
section?
Some arbitrary selection thereof?
Secondly,
what does "pursuant to..." mean?
Earlier versions of the guidelines started from a list of "minimal
required metadata" to ease the transition to a real document management
system (i.e., non-Kavi) for OASIS. The historical discussions, visible
as the document evolved, were about how much metadata should be in the
artifact name. So the (inelegantly written) statement is really a
metastatement about how much and which of the minimal required metadata
should be present. I think this should be deleted, as it's really
motivation.
Also the "separate documents" aren't; editorial error.
line 350 - what does "associated"
mean? How is such an association effected? I am associated with the TAB
by virtue of being an alumnus.
However,
I am not IN the TAB.
The expression is covered elsewhere; see for example lines 501-503
(XHTML, etc), 509-511 (significant comments), 517-518 (already done in
document templates), and 525-526. In most of these the association is
"included in the cover page or meta tags."
general - why the seemingly arbitrary
use of SHALL and MUST? They both carry the same semantic
according to RFC2119. It would be my
recommendation that a single form be chosen throughout the docment.
Note also that RFC2119 makes it
clear
that the capitalization of the terms does not make a difference
with regards to the normative
intent.
"something must do something" means exactly the same as
"something MUST do something".
I think that the document could use a scrubbing to ensure that every
use of "must" and "may"
and "should" are examined to ascertain as to whether they are
intended to
communicate some normative
requirement
or whether they are in fact just considered to be prose.
If the latter, then the phrasing
needs
to be changed to make it clear that it is non-normative.
If the document is going to be
unambiguous,
then it MUST follow the RFC2119 guidelines precisely.
Good advice; thanks.
line 352 - that's nice. How are members
and TC chairs supposed to know when these templates have
been modified to conform to the
requirements
of the ASIS? IMO, the ASIS cannot be mandated until
and unless the templates have also
been
modified accordingly. Furthermore, I think that any mandatory
requirement needs to have a formally
defined specification as to whether there is any provision for
grandfathering. e.g. are all
subsequently
published works, regardless of status, required to conform?
Only those new works produced
subsequent
to the mandate? That will need to be made unambiguous
in the document.
The templates were modified some time ago; if you're using the 4/15/05
IPR statement template you're providing pretty much the full set of
metadata.
line 354 - again, what does "associated"
mean?
As above - different artifacts have the information in different ways,
hence "associated"
line 370 - is it intended that only
the "specification, DTD, schema, or fragment" atrifact types
follow
this requirement, or, (as I suspect)
is it intended to apply to all artifact types? What is a "fragment"
type? (I imagine that it is
meant as an XML fragment,
but this is not clear)
The metadata for stage should be associated with all artifacts; "XML
fragments" should be clarified.
line 376 - this seems to be inconsistent
with the statement above on line 288: "If not present, the value of
this component defaults to “en” (English)."
May it be omitted? Seems to suggest
pretty strongly here that it may not be. If so, what purpose does
specifying
the
default on line 288 serve?
This is confusing; thanks for point it out. "en" is optional on
filenames, but not in metadata.
line 394 - again, associated by what
means? I find it difficult to understand how a requirement can be
stated
without
even suggesting the manner by which
it is to be achieved.
lines 401 - I have never seen "ONLY"
used in CAPS form like that before. Also, it might help if they
provided the secret decoder ring
value
of exactly what the "third-level domain" value is. One would
assume "docs.oasis-open.org"
as indicated below. I would strongly recommend a reference to sections
8.1 and 8.2
be made or that
"docs.oasis-open.org"
be specified here.
Your decoder ring seems to be working pretty well :-) The current
docs.oasis-open.org is the answer, but has the current disadvantage
(pointed out by others) that "persistent URIs" refer to that domain and
don't fit the ASIS.
lines 441-444: I think that this is
inconsistent with line 402 which states that an artifact in "os"
status SHALL NOT have a revision. I
think that it would be simpler to simply state that a revision is
REQUIRED
unless the status is "os".
I think that making this optional, despite the MUST is just opening up
for problems.
I would suggest that it simply be a
MUST excepting the case where the arifact has "os" status. If
I publish
an artifact for which there are no
revisions,
and then revise it, do I go back and rename the artifact to reflect
that it was revision 01? Making this
optional is silly.
You're right.
A
value for Revision MUST be included if there is more than one
non-identical
artifact of the same referenced ProductVersion of a Product. Otherwise
a revision MAY be included or omitted. Revisions
of a single ProductVersion must be unique. If ArtifactType is schema
then
a value for Revision MAY be omitted in a parallel name, similar to
those
defined in Section 7.4 (Latest
Version
Subtree) below.
line 492 - states:
The
relevant required metadata for an artifact MUST be maintained at the
default
index page for the http scheme URI for each product and productVersion
to facilitate search and retrieval.
Take a look at the spreadsheet of comments and resolutions from the
previous review. There was a lot of complaint about RDDL, based on
standardization status (not much) and preference to have an index.html
or one of the other default HTML pages. My thought is that a web
browser-presentable document is important, and that OASIS should
provide a template. Again, the first reviewers rejected RDDL pretty
consistently.
What form must this take? A RDDL document?
I guess I am a little confused as there seems to be no guidance as to
how
the metadata is to be captured in the
"index.html" page. What does
this page look like? Does it then provide links to the various forms of
the document that can be retrieved? Why is so little of the
"Required Metadata" that MUST
be "associated" with the artifacts included in this "index.html"
page's <meta/> tags? Why wouldn't the metadata also be
exposed visibly on this page?
For each artifact?
I have advocated within the WS-RX TC
that we use a RDDL document at the namespace URI for the
WS-ReliableMessaging
specification(s)
that links to the spec and to the
schema
(or WSDLs as the case may be).
http://www.oasis-open.org/apps/org/workgroup/ws-rx/email/archives/200601/msg00104.html
Before I left the TAB, I had been
advocating
a similar course of action with regards to the then AIR guidelines. I
helped
Gil craft a microformat[3] for
OASIS metadata that was contained in
a RDDL document. If you view the source of the proposed RDDL documents,
you can see how that works. Of course, the <meta/> tags could
be added to capture the Required
Metadata
as well, so as to facilitate/optimize indexing by search engines, etc.
I would actually like to see OASIS
incorporate
such practice in the ASIS for all namespace URI defined by its TCs, and
would also like
to see this practice extended to all
OASIS "products" such that there were a product "page"
that provided links to all of the relevant
artifacts in RDDL form, with a
location
to hold all of the "associated" metadata.
What do others think? As I said, there was a lot of pushback on RDDL.
line 573: section 6.2 does not specify
how to construct namespace URI. I believe that it should in fact be
section
7,2 that is referenced.
Right.
line 620 - reads: "OASIS SHALL
NOT guarantee any specific lifetime to URNs in those test spaces for
the
TCs." which flies in the
face of the whole concept of a URN.
Quoting from RFC2141 [2]:
"Uniform
Resource Names (URNs) are intended to serve as persistent,
location-independent, resource identifiers."
Thus, the specific lifetime of a URN
is FOREVER. Period. Anything else is an abomination of the whole
concept
of a URN, regardless
of its purpose.
"persistent" doesn't mean "eternal." The resolvability of namespace
URIs in general seems to create much heat (and a little light); the
purpose of these "temp URNs" is to reserve URN space for those groups
that consistently use URNs. If namespace URIs aren't resolvable either,
that creates a problem for having something browsable at the namespace
URI...
line 641-685 - The
WS-RX TC ran headlong into a problem with the
http://docs.oasis-open.org/[product]
convention
because the WSRM TC objected. Seems that
because the WSRM TC has a shortname
that is the
same as the productName assigned by the
OASIS Staff for the WS-ReliableMessaging
specification,
that they thought that there might
be confusion (sigh). Thus, we had to
assign
namespaces that were of the form:
http://docs.oasis-open.org/ws-rx/[product]/...
This is one of the reasons for the TC Adminstrator's involvement in
naming - dispute resolution. My understanding (when I first suggested
"name of the TC + Product Name") was that "Product Name" uniquely
determines the TC/responsible group and also the IPR container. I'll
add my sighs to yours "pursuant" to the next paragraph:
So, I think that given
that there is a normative requirement
in the ASIS that
directly
conflicts with what we HAD to do per the
OASIS staff that it might be
better to
enforce a rule that required that everything
be in the form:
http://docs.oasis-open.org/[tcshortName]/[product]/...
Also, we
chose to use a date for the "[productVersion]"
rather than
what is
prescribed in the ASIS because we did not
want to have the
namespace
bound unnecessarily to the version of a
specification. You will note
the OASIS
WSS 1.1 preserved the namespace from 1.0
for many of the
specified
components so as to preserve backwards compatibility.
I like the date approach (viz. W3C behavior), but "simple" version
numbers have a strong structuring effect. This is an issue that
requires further discussion.
This is an important
point, and IMO the WSS TC did
exactly the right
thing.
However, it would seem to me that a reading
of the current draft of the
ASIS might
be interpreted as making that a clear violation
of the ASIS policy
guidelines
(that will become mandatory).
[1]
http://www.oasis-open.org/committees/download.php/16546/ArtifactStandardIdentificationSchemeForMetadata-1.0.1.pdf
[2]
http://www.faqs.org/rfcs/rfc2141.html
[3]
http://microformats.org/
Cheers,
Christopher
Ferris
STSM, Emerging e-business Industry Architecture
email: chrisfer@us.ibm.com
blog: http://www.ibm.com/developerworks/blogs/dw_blog.jspa?blog=440
phone: +1 508 377 9295
James
Bryce Clark <jamie.clark@oasis-open.org>
wrote on 02/06/2006 02:44:36 PM:
> OASIS Members:
>
> The OASIS Technical Advisory Board (TAB) has asked that the OASIS
> membership and the public review its
>
> OASIS Artifact Standard Identification Scheme
for Metadata
>
> and provide comments during the period ending 1 March 2006
(details
below).
>
> This document, approved by the TAB, proposes rules for how OASIS
artifacts
> (e.g. specifications, schemas, WSDL) are named, what metadata must
be
> associated with each artifact, consistent filenames and persistent
(and
> consistent) URIs for artifacts (incorporating some of the required
> metadata), and updates to the OASIS URN spaces.
>
> This work furthers goals for consistent naming, persistent URIs,
and
the
> efficiency of data and document management across OASIS. Many of
the
> recommendations are already in effect, e.g. in the current
document
> templates. Others are guidance for work in progress, e.g.
persistent
URIs
> for accessing OASIS artifacts.
>
> Please carefully consider the proposed requirements, as their
> implementation will facilitate pending improvements in OASIS
document
> management, process automation, and expression of namespaces.
>
> While this document is written as a set of requirements, the use
of
this
> document is recommended and not mandated. After this second
General
> Membership review in February 2006, we expect that the OASIS
Technical
> Advisory Board will approve a future version as a contribution to
ongoing
> OASIS policy discussions.
>
> Earlier versions of this document, under various names, have been
> circulated to the OASIS Chairs email list and (as the "Artifact
> Identification Requirements") went through a General Membership
Review
> cycle in July 2005.
>
> The package for this General Membership Review includes
>
> (1) This cover letter
>
> (2) The document
> ArtifactStandardIdentificationSchemeForMetadata-v1.0.1.pdf: at
> http://www.oasis-open.org/committees/download.
> php/16546/ArtifactStandardIdentificationSchemeForMetadata-1.0.1.pdf
>
> (3) A spreadsheet listing comments and responses from the July
2005
> review: at:
> http://www.oasis-open.org/committees/download.
> php/16547/ArtifactStandardIdentificationSchemeForMetadata%20Public%
> 20Review%20Resolutions.pdf
>
> Discussion will take place, and comments will be taken from, the
> oasis-member-discuss list; to send to that list and to receive
real-time
> emails, please apply to join the list(login as a member, select
All
Groups,
> scroll down to OASIS Member Discuss, and click the "Join Group"
link. There
> is no waiting period.
>
> Comments will be considered through those received on March 1,
2006,
> midnight US Eastern Standard Time.
>
> Thank you for your consideration of these important issues.
>
> The OASIS TAB
>
>
>
---------------------------------------------------------------------
> This email list is used solely by OASIS for official consortium
> communications. Opt-out requests may be sent to
> member_services@oasis-open.org, however, all members are strongly
> encouraged to maintain a subscription to this list.
>
|