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: [chairs] Revised filenaming proposal


I have attached the revised filenaming proposal.  Karl and Eduardo, you 
should consider this to be "submitted by the chairs" to you for 
consideration at this point.  Also, Karl, can you tell us the 
disposition of the unique numbering plan?  Are you prepared to do that soon?

Thanks,

	Eve

-- 
Eve Maler                                        +1 781 442 3190
Sun Microsystems                            cell +1 781 354 9441
Web Technologies and Standards               eve.maler @ sun.com
Title: Proposed Rules for OASIS Document File Naming

Proposed Rules for OASIS Document File Naming

Working Draft 02, 18 February 2003

Document identifier:

chairs-filenaming-02 (XML, HTML)

Editor:

Eve Maler, Sun Microsystems, Inc. 

Abstract:

This document provides a proposed set of file naming rules for TC charters, contributions made to TCs, TC drafts and Committee Specifications, and OASIS Standards.

Status:

This document is an informal output of a discussion on the OASIS TC chairs' mailing list and as such has no official standing. The community of chairs intends to follow the rules in this document and is seeking approval of the rules by the OASIS TAB and/or the OASIS Board.

If you are on the list for committee members, send comments there. If you are not on that list, send comments to the editor.



1. Introduction

The community of OASIS TC chairs (archive) has agreed on a set of file naming rules for TC charters, contributions made to TCs, TC drafts and Committee Specifications, and OASIS Standards. We are recommending to the TAB and the OASIS Board that these rules be adopted formally.

The rules adhere to the following general principles:

  • File names should suffice as unique identifiers for use in bibliographic citations, with no ambiguity about which version or revision is meant.

  • Documents at the different maturity levels and with different statuses recognized by OASIS process (contributions, working drafts, Committee Specifications, and OASIS Standards) should be recognizable as such through their file names.

    Note that the OASIS process does not recognize a distinction between normative and non-normative outputs, and both types of output are allowed to be on a full OASIS Standard track. These distinctions could be made informally, however.

  • File names should be readable and meaningful, with few cryptic abbreviations, as long as the overall file name length does not compromise usability.

  • File names should sort alphabetically in a useful manner, even in environments where no sophisticated sorting/querying tools (such as the Kavi system) are available. The most general information should appear first and the least general, last. Version and revision numbers should sort in a way that easily reveals the most and least recent drafts.

  • File names should avoid special characters with which some systems might have difficulty, for example, spaces.

Informal documents produced by a TC that are not on at least a Committee Specification track (such as white papers and presentation slides) are not in the scope of these rules.

2. Terms and Concepts

The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in [RFC 2119].

The file naming rules in this document use the following special terms and concepts:

TC identifier

A short string uniquely identifying an OASIS Technical Committee, used in assigning a TC webpage and in constructing file names. Examples are ubl and odrxml.

document identifier

A string uniquely identifying an OASIS TC output document or OASIS Standard document. Together with a file extension, it serves as the document's file name. However, the document identifier does not include a file extension for purposes of bibliographic citation.

version

A specification development stage that is formally designated with a number (typically in major.minor format, such as 1.0 or 2.3) for purposes of distinguishing levels of implementation and conformance by a public community of developers. An OASIS Standard is associated with a single version throughout its development and approval. For example, several products claim conformance to SAML version 1.0.

revision

A specification development stage that is designated with a number in the form nn for purposes of distinguishing drafts during active TC development. An individual document typically goes through several (or many) revisions before reaching full maturity as a Committee Specification or OASIS Standard.

form

A particular presentation of a document. The same revision of a document might have several forms. Typically the distinguishing factor is the publication file format it uses, where the file extension indicates this information, for example, HTML (.htm or .html), Microsoft Word (.doc or .rtf), OpenOffice.org (.sxw), or PDF (.pdf). Another distinguishing factor might be whether the document uses change bars or other change-tracking devices; in this case, an extended description in the file name provides this information (for example, -diff).

stage

A specification maturity level, as recognized by the OASIS TC process rules. The two stages requiring special levels of TC and membership approval are Committee Specification and OASIS Standard. Prior to becoming a Committee Specification, a document is just known as a "draft" or "working draft"and cannot be assumed to have TC approval or support.

OASIS Standard

A collection of one or more documents that have been submitted to an OASIS membership balloting process and have received approval by that body. Each individual OASIS Standard document has a unique document identifier. It is appropriate to say that "SAML 1.0 is an OASIS Standard" but also that "The SAML 1.0 bindings document (one of seven SAML 1.0 documents) has reached OASIS Standard status and is an OASIS Standard document."

OASIS number

A four-digit number assigned to each OASIS Standard document that is unique across all OASIS Standard documents in all versions and revisions (but not all forms).

Note

The notion of an OASIS number is new, and requires a minimal level of coordination and support on the part of OASIS staff, as OASIS itself must assign these numbers.

TC output

Any document or file produced by a TC that is either the TC's charter or is on an OASIS Standard or Committee Spec track, before OASIS Standard approval has been granted. For example, if a TC produces a draft technical specification and a corresponding set of W3C XML Schema modules, all are considered TC outputs, and each document needs a unique document identifier.

If a TC output is in the form of an SGML or XML document that has multiple external parsed entities, the individual entity files are not seen as TC outputs in and of themselves; they merely form part of a single TC outputs.

contribution

A document that has been submitted by an OASIS member for consideration by a TC.

3. File Naming Rules

The following sections provide the proposed file naming rules for OASIS documents.

3.1. General Rules

The following rules apply to all documents:

  • Hyphens must be used as separators of the major portions of a file name. Spaces must not be used. Hyphens are recommended between words within the description and extended description portions, though underscores may be used. Hyphens are preferred because they are easier to see in displayed URIs and easier to type.

  • Lowercase spelling is recommended.

Below, examples for hypothetical documents produced by the Online Dispute Resolution TC (TC identifier odrxml) are provided for each set of rules.

3.2. Rules for Charters

TC charters must use the following file naming rule. The TC may choose its own version numbering scheme.

tcid-charter-version[-revision][-extdesc].ext
Example File NameComment
odrxml-charter-1.0.htmThe initial charter under which the OdrXML TC was formed.
odrxml-charter-1.1–01.htmA first draft of a clarified charter being discussed by the TC.
odrxml-charter-1.1–01–diff.htmA change-bar form of afirst draft of a clarified charter.
odrxml-charter-1.1.htmThe clarified charter as approved by the TC. (At this point the charter would need to be formally submitted to OASIS.)

3.3. Rules for Contributions

Contributions must use the following file naming rule. It is recommended to use the primary author's family name or surname as the contributor ID. The contributors may choose their own description field and extended description field.

contributorid-description[-revision][-extdesc].ext
Example File NameComment
odrxml-smith-odiousml-1.2.htmA contribution, in HTML form. The primary author's family name is Smith and the contribution is a specification called OdiousML that has (outside of OASIS) been developed to a Version 1.2 level. Here the version is considered part of the description field. The revision field could have been used if the contributor expected to revise the contribution and resubmit it.
odrxml-jones-oddxml-01.docA contribution, in Microsoft Word form. The primary author's family name is Jones and the contribution is a proposal called OddXML. It doesn't have a well-known version identifier, and perhaps was developed specifically for consideration by the TC. Here a revision field is a good idea, particularly if the contribution is considered a member's "position paper" that is likely to be updated.

3.4. Rules for TC Outputs

TC outputs must use one of the following two file naming rules. The TC may choose its own description field, extended description field, and version numbering scheme. A keyword is used to indicate the document stage: either draft for working drafts or cs for Committee Specifications. The revision field is optional for Committee Specifications, depending on whether the TC expects to make minor revisions to essentially stable drafts in response to the public review period. The extended description field may be used to provide the publication date, but it is recommended not to do this for Committee Specifications.

tcid-description-version-draft-revision[-extdesc].ext
tcid-description-version-cs[-revision][-extdesc].ext
Example File NameComment
odrxml-core-1.0-draft-01.htmlThe first draft of the OdrXML 1.0 Core specification, in HTML form.
odrxml-core-1.0–draft-01.pdfThe first draft of the OdrXML 1.0 Core specification, in PDF form.
odrxml-core-1.0-draft-02.htmlThe second draft of the OdrXML 1.0 Core specification, in HTML form.
odrxml-protocol-1.0-draft-17.htmlThe seventeenth draft of the OdrXML 1.0 Protocol specification, in HTML form.
odrxml-protocol-1.0-draft-17–20030214.htmlAn alternative name that could have been used for the above document, with a numerically encoded date as the extended description.
odrxml-protocol-1.0–draft-17–diff.htmlA change-bar HTML form of the seventeenth draft of the OdrXML 1.0 Protocol specification. Here the extended description contains diff to indicate its change-bar form.
odrxml-protocol-schema-1.0–draft-03.xsdThe third draft of the OdrXML 1.0 protocol schema module, in W3C XML Schema form. The description field is protocol-schema.
odrxml-protocol-1.0–cs.htmlThe approved Committee Specification for the OdrXML 1.0 Protocol. The revision field could have been added here if errata fixes were expected.
odrxml-protocol-schema-1.0–cs.xsdThe approved Committee Specification for the OdrXML 1.0 Protocol schema.

3.5. Rules for OASIS Standards

OASIS Standard documents must use the following file naming rule. The OASIS staff is responsible for assigning the OASIS number. The number is unique across all OASIS Standard documents in all versions and revisions (but not all forms).

oasis-oasisnumber-tcid-description-version.ext
Example File NameComment
oasis-1234–odrxml-core-1.0.htmThe OdrXML Core specification as an OASIS Standard document, number #1234, in HTML form. The OASIS staff assigned this number when the OdrXML 1.0 set of specifications was approved as an OASIS standard.
oasis-1234–odrxml-core-1.0.pdfThe same specification, in PDF form. Note that #1234 uniquely refers to the OdrXML Core content, but is allowed to apply to multiple forms of that content simultaneously.
oasis-1235–odrxml-protocol-1.0.htmThe OdrXML Protocol specification as an OASIS Standard document, number #1235, in HTML form. Presumably all of the OdrXML 1.0 OASIS numbers were assigned in a contiguous block, though this is not required.
oasis-1236–ordxml-protocol-schema-1.0.xsdThe OdrXML Protocol schema module as an OASIS document, number #1236, in W3C XML Schema form.

A. Notices

Copyright © The Organization for the Advancement of Structured Information Standards [OASIS] 2001–2003. All Rights Reserved.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification, can be obtained from the OASIS Executive Director.

OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS Executive Director.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS has been notified of intellectual property rights claimed in regard to some or all of the contents of this specification. For more information consult the online list of claimed rights.

B. Revision History

Revision 0105 Feb 2003elm
Initial draft based on chairs list thread.

References

Normative

[RFC 2119] S. Bradner. RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. IETF (Internet Engineering Task Force). 1997.



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


Powered by eList eXpress LLC