OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

chairs message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: Re: [chairs] Oasis document identifiers - conclusion?

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

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.

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

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 

>>>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
>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):
>>>  P. Mishra et al., Bindings and Profiles for the OASIS Security
>>>  Markup Language (SAML), OASIS, November 2002.  Document ID
>>>  oasis-0012-saml-bindings.  See
>>>My thinking is that you *need* to mention at least the document
>>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.
>  >
>>>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 

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>


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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC