OASIS Naming Directives

Date: October 14, 2010
Version: 1.0
This version: http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives-v1.0.html
Latest version: http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html


Contents


1. Introduction

This document specifies rules for proper naming, identification, and usage of URI references for documents produced by OASIS Technical Committees. The OASIS Technical Committee Process provides the broader framework for these rules.

2. Definitions

document identifier — an identifier string that corresponds to a filename in a cover page document URI, minus the .ext portion of the filename; a document identifier is used in a page footer

OASIS Library — the official OASIS repository for approved work, located at the URI http://docs.oasis-open.org

stage — a stage, also called an approval stage, is a track-specific named level of maturity for Work Products, and includes the pre-track Working Draft stage

TC document repository — a specific document repository assigned to each TC and required as an upload location for contributions, drafts, and Work Products queued for approval.

Version — a major Version of a Work Product developed through a continuous process of authoring, review, editorial revision, where approved publication instances correspond to development stages belonging to one Version.

3. Name Characters for Files and Directories

For any filename or directory/folder name, TCs must use only the thirty-six characters [0-9A-Za-z] and two punctuation characters: "." (period), and "-" (hyphen).

These name character restrictions must be adhered to for all files/directories associated with approved Work Products and any candidates for TC approval (e.g., Working Drafts). The rules should be followed in all other contexts where OASIS tools and publication venues support the constraints.

The underscore character ("_") may be used in cases where an application (unavoidably) generates this character, but an underscore must never be used in a filename or directory name that appears in a document cover page URI (i.e., in a URI required for identification of a work as a whole).

4. Name Construction Rules for Files and Directories

Name construction rules define how characters may be used to compose names for files and directories, i.e., prescription for the lexical and syntactic structure of names, given the restricted character inventory. Motivations for these constraints include concerns for fidelity of interchange across different file systems, minimizing the risks of common text-processing errors, usability (visual clarity), and other interoperability considerations.

Constraints:

  1. TCs may use mixed case (upper case characters mixed with lower case characters) in filenames and directory names, including camel case. TCs should understand that OASIS web servers will respect case-sensitivity, with no accommodation for case-folding.
  2. Filenames and directory names must not contain the trademarked names of products, companies, or other corporate entities where the mark is not owned by OASIS.
  3. Filenames and directory names must neither begin nor end with a punctuation character (period or hyphen). Similarly, the document identifier portion of a filename must not end with a punctuation character.
  4. Filenames and directory names must not contain multiple (2+) consecutive punctuation characters
  5. A filename used within a required cover page URI must have the structure [WP-abbrev][version-id]-[stage-abbrev][revisionNumber].[ext], where [WP-abbrev] is a name under TC control matching the agreed-upon Work Product abbreviation, [version-id] is a versioning identifier component composed of the single character [Vv] (either case), followed by a numeric string matching the rules for Version (e.g., V1.1), [stage-abbrev] is a stage abbreviation in lower case characters, [revisionNumber] is a two-digit number as prescribed below, and [ext] is a file extension.
  6. A single file(name) extension must be used in each filename except for a recognized set of extensionless filenames in common use. File extensions should conform to industry best practice — matching well-known MIME Media Types.
  7. A directory must not contain two or more names (filenames or directory names) that differ ONLY in case. For example, a directory must not contain two directories FOO and Foo, nor two files with filenames BAR.txt and bar.txt.
  8. Except as approved by the TC Administrator, filenames having special meaning for operating systems or for OASIS server software must not be used in any Work Product. For example, the following are forbidden: index.html, index.htm, and *.cgi.

The name construction rules enumerated above must be followed for files/directories associated with approved Work Products and any candidate work for TC approval (e.g., Working Drafts). They should be followed in all other contexts where OASIS tools and publication venues support these constraints.

5. Identifiers for Version, Stage, and Revision

Filenames and directory names must be used with other naming components to create prescribed URI references (e.g., hyperlinks) for documents and document portions. This section explains the required use of identifiers for Version, Stage, and Revision which are relevant to creation of URI references for resources within a directory hierarchy.

Version

Formally, a Version of a Work Product is a numeric identifier associated with a focused technical activity that proceeds on the Standards Track or Non-Standards Track through a number of development stages, often leading to the creation of an OASIS final deliverable.

A Version in this formal sense must be represented textually by a numeric string composed of digits [0-9] and period (".") corresponding to any of the approved lexical models (#.#, e.g. 1.0; #.##, e.g. 1.01; #.#.#, e.g. 1.2.1; ##.#, e.g. 10.1). Use of any other pattern for a Version identifier must be negotiated with the TC Administration.

A Version identifier must be used as a discrete path element in document URIs, and must also be used in a document's principal URI filenames (i.e., filenames in required URIs used on a cover page). A Version identifier must also be incorporated into a Work Product name/title.

Informally, OASIS policy documents use the word "version" (lower case) in casual reference to a variant of any kind, in common speech: a variant file format ("the HTML version"), any natural successor or predecessor ("the latest version", "the previous version"), any comparative representation ("the diff-marked version") or any package type ("the compressed ZIP version"), etc. In this document, "Version" (upper case) always refers to the major Version in its formal sense, while "version" (lower case) represents generic usage of the word.

Stage

Each published instance (or, package "release") of a Working Draft or approved Work Product is identified by a name for a stage in combination with a revision number. In textual representation, example stage identifiers would be "Working Draft 01" and "Committee Specification Draft 02". The full names and abbreviations for each stage, within track, are presented below. A stage abbreviation with a revision number must be used in lower case as a discrete path component for document URIs and in principal document filenames.

Revision

The process of document revision as a technical activity takes place when an approved Work Product is edited and is assigned a new Working Draft revision number. Textually, a revision is a two-digit number associated with a Working Draft or a specific stage corresponding to a published instance. A revision number begins with "01" and is incremented by 1 for each release at each maturity level (stage).

A revision number is a required component within filenames used on a document cover page.

6. Rules for URIs and Resources

This section sets out rules for construction of path elements in document URIs (prescribed naming patterns within URIs as strings), rules for persistence of URIs, for permanence of published OASIS resources, and appropriate selection of URI references for various usage contexts. TC editors need to understand these rules and the required use of identifier components in order to design a hierarchy of directories that will be used in successive stages through the progress of Work Product development and publication.

Path components in document URIs

URIs serving as primary identifiers for Work Products installed in the OASIS Library must conform to this pattern:

http://docs.oasis-open.org/[tc-shortname]/[WP-abbrev]/[version-id]/[stage-abbrev][revisionNumber]/[doc-id].[ext]

Where:

  • [tc-shortname] is the official TC abbreviation as used in the (Kavi) group and typically in the TC email list URI
  • [WP-abbrev] is a name under TC control matching the agreed-upon abbreviation/acronym for the Work Product name
  • [version-id] is a versioning identifier component composed of the single character "v" (lower case), followed by a numeric string matching the rules for Version (e.g., v2.0)
  • [stage-abbrev] is the abbreviation for the document stage
  • [revisionNumber] is a two-digit number for the revision at the designated stage
  • [doc-id] is an identifier corresponding to the filename minus the final .ext portion
  • [ext] is the file extension

TCs may also design path components relative to a particular stage where additional directories are created below /[stage-abbrev][revisionNumber]/ viz., at the same hierarchical level as the principal document URIs ([doc-id].[ext]). For example:

http://docs.oasis-open.org/[tc-shortname]/[WP-abbrev]/[version-id]/[stage-abbrev][revisionNumber]/schemas/*.*
http://docs.oasis-open.org/[tc-shortname]/[WP-abbrev]/[version-id]/[stage-abbrev][revisionNumber]/examples/*.*

For content published in the OASIS Library, TCs may create URI references using the path segments "." and ".." ("dot-segments") for relative reference within a path name hierarchy. However, TC Members must take responsibility for constructing such paths in a way that all relative references resolve correctly.

Required document URIs

Following a convention commonly used in other standards organizations, OASIS requires that Work Products present three general kinds of URIs as display metadata, illustrated below: This version, Previous version (when applicable), and Latest version. These three labels are used e.g., by The World Wide Web Consortium (W3C), the Web Services Interoperability Organization (WS-I), The Unicode Consortium, the The Dublin Core Metadata Initiative (DCMI), etc. Note the lower case spelling of version, signifying that the three labels identify published instances corresponding to different approval stages, not to be confused with the major Work Product Version.

  • Label: This version. A URI specific to the Work Product current at the time of publication; it is persistent, permanently assigned to one particular specification instance, and is never re-used.

  • Label: Previous version. A URI used as applicable to reference the previous published instance of a work; it corresponds to the This version URI of the immediate genetic ancestor of any given instance, unless the specification in question is the very first instance.

  • Label: Latest version. A bookmarkable generic URI serving as a URI alias which is always associated with the latest/now-current specification instance, thus having a changing referent. It serves to identify and directly locate each successive published instance of a developing specification, through time. This locator URI does not contain the path component [stage-abbrev][revisionNumber] or stage identifier in the filename.

Document Cover Page URIs (Hypothetical Example)

This version:
      http://docs.oasis-open.org/exampleTC/ourSpec/v2.0/cd03/ourSpecV2.0-cd03.html
      http://docs.oasis-open.org/exampleTC/ourSpec/v2.0/cd03/ourSpecV2.0-cd03.pdf
      http://docs.oasis-open.org/exampleTC/ourSpec/v2.0/cd03/ourSpecV2.0-cd03.doc
Previous version:
      http://docs.oasis-open.org/exampleTC/ourSpec/v2.0/cd02/ourSpecV2.0-cd02.html
      http://docs.oasis-open.org/exampleTC/ourSpec/v2.0/cd02/ourSpecV2.0-cd02.pdf
      http://docs.oasis-open.org/exampleTC/ourSpec/v2.0/cd02/ourSpecV2.0-cd02.doc
Latest version:
      http://docs.oasis-open.org/exampleTC/ourSpec/v2.0/ourSpecV2.0.html
      http://docs.oasis-open.org/exampleTC/ourSpec/v2.0/ourSpecV2.0.pdf
      http://docs.oasis-open.org/exampleTC/ourSpec/v2.0/ourSpecV2.0.doc

Resource Permanence

As part of the OASIS commitment to transparency, openness, and accountability, resources published in the OASIS Library, TC Document Repository, and other venues must not be deleted. All revisions are retained. With the exception of resources identified by "latest version" URI aliases, content instantiated as regular files and directories must not be over-written, replaced, renamed, or removed. TC Members are expected to follow this rule even in cases where a collaboration tool (by some means) might allow resource deletion.

URI Persistence

Corollary to Resource Permanence, URIs for published OASIS resources must be persistent. All resources and the Uniform Resource Identifiers (URIs) which establish mappings from identifiers to resources are permanent. This rule also applies to any secondary resource identified by a fragment identifier. Assignment of URIs to resources is thus considered to be inviolate other than for URI aliases intentionally associated with variable content. For all other URIs, no action which severs the relationship between a URI and the resource may be undertaken.

URI Aliases

TCs must not use URI aliasing by any means, including, for example, unauthorized: (a) use of META-refresh elements, (b) preparing files with identical content under two different filenames within a given published instance, or (c) constructing URIs for canonical OASIS resources by using redirects supported by services on other Internet domains (e.g., http://tinyurl.com/, http://purl.oclc.org/, http://bit.ly/).

Using Appropriate URI References

This subsection explains how to select appropriate URI references for documents so that all users will be able to access the resources online and will be directed to the appropriate representation for a published instance of a work.

URI references for different use cases

TC editors and others should select the best URI reference suitable to the reader's need:

  • Select the URI for the current published document if you want the reader to examine something specific in that instance; select URI for the latest instance if you want the reader to access the very most recent publication, now or in the future
  • Select the URI for the document directory in the OASIS Library if you want the reader to scan the entire hierarchy of files/directories. Example, the directory for UBL prd1-UBL-2.1.
  • Select the URI for the ZIP package corresponding to a published instance if you think the most appropriate use (e.g., testing) will be for the reader to download the package and install the files locally. Example, the ZIP file for UBL prd1-UBL-2.1.

Publicly Accessible URIs

In support of the OASIS TC Process rules for public visibility of all TC resources, TC Members must be careful to select an appropriate form of a URI reference to ensure that a resource is publicly accessible from that URI reference. Member-only (private, password-protected) URI references created by OASIS tools must not be cited in TC mailing list messages or in any documents that may become public. In some cases, the mechanical transform from a member-only (private) URI to the correct public URI can be made by replacing the substring 'apps/org/workgroup/{tc-short-name}/' with 'committees'. Here are examples for documents, email messages, ballots, and calendar entries:

Document

Email message

TC ballot listing

TC individual ballot

TC calendar entry

7. XML Namespace Identifiers and Namespace Documents

OASIS Work Products which declare XML namespaces are required to adhere to several OASIS rules for construction of URI references and use of namespace documents where applicable.

8. Notes

This reference section is intended to provide details (exceptional cases, etc). For definitions that may provide useful clarification, see Definitions.


Feedback: Please send questions or comments on this document to robin@oasis-open.org.