chairs-filenaming02 XML HTML http://www.oasis-open.org/spectools/docs EveMaler Sun Microsystems, Inc.

eve.maler@sun.com

18 February 2003 2003OASIS Open, Inc. All Rights Reserved. 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. 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 chairs@lists.oasis-open.org list for committee members, send comments there. If you are not on that list, send comments to the editor.

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.

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

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

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.

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 Name Comment odrxml-charter-1.0.htm The initial charter under which the OdrXML TC was formed. odrxml-charter-1.1–01.htm A first draft of a clarified charter being discussed by the TC. odrxml-charter-1.1–01–diff.htm A change-bar form of afirst draft of a clarified charter. odrxml-charter-1.1.htm The clarified charter as approved by the TC. (At this point the charter would need to be formally submitted to OASIS.)

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 Name Comment odrxml-smith-odiousml-1.2.htm A 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.doc A 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.

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 Name Comment odrxml-core-1.0-draft-01.html The first draft of the OdrXML 1.0 Core specification, in HTML form. odrxml-core-1.0–draft-01.pdf The first draft of the OdrXML 1.0 Core specification, in PDF form. odrxml-core-1.0-draft-02.html The second draft of the OdrXML 1.0 Core specification, in HTML form. odrxml-protocol-1.0-draft-17.html The seventeenth draft of the OdrXML 1.0 Protocol specification, in HTML form. odrxml-protocol-1.0-draft-17–20030214.html An 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.html A 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.xsd The 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.html The 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.xsd The approved Committee Specification for the OdrXML 1.0 Protocol schema.

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 Name Comment oasis-1234–odrxml-core-1.0.htm The 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.pdf The 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.htm The 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.xsd The OdrXML Protocol schema module as an OASIS document, number #1236, in W3C XML Schema form.

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. 01 05 Feb 2003 elm Initial draft based on chairs list thread. RFC 2119S. Bradner. RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. IETF (Internet Engineering Task Force). 1997.