This draft "Guidelines for Filenames, URIs, and Namespaces" presents the principal content from the document of 2006-06-30, limited to the statement of provisional rules. Commentary and examples are now provided, also unofficially, in "Commentary on Guidelines for Filenames, URIs, and Namespaces." Guidelines for the creation and use of metadata are being prepared as of 2006-07.
- 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": "All documents and other files produced by the TC, including specifications at any level of approval, must use the OASIS file naming scheme"
"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 filenames that compete with any reserved filenames used by the system/server or by OASIS staff for administrative purposes
- 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 publicly viewable via standard indexes and other navigation/browse facilities.
- URI aliasing using stragegies 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
- 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., "Latest version: " URI), so files may be revisioned but not overwritten. 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
- HTTP scheme namespace URIs should be rooted at http://docs.oasis-open.org/[TC-shortName]/ or (preferably) at [TC-shortName]/[productName]/ — or possibly otherwise, as negotiated with TC Administration
- HTTP scheme namespace URIs must resolve to some informative resource, ideally meeting the requirements for a 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
- Most issues relating to versioning remain unresolved, for example, which terms to use for which work products: "version", "draft", "revision", "edition"
ASIS document sections on metadata have been removed in this document, as metadata design has been targeted for work as a separate design effort
- Version 06: added note about the meaning of tcShortName
- Version 05: original posted version based upon 2006-06-30 combined document