Proposed Rules for OASIS Document File Naming
Working Draft 01, 5 February 2003
- Document identifier:
chairs-filenaming-01 (XML, HTML)
This document provides a proposed set of file naming rules for TC charters,
contributions made to TCs, TC drafts and Committee Specifications, and OASIS
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 <@@email@example.com> list
for committee members, send comments there. If you are not on that list, send
comments to the editor.
Copyright © 2003 OASIS Open, Inc. All Rights Reserved.
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
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,
File names should be readable and meaningful, with few cryptic
abbreviations, as long as the overall file name length does not compromise
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 [RFC 2119].
The file naming rules in this document use the following special terms
- 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. [@@ How do people feel about this? Should
the file extension be part of the citation?]
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.
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.
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).
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).
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.
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
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
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.
|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.)|
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.
|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.|
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. [@@ Do people agree?
SAML had a revision to its CSs, and nothing in the OASIS process prevents
frequent Committee Specification approvals.]
|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
|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.|
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). [@@ Should extended descriptions be allowed
here? Would change-bar forms of OASIS Standard documents be expected?]
|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
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 01||05 Feb 2003||elm|
|Initial draft based on chairs list thread.|