Re: [chairs] Oasis document identifiers - conclusion?

[Jeff Hodges <Jeff.Hodges@sun.com>]

"Eve L. Maler" wrote:
> 
> 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)

    this begs the (good) question of "tracks" in general. oasis presently 
    doesn't explicitly have a notion of "tracks". more on this below in the 
    section on URNs.


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

Yes.

> (I believe the IETF numbering scheme treats
> every output as separate like this.)

Yes. 

>  Alternatively, should they have
> some sort of numeric "root" in common? 

I don't think so, it gets too complex to try to cram into filenames and such.
The IETF handles this issue by a combination of a spec and rfc-index metadata. 

For example, RFC3377 explicitly defines LDAPv3's constituent specifications,
plus said specifications' (plus 3377's) rfc-index metadata indicates the
relationships. See..

  http://www.rfc-editor.org/rfc/rfc3377.txt

  http://www.zvon.org/tmRFC/RFC3377/Output/index.html

  http://www.zvon.org/tmRFC/RFC2251/Output/index.html


  plus, in <ftp://ftp.isi.edu/in-notes/rfc-index.txt>, note the 
  "updated by" and "updates" metadata..
                               .
                               .
  2251 Lightweight Directory Access Protocol (v3). M. Wahl, T. Howes, S.
       Kille. December 1997. (Format: TXT=114488 bytes) (Updated by RFC3377)
       (Status: PROPOSED STANDARD)
                               .
                               .
  3377 Lightweight Directory Access Protocol (v3): Technical
       Specification. J. Hodges, R. Morgan. September 2002. (Format:
       TXT=9981 bytes) (Updates RFC2251, RFC2252, RFC2253, RFC2254, RFC2255,
       RFC2256, RFC2829, RFC2830) (Status: PROPOSED STANDARD)
                               .
                               .




> Should the schema documents
> even get numbers at all?

yes.

> 
> My opinion: All outputs considered part of an OASIS Standard (i.e.,
                                                      ^^^^^^^^
  perhaps what we should more genericaly use here is "Document",
  where an "oasis document" is doc that's been thru some 
  appropriate review process (perhaps simply the present one), no
  matter which "track" the doc is on (eg "standards", "informational", 
  etc.)


> they've been voted on) should ideally be numbered, including schema
> documents and non-normative documents;

agreed.

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

perhaps.


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

agreed.


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

somewhere the IETF says that the rfcnnnn.txt file is normative, if for example,
there's alternative doc formats such as .ps available. 

Ah, it's here (in section 2.4)..
  
  Instructions to Request for Comments (RFC) Authors
  ftp://ftp.rfc-editor.org/in-notes/rfc-editor/instructions2authors.txt

  [..which appears to be headed to RFC-dom itself (it's historically been
   an informal text doc available at rfc-editor.org]

also perhaps of interest is..

  RFC Editorial Policies
  http://www.rfc-editor.org/policy.html


> 
> Karl expressed some interest in seeing Committee Specs uniquely
> numbered the way that OASIS Standards could be, but I was dubious.

I don't think it's a good idea. 


> It's better not to involve OASIS in pure-overhead activities like this
> when just-in-time publishing is of the essence.

agreed.

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


I actually don't really agree with the use of "cs" to denote committee spec.
It's still a draft in the grand scheme of things, and by denoting it with such
an indicator is just going to invite folks to normatively reference it (we have
to fight this tendency in the IETF context all the time) which SHOULD NOT be
done. 

personally, I'd leave everything as "draft-..." until and if oasis-wide
approval of the track-appropriate form is obtained, and then (and only then),
assign a unique identifying number to it (and render that doc immutable). 

this is what's been worked out (with lotsa effort & pain) over the years in the
ietf and seems to work pretty well. 


> 
> The TC name will hopefully be something short yet recognizable, and
> ideally coordinated with the OASIS website's TC area name. 

agreed. rather than calling it "tc name", I'd call it the "tc identifier", and
it should be established at time of TC establishment. 

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

agreed.

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

agreed, but what folks often do for private versions is incr by 1 from the
prior version, and add an alphabetic tag, eg "-09a", and then "incr" the alpha
tag (eg "-09b") as private revs are shared, and then delete the alpha tag upon
wider publication, eg to the TC as a whole. 

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

don't say "never" ;)   IETF thought that too,  but in (very) rare circumstances
an individ submission has gone from I-D (Internet-Draft) to "proposed standard"
maturity-level RFC (and subsequent wide use) without a working group ever being
established (eg SASL rfc2222). 

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

Yes.

> 
> Non-standards-track documents, typically informational or
> marketing-related in nature, should ideally use the following scheme:
> 
>   info-{name_of_TC}-description-nn

I would just simply use "draft-..." in the filename, and only have a different
filename form after it has gone thru some track-appropriate vetting at the
oasis-wide level. Eg "informational" RFCs (see
http://www.ietf.org/rfc/rfc2026.txt, section 4) only become RFCs after IESG 
vetting.


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

I discourage this. 

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


I'm personally waffling about whether "oasis-nnnn" is sufficient, or whether we
should also have the {description} (even tho I suggested the latter). Having
the description in the filename is nice at times, but it may need some sort of
supervisory cycles. 



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

again, I discourage the {keyword} and suggest just draft-... so this becomes
moot. 

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

agreed, tho whether this doc ident is the doc filename or the doc URN is a good
question. more below on this. 


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

It looks fine to me. 


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


actually we have one, courtesy of NormW & KarlB..

  http://www.ietf.org/rfc/rfc3121.txt

!

It defines a URN namespace addressing all the above. 


> Do we want to consider
> assigning URNs to OASIS documents, based (I assume) on whatever
> document identifier naming scheme we adopt?

Yes, I think we want to spec a mapping between all the above in this msg (eg
filenames) to/from the URN namespace (and sub-namespaces) defined in rfc3121.
Docs should include their URN. The putative oasis-index could include them, and
they should probably become the "document identifier" rather than the filename
as we've been doing. Note that rfc3121 specs both a "specification-id" and a
"document-id". these can simply be the monotonically increasing oasis-wide
number (a la RFC #s) that oasis will assign for oasis-wide docs, and it could
be the doc filename for "draft-..." docs. 

Also, wrt "document tracks", rfc3121 nominally specifies two tracks:
"specification" is for standards-track docs, "technical" is for everything else
(eg "informational" track docs).

If we feel strongly enough that we need more categories/tracks, we can write a
rfc3121bis (using IETF processes) that updates or obsoletes rfc3121. This isn't
terribly difficult. 

hope this helps,

JeffH