Re: [chairs] Oasis document identifiers - conclusion?

[Rex Brooks <rexb@starbourne.com>]

I don't have a lot of comment on this and where I do, I include it 
within the dialog at the appropriate point.

I do think that this needs to be coordinated with what OASIS is doing 
with Kavi on standardizing formatting for various system-wide 
functions, and perhaps the chairs list needs to review the 
recommendations and procedures before they are completely adopted. I 
leave it to others, however, to do so. I like all of us have my hands 
full with what the TCs I work in are doing.

At 5:50 PM -0500 1/4/03, Eve L. Maler wrote:
>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...

I agree, and yes, please to Eve's comment.

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

I agree.

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

That's fine until it becomes apparent that a TC needs to change its 
name, or combine two TCs into one, which has been and is the case in 
the three TCs in which I work..

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


Same Problem as previous. As long as it is a SHOULD and not a MUST, 
I'm okay with it.

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

I second Eve's comments. Primers, User Guides, White Papers, etc. 
should remain informal. Way too much work for too little importance 
in terms of OASIS' needs, but extremely important for the 
implementors.

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

I think draft is sufficient.

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

I think that "technical" needs to be subdivided into "informational" 
and  "research."

>>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
>
>
>----------------------------------------------------------------
>To subscribe or unsubscribe from this elist use the subscription
>manager: <http://lists.oasis-open.org/ob/adm.pl>

Ciao,
Rex

-- 
Rex Brooks
Starbourne Communications Design
1361-A Addison, Berkeley, CA 94702 *510-849-2309
http://www.starbourne.com * rexb@starbourne.com