OASIS Naming Guidelines Part 1: Filenames, URIs, Namespaces

Rules

• 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

Rules

• 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

Rules

• 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.

Rules

• 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.]