OASIS Naming Guidelines Part 1: Filenames, URIs, Namespaces
OASIS Naming Guidelines, In Two Parts
Part 1: Filenames, URIs, Namespaces
Part 2: Metadata and Versioning
Note: For Technical Committee work governed by the OASIS Technical Committee Process effective October 15, 2010, please see the document
OASIS Naming Directives,
which updates the naming rules to match the revised TC Process. Information in this document may still be useful for
background (e.g., rationale for vintage-2008 decisions) and other historic purposes. For most other purposes, the
OASIS Naming Directives
document supercedes this document — OASIS Naming Guidelines, In Two Parts and commentary.
Date: 2008-10-09, Minor Update 2009-08-01
Editor: Robin Cover
This Version: http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNamingV08.html
Latest Version: http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNaming.html
Previous Version: http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNamingV07.html
Status: The OASIS Board has approved the Guidelines for use as of 2006-08-02; OASIS Staff is authorized to update the guidelines from time to time as needed.
Review Comments: send to email@example.com
This document (OASIS Naming Guidelines Part 1: Filenames, URIs, Namespaces) presents core requirements for naming; rules for display metadata and versioning are presented in OASIS Naming Guidelines Part 2: Metadata and Versioning. Commentary and examples are provided in "Commentary on Guidelines for Filenames, URIs, and Namespaces."
- The rules and guidelines presented in this document and its predecessors are concerned chiefly with resources targeted for publication in the OASIS Open Library (http://docs.oasis-open.org/) — and not with resources submitted to a TC's Kavi repository. In many cases, Kavi [as currently installed] does not or cannot support the requirements implicit in this design effort. Nor are the rules envisioned as applicable to resources published on other OASIS-owned Internet domains (e.g., uddi.org, dcml.org, cgmopen.org, psi.org, pkiforum.org, legalxml.org, topicmaps.org [being transferred to ISO/IEC JTC 1/SC 34], ebxml.org, www.oasis-open.org, etc.
- The guidelines are not concerned with names used in XML markup constructs (e.g., names in elements, attributes, entities, PITargets, etc.)
- No retroactive application of rules is envisioned for resources already accessible via the OASIS Open Library; URIs and resources as currently exist will be grandfathered
- While the guidelines are intended to apply to any new resource uploaded to the OASIS Open Library, they are concerned mainly with specification-track documents and related resources (Working Drafts, Committee Drafts, Committee Specifications, Public Review Drafts, OASIS Standards) as defined by the TC Process document, and announced in November 2005.
- All resources installed in the OASIS Open Library are governed by the naming guidelines — whether documents produced by Technical Committees or materials contributed to OASIS from external sources, whether targeted for direct access on the file system or embedded within package files (.ZIP, .tgz).
- The guidelines are intended to fulfill the expectation articulated in the TC Process "2.18 Specification Quality" [2007-01-25]: "All documents and other files produced by the TC, including specifications at any level of approval, must use the OASIS file naming scheme, and must include the OASIS copyright notice. All document files must be written using the OASIS document authoring templates, which shall be published and maintained by the TC Administrator."
"Name Characters" here refers to characters used in URIs — including filenames, directory names, colon- or slash-delimited components within namespace URIs, delimiters, and possibly other URI subcomponents as may be labeled.
- Ignoring usage constraints: The complete character set for naming OASIS resources is [0-9A-Za-z] plus "."(period), "-" (hyphen), "_" (underscore), "/" (slash), "#" (hash), and ":" (colon).
- In most contexts, allowable name characters include [0-9A-Za-z] plus "."(period) and "-" (hyphen)
- Underscore is ("_") allowed in designated contexts where use of hyphen is impractical or undesirable
- Hyphen is the preferred character for use as an internal delimiter between name subelements if an explicit charcter is used; juncture may also be marked by camel case orthography
- The slash ("/") or hash ("#") character is allowable in [HTTP scheme namespace] URIs according to the rules for URIs and XML namespaces.
- Colon (":") is expected in URN scheme namespaces
"Name construction" here refers to the lexical and syntactic structure of names, given the restricted character inventory. Motivations for the constraints include concerns for fidelity of interchange across file systems, minimizing the risks of common text-processing errors, usability (visual clarity), and other data QA. In other cases, arbitrary restriction of unbounded variablity serves the goal of simplicity through uniformity.
- Mixed case in names is generally allowed, including camel case
- Case-sensitive interpretation by the OASIS server and users is to be expected
- Creating two or more file/directory names differing ONLY in case (at the same hierarchical level) is deprecated; for example, in directory FOO, one should not create Bar and BAR
- Componentized filenames (e.g., IETF-style filenames, using hyphen-separated metadata factoids) are allowed but not required
- Filenames and directory names should neither begin nor end with a punctuation character (period, hyphen, underscore).
- Filenames and directory names should not contain multiple consecutive punctuation characters
- Filenames should not have two or more (identical) filename extensions (example: NOT foo.xsd.xsd or bar.pdf.pdf.
- Filenames should normally have a terminal PERIOD + filenameExtension unless the media/mime type is "text/plain" and the filename is one of a recognized set of extensionless names in common use (e.g.,
CATALOG/catalog, README, ChangeLog).
- Filename extensions should conform to industry best practice, matching well-known MIME Media Types for resources commonly shared in Web space open systems
- TC members must not create hidden files or filenames that compete with any reserved filenames used by the system/server or by OASIS staff for administrative purposes (e.g., index.html, index.htm, .htaccess)
- TC members should not use naming constructs that, in the judgment of the TC Administration, are likely to infringe, embarrass, confuse, shock, or otherwise fall outside the boundaries of social norm
- URIs for OASIS specifications should not contain the trademarked names of products, companies, and other corporate entities
- URIs for OASIS resources, as well as for HTTP scheme namespace URIs, should begin with the [exact, case-specific] 27 characters: http://docs.oasis-open.org/ unless specified otherwise by the OASIS TC Administration as an allowable exception
- Below the hierarchical level http://docs.oasis-open.org/[tcShortName]/, TCs are allowed relative freedom to create directories for their own use; all directories below tcShortName and their contents will be made publicly viewable via standard indexes and other navigation/browse facilities.
- Since each new published instance of a revised resource (e.g., prose specification, schema, DTD, WSDL, RDDL) requires a new URI, distinct filenames and/or path (directory) components must be used; while TCs are allowed to use versioning identifier components in filenames or paths, experience suggests that use of path components is less labor-intensive, less error-prone, and supports enhanced usability through directory index navigation.
- URI aliasing using strategies approved by the TC Administration and supported by OASIS IT should be for creating a persistent "Latest Version: " URI at which the most recent document version [of a certain type] may always be found; "Latest Version" URI aliases must be created for prose specifications, and may be created for supporting documents/files (e.g., XML schemas, WSDLs, DTDs, RDDLs), observing template models for the former and URI design requirements for the latter.
- URI aliasing using mechanisms other than those explicitly approved and for purposes other than "Latest Version: " URI requires consultation with the TC Administration
- Arbitrary URI aliasing (by any means) is forbidden, including, for example, unauthorized: (a) use of META-refresh elements (b) construction of URIs for canonical OASIS resources by using redirects from other Internet domains (e.g., http://tinyurl.com/, http://purl.oclc.org/)
- Assignment of URIs to resources is considered to be permanent except for a small class of approved exceptions, documented by the TC Administration (e.g., a "Latest version: " URI is associated with variable content). Thus: resources installed on the file system (instantiated as regular files, directories, symbolic links) and associated with published (viz., publicly visible) URIs may not be altered by deletion, overwriting, renaming/moving, or by any other action which severs the relationship between the URI and the resource. URIs, resources, and mappings from URIs to resources are permanent. This rule applies to secondary resources identified by fragment identifier.
- Any of the three common types of namespace names (URI references) are allowed: hash type, slash type, and simple (no-trailing-delimiter) type
- URN-based namespaces are also allowed, but HTTP scheme namespace URIs are to be preferred because their resolution is supported by standard, ubiquitous DNS+HTTP methods; TCs should be aware that OASIS has no current plans to implement the online resolution system for URNs referenced in IETF RFC 3121
- In order to avoid creating collision/confusion through semantic overloading at a point where
an HTTP schema XML Namespace URI could be mistaken for a regular directory URI, or vice versa, Namespace URIs and associated names (named properties, functions, dialects, faults, actions, other message types as non-information resources) are to use a reserved path structure containing the literal element /ns/. For any Type 1 or Type 3 namespace URI terminating in foo/ or foo (e.g., for http://docs.oasis-open.org/ns/<ShortName>/foo/ or http://docs.oasis-open.org/ns/<ShortName>/foo), no URIs should be created for information resources matching "*" in http://docs.oasis-open.org/ns/<ShortName>/foo/*. We will not create a folder/directory foo on the file system, nor locate any content in (an imaginary) directory foo/, because the path containing /ns/ is reserved for the declared namespace and related non-information resources.
- HTTP scheme namespace URIs must be rooted at the "docs.oasis-open.org" Internet domain
using one of the following two patterns with the /ns/ path
element, unless an alternative URI is approved by the TC Administration: (1)
http://docs.oasis-open.org/ns/<ShortName>/<Versioned-NS-String> OR (2)
http://docs.oasis-open.org/<ShortName>/ns/<Versioned-NS-String>. ShortName is the approved
short name for the TC or Member Section; Versioned-NS-String is a short string identifying a namespace using a versioning subcomponent. For example, given an imaginary TC short name 'ws-xx' and a versioned namespace string element 'WS-XX-20080115', a NS URI would be: http://docs.oasis-open.org/ns/ws-xx/WS-XX-20080115 OR http://docs.oasis-open.org/ws-xx/ns/WS-XX-20080115.
- HTTP scheme namespace URIs must resolve to some informative resource, ideally meeting the requirements for a (RDDL) namespace document; OASIS will supply a default namespace document if the TC designates/supplies no resource for resolution
- URIs intended for use as HTTP scheme URI namespace names should be formally identified by the TC (as early in the specification design process as possible) so that the OASIS TC Administration may check for possible naming collisions, approve the proposed resolution target resource [namespace document], and properly reserve the URI — including possibly reservation of (all) space below the hierarchical level of the candidate NS URI
- In accordance with Disposition of Names in an XML Namespace (edited by Norman Walsh for the W3C Technical Architecture Group - TAG), TCs should provide information about change policies for XML namespaces
- [Update 2006-09-30: see now OASIS Naming Guidelines: Metadata and Versioning]
- [Obsoleted as of 2006-09-30:] Most issues relating to versioning remain unresolved, for example, which terms to use for which work products: "version", "draft", "revision", "edition". [Note 2006-08-18: Guidelines for enumerating "versions", consistent with the specification templates, have been formulated provisionally and will be published here in the near future.]
Revised the guideline for construction of HTTP scheme NS URIs to use the explicit /ns/ path element.
Revised the Introduction statement to clarify that the Naming Guidelines are official, approved rules for use by OASIS TCs (no longer "draft" or "provisional").
Correct typo in section 'XML Namespace Design, Allocation, and Management': http://http://docs.oasis-open.org/tcName/path/foo -->> http://docs.oasis-open.org/tcName/path/foo. 2009-01-19.
Clarified the text and pseudo-syntax for preventing collision and semantic overloading, with an associated note in the commentary about information resources. 2009-08-01.