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
• 2. Definitions
• 3. Name Characters for Files and Directories
• 4. Name Construction Rules for Files and Directories
• 5. Identifiers for Version, Stage, and Revision
• 6. Rules for URIs and Resources
• 7. XML Namespace Identifiers and Namespace Documents
• 8. Notes

---

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.

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.

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.

• An XML namespace name identified by an HTTP scheme URI reference must conform to the pattern:

  http://docs.oasis-open.org/ns/[tc-shortname]/xxxx

  Where:

  • "[tc-shortname]" is the official spelling of the TC abbreviation as used in the (Kavi) group and typically in the TC email list URI (e.g., cmis in the NS http://docs.oasis-open.org/ns/cmis/core/200908/)
  • "xxxx" is a short string identifying an XML namespace, which should incorporate a versioning subcomponent (e.g., a string like 201011 representing a date)
  • "xxxx" may use any of the same thirty-eight characters as names for files and directories/folders, plus internal "/", and may terminate with the character "/" or "#"

• The pattern specified above for HTTP scheme URIs uses the /ns/ path element in a syntax reserved for identifying non-information resources only. Therefore, no (file-system) regular files, directories/folders, or symbolic links matching information resources may make use of these URI strings for resource identification.

• Non-information resources using identifiers associated with XML namespaces may be based upon any HTTP scheme URI XML namespace declared by the TC (i.e., identifiers for named properties, functions, dialects, faults, actions, or any named message types).

• Any HTTP scheme URI matching the base pattern of a declared XML namespace, when dereferenced, will resolve under DNS+HTTP to (fetch) the corresponding namespace document which documents the namespace and the specification which declares it. The OASIS TC Administrator maintains the namespace documents in consultation with TC specification editors.

• URN-based XML namespaces may be declared by existing TCs that have already used this feature, or by associated Maintenance Activity TCs, where architectural considerations require continued use of URNs. URN-based XML namespaces must not be declared otherwise, since they lack a standard, ubiquitous resolution method using DNS[+HTTP]. In URNs, the colon (":") character is expected.

• TCs must define a namespace versioning policy for any XML namespace declared in a specification, and must communicate the text expressing such policy to the TC Administrator for incorporation into the appropriate namespace document.

8. Notes

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

• Filenames without extensions. Exceptions to the rule that every filename much include a file extension include: CATALOG or catalog, README, ChangeLog. Please contact the TC Administrator if you wish to recommend additional filenames for consideration.

• Information resource and non-information resource. The term (non-)information resource (mentioned above) is sometimes used to distinguish [1] computer-managed (serializable, textual or binary) objects like document files, image files, video files from [2] physical objects like cars and human persons, or abstract concepts like "smooth". While the two terms are not universally accepted, they offer a convenient way to distinguish documents from XML namespaces. Since an XML namespace is an abstract space of names (possibly unbounded) identified by a URI reference, it is considered a non-information resource.

• Member-only URIs vs. public URIs. The Kavi collaboration tool [as of 2010-10] creates a private OASIS member-only URI for most resources, and while these private URI references "work" for OASIS members who are logged in, they are broken for all other users, and give the appearance of OASIS-private resources that are not available to the public. Since that outcome frustrates/annoys users and creates a negative/false impression about the "openness" of OASIS, TC members are urged to ensure that the public form of any URI reference is cited in all communications and documents under their control.

• Work Product title/name. A document title, also called a Work Product name, (e.g., TC Process Sections 2.18 and 2.19), should be composed from a suitable identifier followed by the word "Version" and the Version number. The title of a Work Product must not include any trademarks or service marks not owned by OASIS. Any acronyms in the title should be spelled out, but full spelling is not required. When formatted for display, the complete title should be treated as though it is a single line of text.

• Scope. The naming directives in this document (especially for name characters and construction) are intended to apply broadly to all official OASIS publication venues, including the OASIS Library, TC document repository, email list archives (file attachments), Wikis, SVN (Subversion) repository instances, JIRA issues tracking facilities, TC/SC web sites, Member Section web sites, etc. For a partial list of URIs, see:

  • OASIS Wiki List, and example XACML TC Wiki
  • SVN (Subversion) Repositories, and example SCA-Assemby TC SVN Repository
  • JIRA Issues Tracker, and example Office/OpenDocument TC Issues Tracking

• TC document repository. With a few approved exceptions (e.g., TC meeting minutes published to the general mailing list), the TC Process requires that work produced by TC Members must be uploaded to "the TC's document repository" in the appropriate folder(s). This fulfills the TC Process requirement "Editable formats of all versions of TC documents must be delivered to the TC's document repository" (2.18 (4)). TC Members should understand that content uploaded to the TC document repository for approval by TC ballot will be QC'd and then installed in the OASIS Library by the TC Administrator.

  Each OASIS TC is assigned a "document repository" (as of 2010-10) through the Kavi collaboration suite. For example, in the case of the OASIS Provisioning Services TC, a publicly accessible link to the TC's document repository is: http://www.oasis-open.org/committees/documents.php?wg_abbrev=provision. TC members upload files to that repository through the [Kavi] "TC Members Page" by navigating to the Documents area, locating the appropriate Folder, and clicking the button for "Add New Document" in that Folder.

• Track. TC members should take into account various options for document development and approval through a life-cycle suitable for any particular deliverable. The OASIS Technical Committee Process effective October 15, 2010 introduced a two-track system for OASIS Work Products, so that a Work Product is classified as either a Standards Track Work Product or a Non-Standards Track Work Product. Whereas a Standards Track Work Product is designed for implementation, a Non-Standards Track Work Product is typically used for creation of TC-approved white papers, slide presentations, and other material used for educational or promotional purposes. The review and approval processes for Work Products in the two tracks are (almost) identical, as are most rules for the creation of document identifiers, required file formats, etc.

  A Standards Track Work Product, intended as an implementation specification, contains a required set of numbered conformance clauses and has Normative References. A Non-Standards Track Work Product does not contain normative statements that define mandatory conformance requirements. It may not be submitted for approval by the Consortium membership as an OASIS Standard, and the patent provisions of the OASIS IPR Policy (under a TC's chosen IPR Mode) do not apply.

---

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