RE: [chairs] Oasis document identifiers - conclusion?

["Eve L. Maler" <eve.maler@sun.com>]

Okay, here's my promised followup.  I don't think we quite have firm
conclusions yet, but we're getting closer.  Here's a summary of
outstanding issues (some of which have been mentioned to me in private
communication):

- How to name OASIS Standards uniquely
- How to associate groups of specs together
- How to name TC outputs in general (both informational and
standards-track)
- How to make bibliographic references to OASIS outputs
- How to assign URNs for OASIS-related namespaces

Below I lay out the issues and suggest some resolutions.  Your
thoughts are welcome.


*OASIS Standard numbering and associating groups of specs:

Karl Best has agreed to assign numbers to OASIS Standards, including
ones already published.  In order for this to happen, though, there
needs to be some agreement about how to handle groups of
specifications and various types of outputs (along with some
retroactive editing).  For example, SAML 1.0 consists of seven
documents, two of which are schema documents.  Should they simply get
independent numbers?  (I believe the IETF numbering scheme treats
every output as separate like this.)  Alternatively, should they have
some sort of numeric "root" in common?  Should the schema documents
even get numbers at all?

My opinion: All outputs considered part of an OASIS Standard (i.e.,
they've been voted on) should ideally be numbered, including schema
documents and non-normative documents; however, I suspect an exception
should be made for sets of schema documents and other machine-readable
outputs because of the needs of the software that consumes them.
Also, I've just tried to come up with a scheme for "sub-numbering" of
individual specs within an OASIS Standard (e.g., the SAML V1.0 Core
spec might be 0012-1 or 0012.1 or something), but I can't come up with
anything I like because the document identifier just gets
progressively uglier.  So I say we should just number each individual
output, and internally they should all properly reference each other
to the extent that they have dependencies.


*Naming TC outputs in general:

The following is mostly opinion/proposal:

Each TC output has a document identifier, which gets used as the main
portion of its filename and is sufficient for uniquely identifying it
in bibliographic references (though a bibliography entry would
typically contain quite a bit more information).  A file extension
indicates a file format in which that output is expressed, e.g.
xxx.doc for a Word file.

It's possible to have alternate file formats for a single output, in
which case you might have xxx.doc and xxx.pdf; in this case, the
documents should include statements clarifying which is normative in
case of discrepancy.

Karl expressed some interest in seeing Committee Specs uniquely
numbered the way that OASIS Standards could be, but I was dubious.
It's better not to involve OASIS in pure-overhead activities like this
when just-in-time publishing is of the essence.

Below is a proposal rolling up all the naming-scheme comments to date:

All TC outputs that are standards-track (meaning they are intended for
either OASIS Standard balloting or even just Committee Spec status),
whether they are normative or non-normative, should use the following
naming scheme:

  {draft|cs}-{name_of_TC}-{description}-nn

The "draft" status should be used for drafts of TC outputs in any
stage of development.  A "draft" does not necessarily convey that the
TC has approved the content or reached consensus on it in any way,
though in fact this may have happened.  A document moves from "draft"
to "cs" (Committee Spec) when the TC has approved it as such.

The TC name will hopefully be something short yet recognizable, and
ideally coordinated with the OASIS website's TC area name.  The TC
name should remain constant during the TC's tenure, to serve as a kind
of "namespace" for its document identifiers.  The description is
entirely up to the TC members/editors.

The "nn" part gets incremented by 1 *every* time there is a new
version sent to the TC list.  (Private versions being worked on by
editing teams can have any name they want.)

Individual proposal submissions for the TC's consideration should use
the following scheme:

  draft-{name_of_proposer}-{description}-nn

The proposer name is typically the family name of the primary
proposer.  (In a way the "draft" part adds nothing, because this sort
of document can never be on a standards track.  But the combination of
"draft" and a second segment that is different from the TC name allows
for proposals to be uniquely distinguished from TC outputs.)

Non-standards-track documents, typically informational or
marketing-related in nature, should ideally use the following scheme:

  info-{name_of_TC}-description-nn

However, TCs can invent new keywords other than "info" if they really
need to.

OASIS Standards should use the following scheme:

  oasis-nnnn-{description}

The description will typically reference the TC name/purpose in
whatever way is appropriate (oasis-0012-saml-core,
oasis-0007-docbook-dtd, or whatever), so that's why the TC name
doesn't have to appear in addition.

Question: In the above, I've kept the original order we've been using
in SAML for quite some time now, to wit,
{keyword}-{name_of_TC/proposer}.  But logically it may make more sense
to reverse these, as the TC name stays constant for everything a TC
produces, and the status will change.  What do people think?


*Bibliographic references to OASIS outputs:

I'm no expert at this, but here is a stab at how bibliography entries
perhaps should look (assuming something like the document identifier
naming scheme proposed above):

[SAMLBind]
  P. Mishra et al., Bindings and Profiles for the OASIS Security
Assertion
  Markup Language (SAML), OASIS, November 2002.  Document ID
  oasis-0012-saml-bindings.  See
http://www.oasis-open.org/committees/security/.

My thinking is that you *need* to mention at least the document
identifier, but the other descriptive information (primary author,
title, sponsoring organization, date) is helpful in traditional
cataloguing.  And the URL is there becuase all things related to the
TC that produced this output can be found there, including this
document, IPR statements, etc.  I'm not really thrilled with how this
looks; does anyone have other ideas?


*URNs:

Currently some OASIS URNs are assigned for things like schemas; e.g.,
SAML's assertion schema has the target namespace
urn:oasis:names:tc:SAML:1.0:assertion.  But there's no control over
how this is done, other than to give each TC their own sub-space.  Do
we need a naming scheme for this as well?  Do we want to consider
assigning URNs to OASIS documents, based (I assume) on whatever
document identifier naming scheme we adopt?


That's all I have time for; I know this doesn't address some of the
stickier procedural issues, but if we can at least get the naming
sorted out, we'll be well on our way.  Sorry for the long message.
Please do weigh in with your thoughts.

Happy new year to all,

	Eve