Re: [chairs] Oasis document identifiers - conclusion?

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

Thanks for the comments!  One more round is below.

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

True, but I think we can get away without adding a lot of overhead and 
new terms...

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

I'd rather not.  OASIS process doesn't define a huge number of terms, 
but it does have a clear notion of what OASIS Standards and Committee 
Specifications; each has unique requirements around review and approval. 
    In any case, it sounds like we're in agreement that OASIS Standards 
should be numbered, and others shouldn't...

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

Do others have any experience regarding this?  Since these guidelines 
will largely be self-enforced, maybe we can just rely on good judgment.

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

Sure, but I'm not sure OASIS wants to dictate which format is normative. 
  I was suggesting that at least each set of alternate versions be clear 
about this, with the normative version chosen at the discretion of each 
TC's editors.

(By the way, for the W3C the normative format is HTML, though it's more 
and more common for an XML version to be published alongside it.)

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

Unless other speak up who want this, I suggest we just strike the idea 
for now.

...
>>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 problem is that a Committee Spec really does have a special meaning 
in OASIS process, and in fact it's possible for TC charters to say that 
their entire goal in life is to produce Committee Specs, not OASIS 
Standards.  I think it's important to distinguish drafts that haven't 
reached that special level of TC approval from Committee Specs that have.

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

Good idea (and I note that RFC 3121, which you mention below, defines 
something like this already).  We can do it informally for now, but 
Karl, how about making this a recommended part of TC proposals?

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

I was going to mention that, but decided that since it's out of sight of 
the "official" process, I didn't need to say anything.  Perhaps the 
guidelines that grow out of this discussion can mention this idea as a 
non-normative thing.  It has worked out really well in the SAML TC.

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

OASIS process has no provision for this currently.  I think that it 
would have to become a draft-{TC_identifier}-something in order to 
become an OASIS document.  And there are probably IPR considerations. 
But in any case, having the "draft" there allows for the "disallowed" 
situation.

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

I have been assuming that any kind of document, not just normative ones, 
can be on the "standards track", leading to a Committee Spec or OASIS 
Standard.  The SAML security considerations document is an example of a 
technical-yet-informational spec that has reached OASIS Standard level. 
  But, for example, the UBL Code List White Paper is not intended to go 
through a formal review process of any kind; it's just out there to be 
helpful.  There's no promise that it will ever be updated; it's more 
like a W3C Note than anything, except for the marketing tinge.  If we 
call it info-ubl-codelist-##, then it's all set, even if it goes through 
several revisions.  I'd rather not pursue adding a heavy OASIS process 
to allow for review of such documents.

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

I do think that at least one keyword is needed for non-"review track" 
stuff if we want their names to fit the pattern.  We could, if we want, 
say that these sorts of documents have no particular naming scheme 
whatsoever, of course.  (The UBL TC has produced various white papers 
and presentations, and for the most part hasn't used any special naming 
whatsoever.  I just tried to use a pattern in the one case of the code 
list white paper because, as a "paper", it was similar to our real 
specs, and because I was a spec template author. :-)

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

Are you concerned about inappropriate or too-long descriptions, or do 
you think the descriptions along with the numbers should be unique? 
Perhaps Karl can respond about whether it's reasonable for him to review 
proposed OASIS Standard document identifiers; these could be included in 
the package that gets sent to him to kick off the membership balloting. 
  Doesn't seem too onerous, and the alternative is having everyone 
memorize the numbers.

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

Well, if everything really says "draft", the keyword could be left out 
entirely because it doesn't add anything! :-)  But just in case, let's 
play out my question and assume that my brilliant arguments above have 
convinced you that we need to reflect a Committee Spec status with a 
keyword.  Then, the order would seem to matter.  Is this preferable?

   draft-saml-bindings-05
   draft-saml-bindings-06
   cs-saml-bindings-01

Or is this?

   saml-draft-bindings-05
   saml-draft-bindings-06
   saml-cs-bindings-01

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

Good point!  However, the {type}{:subtype}?:{document-id} stuff appears 
to be somewhat underspecified and depends on precisely the discussion 
that appears in this thread...

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

Not sure I understand.  So the document-id would be the number?  And the 
specification-id would be what -- maybe the description?  Or vice versa?

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

Well, I think this is still unclear.  I would have guessed, left to my 
own devices, that the Technical category is for technically oriented 
OASIS outputs that didn't come from a TC.  E.g., the guidelines we're 
discussing now...  It would be nice to have more input from Karl and 
Norm about what was intended here, since "Technical Notes, Resolutions, 
Memoranda, and Research Papers" has no defined meaning in OASIS process 
unless it's talking about Board outputs.

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

Probably we just need some clarification of what's already there, but if 
a 3121bis seems appropriate, we could do that.

Thanks for the great research and comments!  Now we need the others to 
weigh in...

	Eve
-- 
Eve Maler                                        +1 781 442 3190
Sun Microsystems                            cell +1 781 354 9441
Web Technologies and Standards               eve.maler @ sun.com