OASIS Naming Guidelines Part 2: Metadata and Versioning

OASIS Naming Guidelines, In Two Parts

Part 1: Filenames, URIs, Namespaces
Part 2: Metadata and Versioning

Date: 2007-03-31
Editor: Robin Cover, with contributions from Mary McRae
Version: 03
This Version: http://docs.oasis-open.org/specGuidelines/namingGuidelines/metadata03.html
Latest Version: http://docs.oasis-open.org/specGuidelines/namingGuidelines/metadata.html
Previous Version: http://docs.oasis-open.org/specGuidelines/namingGuidelines/metadata02.html

Review Comments: send to robin@oasis-open.org. Significant issues/questions raised will be addressed in the document Notes.

Contents


Overview

Metadata information for OASIS specifications and related documents is considered of vital importance for consistent identification and reference, attribution, resource integrity checking, classification, describing resource relationships, searching, sorting, generation of reports, online access, and many other functions.

OASIS Technical Committees are asked to provide specification metadata as formally required by the OASIS Technical Committee Process (e.g., Section 2.8 TC Visibility and Section 2.18 Specification Quality) and by the OASIS Specification Templates. On occasion, TCs will also need to coordinate with the TC Administration to communicate a request for assignment of XML namespace, file system design, server configuration, product name/acronym, etc.

This document describes required metadata to be supplied by authors and editors when they are designing and authoring OASIS specifications. In the course of editing and publishing successive specification drafts, metadata representation is sometimes required, or required when applicable; in other contexts, it is optional. The presentation which follows is intended to clarify the rules for creation of metadata in all required usage contexts, and to describe optional strategies for representing additional metadata, at the discretion of individual Technical Committees.

In addition to metadata information stored within specifications, more complete externally stored metadata are used to describe specification production workflow events, additional resource relationships, subject classifications, etc. — including descriptive, structural, and administrative metadata. These additional specification-related metadata are created and maintained by OASIS Staff, designed (ultimately) for use in the document management system associated with the OASIS Open Library. They are not [as of 2006-09] of immediate concern to specification authors and editors.


Required Display Metadata for Prose Specifications

The most common usage context for specification metadata is the so-called title page of a prose specification — although the notion of page is not applicable in the case of (X)HTML documents or in specification-related files intended primarily for machines. Because the required descriptive metadata elements have a visible representation at the beginning of a specification, we refer to them as display metadata elements. Rules for construction and usage are presented below.

Title

The specification title should be composed from the specification name followed by the word "Version" and the version number.

Examples:

Version

Informally, we use the term "version" in casual reference to any instance (expression, manifestation) of a specification, or parts of a specification, having some genetic relationship to other instances in its lineage: "let's create a new version" or "an earlier version" In our metadata model, formally, a Version of an OASIS specification refers to a significant body of work that is chartered to take place (typically) over several months, often leading to the creation of an OASIS Standard. A Version is thus a "specification development stage [identified] for purposes of distinguishing levels of implementation and conformance by a public community of developers. An OASIS Standard is associated with a single version throughout its development and approval..." [Maler]

A specification Version is represented textually by a numeric string composed of digits [0-9] and period (".") corresponding to any of the following lexical models provided below (as examples), as may be relevant to the TC's work activity and preference for major/minor version notation. Formally, using parenthesis to indicate optionality and "#" to represent a digit, the allowable pattern is: #(#).#(#)(.#(#)). Use of any other pattern for version number must be negotiated with the TC Administration.

Examples:

1.0      #.#
1.01     #.##
1.2.1    #.#.#
10.1     ##.#

Stage

Each individual prose specification produced by a TC should be identified as belonging to one of the following levels of maturity, called stage, listed here in ascending order from lowest to highest:

Working Draft            (wd/WD)
Committee Draft          (cd/CD)
Public Review Draft      (pr/PR)
Committee Specification  (cs/CS)
OASIS Standard           (os/OS)

In order to identify the relative order of specification instances published throughout the specification production lifecycle, a numeric string composed of two digits [0-9] is to be associated with each successive instance. This value begins with '01' for each stage, and should increase monotonically [01 02 03 04 05]. The last stage (OASIS Standard) typically does not have the associated numeric string for stage, because an OASIS Standard represents the terminal stage, and is adequately represented by the Version. Note: the two-character abbreviations may be used in other usage contexts, as needed.

For a prose specification, intended principally for reading by a human, the display metadata are to be composed from the stage (label) and the numeric component, as exemplified in the following sequence pattern. This sequence, provided purely for illustration, does not imply that a specification should have exactly four Working Draft documents and three Committee Draft documents: a TC can issue as many drafts in any of these categories as needed. This example sequence also does not reflect document Revision notations, as explained below.

Examples:

Working Draft 01
Working Draft 02
Working Draft 03
Working Draft 04
Committee Draft 01
Committee Draft 02
Committee Draft 03
Public Review Draft 01
Public Review Draft 02
Committee Specification 01
Committee Specification 02

Revision

This metadata element is required when applicable.

A Revision represents a specification instance higher than Working Draft stage which has not been formally approved by TC vote. The title page of a prose specification instance should reflect a Revision metadata property if the document constitutes a CD-, PR-, or CS-level specification being published by the editorial team which has not been voted (for that particular instance) as a TC-approved document. Working Draft documents are issued consecutively, in each instance incrementing the WD number by one; they are not "revised" in the sense being considered here as a Revision.

The TC Process itself mandates that a new revision number be assigned to each specification instance when any change is made: "Any change made to a specification requires a new version or revision number, except for changes made to the title page and in the running footer noting the approval status and date, which must be made after the approval of the specification."

A Revision at the CD, PR, and CS stage is represented in display metadata using the word "Revision" followed by a numeric string composed of two digits [0-9], beginning with '01' and increasing monotonically.

For example: if a published "Working Draft 04" was balloted for approval by the TC as a Committee Draft, and if the vote to approve as CD passed, the specification should be re-issued with a change in the date (to reflect the date of the vote) and change of status (e.g., "Committee Draft 01") visible on the specification title page and in any running footers. Of course, the notion of a running footer pertains only to page-oriented formats, and not to XHTML or XML. As the TC's editorial team revises the approved document identified as "Committee Draft 01", creating successive instances of the specification for informal TC member review, each instance should each carry an incremented Revision identifier: "Revision 01", "Revision 02", "Revision 03", etc.

For the purposes of prose specification display metadata, the Revision identifier is always associated with the stage identifier, and never in isolation. This publication practice ensures that a reader may ascertain the relative status of the specification instance in terms of maturity and approved-ness, as well as its absolute order in the publication sequence. The examples illustrate how this should be expressed on the specification title "page". Note that for each initial instance of a numbered Committee Draft, Public Review Draft, and Committee Specification, the specification title "page" does not indicate a Revision: those initial instances are newly approved, and have not yet been "revised" in sense intended by Revision.

Example sequence:

Working Draft 01
Working Draft 02
Working Draft 03
Working Draft 04

   /* "Working Draft 04" is then approved by vote as a Committee Draft;
   the specification is issued as "Committee Draft 01" */

Committee Draft 01
Committee Draft 01, Revision 01
Committee Draft 01, Revision 02
Committee Draft 01, Revision 03
Committee Draft 01, Revision 04

   /* "Committee Draft 01, Revision 04" is then approved by vote as a
   Committee Draft; the specification is issued as "Committee Draft 02" */

Committee Draft 02
Committee Draft 02, Revision 01
Committee Draft 02, Revision 02
Committee Draft 02, Revision 03
Committee Draft 02, Revision 04

   /* "Committee Draft 02, Revision 04" is then approved by vote as a
   Committee Draft; the specification is issued as "Committee Draft 03" */

Committee Draft 03
Committee Draft 03, Revision 01
Committee Draft 03, Revision 02

   /* "Committee Draft 03, Revision 02" is then approved by vote as a Public
   Review Draft; the specification is issued as "Public Review Draft 01" */

Public Review Draft 01
Public Review Draft 01, Revision 01
Public Review Draft 01, Revision 02

   /* "Public Review Draft 01, Revision 02" is then approved by vote as a Committee
   Specification; the specification is issued as "Committee Specification 01" */

Committee Specification 01
Committee Specification 01, Revision 01
Committee Specification 01, Revision 02

Date

Each instance of a published prose specification should be assigned a Date matching either the calendar publication date or the date of approval by formal vote. In the case of a new (as yet unrevised) Committee Draft, Public Review Draft, Committee Specification, and OASIS Standard, the date is considered to be the date on which the TC or OASIS membership voted to approve the specification for advancement or as a Standard: from WD to CD, from CD to PR, from PR to CS, from CS to OS.

For prose specifications (in English), the date format for the display metadata on the title "page" is required to conform to the pattern DD Month YYYY. Note: In usage contexts intended principally for machines, the ISO 8601 extended calendar format should be used instead: YYYY-MM-DD.

Examples:

01 January 2007
11 September 2001

Specification URIs

Specification URIs Model Example. In the typical case, a prose specification title page must supply nine (or six) URIs at the Internet Domain docs.oasis-open.org conforming to the following example; the URIs for editable source (e.g., .doc, .odt) may be omitted if XHTML is used as the editable source:

This Version:
      http://docs.oasis-open.org/exampleTC/ourSpec2.0/cd3/spec05.html
      http://docs.oasis-open.org/exampleTC/ourSpec2.0/cd3/spec05.pdf
      http://docs.oasis-open.org/exampleTC/ourSpec2.0/cd3/spec05.doc
Previous Version:
      http://docs.oasis-open.org/exampleTC/ourSpec2.0/cd3/spec04.html
      http://docs.oasis-open.org/exampleTC/ourSpec2.0/cd3/spec04.pdf
      http://docs.oasis-open.org/exampleTC/ourSpec2.0/cd3/spec04.doc
Latest Version:
      http://docs.oasis-open.org/exampleTC/ourSpec2.0/spec.html
      http://docs.oasis-open.org/exampleTC/ourSpec2.0/spec.pdf
      http://docs.oasis-open.org/exampleTC/ourSpec2.0/spec.doc

This section ("Specification URIs") provides guidance on the design of URIs for prose specifications; a separate section defines rules for the creation of "Latest Version" URIs for Schemas, WSDLs, RDDLs, and Other Specification Components.

In the context of the Web, the single most important metadata datum relating to a resource is a persistent, unique resource identifier. For resources like prose specifications that have a textual representation, the URI may support resource location and access in addition to identification, as specified in the relevant RFC: "A URI can be further classified as a locator, a name, or both... An individual scheme does not have to be classified as being just one of name or locator. Instances of URIs from any given scheme may have the characteristics of names or locators or both.."

Following a convention used commonly in other standards organizations, e.g., The World Wide Web Consortium (W3C), the Web Services Interoperability Organization (WS-I), The Unicode Consortium, the The Dublin Core Metadata Initiative (DCMI), etc., OASIS requires that specifications present three general kinds URIs as display metadata, as explained below: This Version, Previous Version, and Latest Version. Additionally, because some classes of OASIS specification publication represent instances not yet formally approved by a Technical Committee vote (Working Drafts, Revisions), URIs should be made available for Latest Approved Version and Previous Approved Version in applicable publication situations.

In the OASIS context, when applicable, published specifications are expected to convey specification URI display metadata of five types. URIs for This Version, Previous Version [may have the value 'NA'], and Latest Version are always required.

Example for "Working Draft 01"

This is a fictitious example, designed simply to illustrate an explicit null value for Previous Version when an initial Working Draft (Stage: Working Draft 01) is released. The example is not intended to show, e.g., that the component v2 should occur in the path, or that a filename for a Working Draft 01 release should contain the literal substring -wd01. Most matters of filename design and URI design are left to the discretion of TCs. However, use of path components in URIs is encouraged, as in /wd01/ below: this strategy allows use of the same filenames as a specification progresses through several stages (WD/CD/PR/CS) and revisions. See some real examples below.

Specification URIs:

This Version:
http:/docs.oasis-open.org/exampleTC/fruitMarkup/v2/wd01/fruit.html
http:/docs.oasis-open.org/exampleTC/fruitMarkup/v2/wd01/fruit.pdf
Previous Version:
[NA]
Latest Version:
http://docs.oasis-open.org/exampleTC/fruitMarkup/v2/fruit.html
http://docs.oasis-open.org/exampleTC/fruitMarkup/v2/fruit.pdf

Example for "Working Draft 02"

This is a fictitious example, designed simply to illustrate citation of the required XHTML and PDF format URIs. It is not intended to imply, e.g., that a filename should necessarily encode a date or numeric version component. Most matters of filename design and URI design are left to the discretion of TCs. This example also shows how a path and filename for the Latest Version URIs may be shortened, omitting unnecessary components.

Specification URIs:

This Version:
http://docs.oasis-open.org/exampleTC/nutMarkup/2.1/wd2/nut-200708.html
http://docs.oasis-open.org/exampleTC/nutMarkup/2.1/wd2/nut-200708.pdf
Previous Version:
http://docs.oasis-open.org/exampleTC/nutMarkup/2.1/wd1/nut-200705.html
http://docs.oasis-open.org/exampleTC/nutMarkup/2.1/wd1/nut-200705.pdf
Latest Version:
http://docs.oasis-open.org/exampleTC/nutMarkup/2.1/nut.html
http://docs.oasis-open.org/exampleTC/nutMarkup/2.1/nut.pdf

Example for Version 4.0, "Public Review Draft 03, Revision 05"

This is a fictitious example, designed simply to illustrate the use of Latest Approved Version URIs using a path component (directory) named approved. This example also shows how a path component might be used to represent the stage and revision in the format "stageLabel + stageEnumerator + revisionEnumerator"; viz., below, pr3.5 could be used to signify "Public Review Draft [pr] 03 Revision 05". This example is not intended to imply, e.g., that the path/filename design here illustrated MUST be used in any similar situation. Most matters of filename design and URI design are left to the discretion of TCs.

Specification URIs:

This Version:
http://docs.oasis-open.org/exampleTC/nutMarkup/4.0/pr3.5/nut.html
http://docs.oasis-open.org/exampleTC/nutMarkup/4.0/pr3.5/nut.pdf
Previous Version:
http://docs.oasis-open.org/exampleTC/nutMarkup/4.0/pr3.4/nut.html
http://docs.oasis-open.org/exampleTC/nutMarkup/4.0/pr3.4/nut.pdf
Latest Version:
http://docs.oasis-open.org/exampleTC/nutMarkup/4.0/nut.html
http://docs.oasis-open.org/exampleTC/nutMarkup/4.0/nut.pdf
Latest Approved Version:
http://docs.oasis-open.org/exampleTC/nutMarkup/4.0/approved/nut.html
http://docs.oasis-open.org/exampleTC/nutMarkup/4.0/approved/nut.pdf

Example for "Public Review Draft 02, Revision 03"

This is a fictitious example, designed simply to illustrate the use of metadata elements in filenames — though no agreement exists that doing so is a good idea. The disadvantage is that for every new release stage (WD/CD/PR/CS/OS) and revision, filenames must be changed: when specification files are interlocked through heavy cross-referenced, maintaining correct references through direct editing becomes labor intensive, and is error-prone. However, some editorial teams may be convinced that it is a good idea to construct a filename using metadata to represent the specification name, version, document type, stage, revision, language, etc. See the document Artifact Standard Identification Scheme for Metadata (ASIS), but note that the proposed prescription for componentized filenames of the shape product-productVersion-artifactType-stage-revision-language.form was not adopted by OASIS. Most matters of filename design and URI design are left to the discretion of TCs.

Specification URIs:

This Version:
http://docs.oasis-open.org/exampleTC/nutMarkup/v2/nut2.0-pr02-rev03.html
http://docs.oasis-open.org/exampleTC/nutMarkup/v2/nut2.0-pr02-rev03.pdf
Previous Version:
http://docs.oasis-open.org/exampleTC/nutMarkup/v2/nut2.0-pr02-rev02.html
http://docs.oasis-open.org/exampleTC/nutMarkup/v2/nut2.0-pr02-rev02.pdf
Latest Version:
http://docs.oasis-open.org/exampleTC/nutMarkup/v2/nut2.html
http://docs.oasis-open.org/exampleTC/nutMarkup/v2/nut2.pdf
Latest Approved Version:
http://docs.oasis-open.org/exampleTC/nutMarkup/v2/approved/nut2.html
http://docs.oasis-open.org/exampleTC/nutMarkup/v2/approved/nut2.pdf

Representation specification URIs for multiple formats:

The OASIS TC Process document grants privilege to the XHTML and PDF specification formats, both of which are required:

All TC-approved versions of documents (i.e., Committee Drafts, Public Review Drafts, and Committee Specifications) must be submitted to the TC's document repository in the editable source, XHTML, and PDF formats. Any links published by the TC shall be to the XHTML and/or PDF formats stored in the TC's document repository.

The complete examples above therefore illustrate how specification URIs should be created for the specification title page, including both the XHTML and PDF formats. If the specification is at level "Working Draft 01", a "Previous Version" URI value of 'NA' should be listed, unless OASIS-managed URIs are available for original technical material contributed to the TC as a basis for new work.

If the TC editorial team wishes to reference other important specification URIs for any instance (e.g., a complete ZIP package, diff-marked versions, source word-processor formats, specification XML [DocBook, DITA], PostScript, etc.), these URIs should be cited in the initial document section(s) or in an appendix.

How to assign Specification URIs:

Note: The examples in this listing are NOT requirements, recommendations, or even suggestions.

1.  http://docs.oasis-open.org/health/virus-ml/virusML-1.html
2.  http://docs.oasis-open.org/health/virus-ml/virusML-1.pdf
3.  http://docs.oasis-open.org/health/virus-ml/virusML-1.zip
4.  http://docs.oasis-open.org/health/virus-ml/approved/virusML-1.html
5.  http://docs.oasis-open.org/health/virus-ml/approved/virusML-1.pdf
6.  http://docs.oasis-open.org/health/virus-ml/approved/virusML-1.zip
7.  http://docs.oasis-open.org/health/virus-ml/1.0/wd01/*
8.  http://docs.oasis-open.org/health/virus-ml/1.0/wd02/*
9.  http://docs.oasis-open.org/health/virus-ml/1.0/wd03/*
10. http://docs.oasis-open.org/health/virus-ml/1.0/wd04/*
11. http://docs.oasis-open.org/health/virus-ml/1.0/wd05/*
12. http://docs.oasis-open.org/health/virus-ml/1.0/cd01/*
13. http://docs.oasis-open.org/health/virus-ml/1.0/cd01/r1/*
14. http://docs.oasis-open.org/health/virus-ml/1.0/cd01/r2/*
15. http://docs.oasis-open.org/health/virus-ml/1.0/cd01/r3/*
16. http://docs.oasis-open.org/health/virus-ml/1.0/cd01/r4/*
17. http://docs.oasis-open.org/health/virus-ml/1.0/cd02/*
18. http://docs.oasis-open.org/health/virus-ml/1.0/cd02/r1/*
19. http://docs.oasis-open.org/health/virus-ml/1.0/cd02/r2*
20. http://docs.oasis-open.org/health/virus-ml/1.0/cd03/*
21. http://docs.oasis-open.org/health/virus-ml/1.0/pr01/*
22. http://docs.oasis-open.org/health/virus-ml/1.0/pr01/r1/*
23. http://docs.oasis-open.org/health/virus-ml/1.0/cs01/*
24. http://docs.oasis-open.org/health/virus-ml/ns/200605
25. http://docs.oasis-open.org/health/virus-ml/ns/200701
26. http://docs.oasis-open.org/health/virus-ml/ns/200707
27. http://docs.oasis-open.org/health/virus-ml/ns/

Any number of design strategies may be used at the level of the file system for TC's web site area in the OASIS Open Library. For example, a TC might use a directory path element named "latest", and (within the above fictitious example), use the following URIs for every instance of the XHTML/PDF format, where the two URIs would match, successively through time, every version-specific (This Version) URI as the specification revisions are released.:

http://docs.oasis-open.org/health/virus-ml/1.0/latest/virus-ml.html
http://docs.oasis-open.org/health/virus-ml/1.0/latest/virus-ml.pdf

Further, see how the OASIS DocBook TC organizes the W3C XML Schemas, the RELAX NG Grammars, and the prose specifications in separate directory trees.

Mapping from version-specific (This Version) to version-agnostic (Latest Version) is specified on a case-by-case basis, per the wishes of the TC. As of 2006-09-22, OASIS IT staff had installed a prototype implementation to support versatile server configuration settings that establish mappings between arbitrary URIs and system resources represented by files and directories/paths. Based upon the results of testing of this implementation or its successor, OASIS Staff will make recommendations to TCs about a set of best-practice alternatives for constructing "Latest Version" URIs, and methods for ensuring that the server configuration is always updated to reflect the TC's declared mappings. In the interim, TCs should consult with the TC Administration to negotiate agreement about creating URI aliases and other mappings.

Technical Committee

The name of the OASIS Technical Committee responsible for the development of a published specification should be represented as display metadata on the specification title "page". For this purpose, the official name of each Technical Committee is listed in the document OASIS Committees by Name. The name of the TC should encode an HTTP scheme URI reference (hyperlink) to the TC Public Home Page, as modeled in the examples below.

Examples:

Chair

At the time a TC issues a new specification instance, one or more members of the TC may have the role of Chair. Any current Chair or Co-Chair should be represented on the specification title "page", listing the person's name, and (as appropriate) an institutional affiliation, and personal email address. If a Chair is an organizational member, the corporate affiliation may be noted following the personal name; if the Chair is an individual or associate members, no affiliation may be displayed. In other cases, please consult with the OASIS TC Administration as to conventions for inclusion of institutional affiliation and email address.

Examples:

Chairs:
    Diane Jordan, IBM <drj@us.ibm.com>
    John Evdemon, Microsoft <John.Evdemon@microsoft.com>

Chair:
    Rich Thompson, IBM Corporation <richt2@us.ibm.com>

Editor

At the time a TC issues a new specification instance, one or more members of the TC may be serving as an Editor. Any current Editor should be represented on the specification title "page", listing the person's name, and (as appropriate) an institutional affiliation, and personal email address. If an Editor is an organizational member, the corporate affiliation may be noted following the personal name; if an Editor is an individual or associate members, no affiliation may be displayed. In other cases, please consult with the OASIS TC Administration as to conventions for inclusion of institutional affiliation and email address. Note: a complete list of TC participants is to be included in a prose specification, according to TC Process rules; such attribution is typically made in a document Appendix labeled "Acknowledgements."

Example:

Editors:
    Doug Davis, IBM <dug@us.ibm.com>
    Anish Karmarkar, Oracle <Anish.Karmarkar@oracle.com>
    Gilbert Pilz, BEA <gpilz@bea.com>
    Steve Winkler, SAP <steve.winkler@sap.com>
    Ümit Yalçinalp, <umit.yalcinalp@sap.com>

Related Work

This metadata element is required when applicable, otherwise optional (always allowed).

Within a prose specification title "page", TC editors should supply the title and applicable URI for any other resource closely associated with the specification, where reference to the related resource is deemed essential or strongly motivated. In most cases, the TC editors are to make a judgment, necessarily subjective, as to whether a Related Work reference would be of significant benefit to the human reader.

Under one particular condition, Related Work is a required display metadata element, namely: when a second Version of a specification/standard is being developed. For example, specification instances being published as part of the Security Assertion Markup Language (SAML) Version 2.0 production life cycle should reference SAML Version 1.1 and SAML Version 1.0 as Related Work resources (see example below). Similarly, published instances of OpenDocument v1.1, draft and final, should cite the Open Document Format for Office Applications (OpenDocument) Version 1.0 OASIS Standard as a Related Work.

Example:

Related Work:
   This specification is related to:
      Security Assertion Markup Language (SAML) v1.1   http://www.oasis-open.org/specs/index.php#samlv1.1
      Security Assertion Markup Language (SAML) v1.0   http://www.oasis-open.org/specs/index.php#samlv1.0

Another condition under which Related Work metadata should be supplied is when the specification being published replaces or supercedes another specification. In most cases, this rule would come into play when one OASIS-owned specification logically supersedes another (e.g., withdrawn, deprecated, or otherwise obsoleted) OASIS-owned specification. In more rare cases, it may be important to use a Related Work reference to signify that an OASIS specification supersedes one produced by another standards organization. In both cases, TC editors should consult with the OASIS TC Administration about this supersedes/replaces Related Work metadata element.

When considering candidate resources for possible reference as Related Work, account should taken as to whether a resource is more properly identified as a display metadata item required or recommended for citation elsewhere on the specification title "page".

Informally (not with an intent to formally implement DCMI metadata models), OASIS TC editors may wish to study the collection of Dublin Core Metadata Initiative (DCMI) terms defined as element refinements of DCMI relation [label Relation] — as these may prompt ideas for Related Work candidate references. In DCMI, a relation stores "a reference to a related resource... Recommended best practice is to reference the resource by means of a string or number conforming to a formal identification system." Here are some of the element refinements build from DCMI relation, usually reciprocal:

hasFormat
The described resource pre-existed the referenced resource, which is essentially the same intellectual content presented in another format
isFormatOf
The described resource is the same intellectual content of the referenced resource, but presented in another format
hasPart
The described resource includes the referenced resource either physically or logically
isPartOf
The described resource is a physical or logical part of the referenced resource
hasVersion
The described resource has a version, edition, or adaptation, namely, the referenced resource
isVersionOf
The described resource is a version, edition, or adaptation of the referenced resource. Changes in version imply substantive changes in content rather than differences in format
isReferencedBy
The described resource is referenced, cited, or otherwise pointed to by the referenced resource
references
The described resource references, cites, or otherwise points to the referenced resource
isReplacedBy
The described resource is supplanted, displaced, or superseded by the referenced resource
replaces
The described resource supplants, displaces, or supersedes the referenced resource
isRequiredBy
The described resource is required by the referenced resource, either physically or logically
requires
The described resource requires the referenced resource to support its function, delivery, or coherence of content
conformsTo
A reference to an established standard to which the resource conforms

Declared XML Namespace

This metadata element is required when applicable.

Following W3C's recommendation for "good practice on namespace adoption", a prose specification may describe the use of one or more XML namespaces declared in schemas associated with the specification. [NB: Specifications sometimes also describe use of related XML namespaces (recommended prefixes) not defined locally; such related XML namespaces are not of interest here.] When XML namespaces are declared/described in schemas and prose, these namespaces should be referenced as display metadata on the title "page" of the prose specification.

As clarified elsewhere in the Naming Guidelines document, HTTP scheme namespace URIs declared/defined by OASIS TCs must resolve to some informative resource, ideally meeting the requirements for a namespace document which documents that namespace, and preferably a RDDL namespace document. OASIS will supply a default namespace document if the TC designates/supplies no resource for resolution.

The label for use on the specification title "page" is Declared XML Namespace (exactly one) or Declared XML Namespaces (two or more). Illustration (without regard for complete title page formatting/style):

Declared XML Namespaces:
    http://docs.oasis-open.org/wsbpel/2.0/plnktype
    http://docs.oasis-open.org/wsbpel/2.0/process/abstract

Other examples:

Abstract

A well-written abstract for a specification plays an important role as descriptive metadata. TC editors are required to provide a written abstract for OASIS prose specifications. They are encouraged to consider how a precise, carefully crafted summary might be re-used in various contexts to help generalists, journalists, and specialists in related technical domains understand the specification's key technology contribution. Given the large number of technical specifications available and the effects of knowledge specialization, the abstract plays a key role in spec adoption.

Example:

Abstract:
[not yet written... in search of award-winning candidates]


"Latest Version" URIs for Schemas, WSDLs, RDDLs, and Other Specification Components

This section describes the design concerns and requirements for the creation and use of "Latest Version" URIs for files and documents other than the typical prose specification (e.g., XML schemas, XML sample instance files, DTDs, WSDL files, RDDL namespace documents).

As described above for Prose Specification URIs a "Latest Version" URI is a locator: it is defined as a URI alias serving as a bookmarkable, version-agnostic, generic URI which is always associated with the latest/current instance of a resource, thus having a changing referent; it serves to directly locate each successive published instance of resource which is being revised as the specification progresses through various stages (WD/CD/PR/CS/OS) and revisions.

Use of a "Latest Version" URI alias has two principal advantages: it allows a human or agent to fetch some representation of the resource without knowing the version-specific URI; it also can be crafted to contain fewer characters than a version-specific URI, as illustrated in the the Example for "Working Draft 02".

Three important requirements govern the creation and use of a "Latest Version" URI:

  1. Clear designation of a "Latest Version" URI as such. It is vital that users can readily ascertain which URI serves as a URI alias ("Latest Version") "locator" for changing content versus the URI which serves as the static identifier permanently mapped to an unchanging resource with fixed content. The semantics for "This Version" (version-specific) and "Latest Version" (generic, version-agnostic) URIs are quite distinct: it is imperative that users accessing a resource or creating a citation to a resource know which is which. As explained below, mistakenly referencing a "Latest Version" URI often creates data errors.

    In the case of a prose specification that has a title page, informing the user about the two different URI types is not a problem: the Specification URI labels clearly identify "Latest" and "This." In some cases it is desirable to use "Latest Version" URIs with ancillary files which lack title pages: XML schemas, XML sample instance documents, DTDs, WSDL files, RDDL namespace documents, etc. When "latest" URI aliases are created for these resource types, TC editors must take special care to distinguish between the two in such fashion that users are adequately informed. Candidate locations in which these two URI variant types may be described according to their particular sementics and indended usage:

    • the associated prose specification, using a dedicated document section
    • comment sections at the beginning of a machine-readable file
    • special designation and labeling in a (RDDL) namespace documents

  2. Simultaneous creation of version-specific and version-agnostic URIs. It is vital that a version-specific URI always be provided for reference whenever a version-agnostic (latest version URI alias) is published. More particularly, a version-specific URI must be created at the same time as a URI which is intended to serve as a "Latest Version" URI, and the proper aliasing mechanism must be established at the outset. It does not work: (a) to use URI-1 as "the" resource URI at stage one, then declare that URI-1 is the "Latest Version" URI when the resource is revised and moves to stage two; (b) more generally, to retrospectively create a version-specific URI for a resource at the end of its lifecycle function as the latest instance of the resource. If a version-specific URI is unavailable during the time of a resource's function as "current/latest", external references made to the resource at the URI alias (the only one available) will predicably result in data errors when the resource content is updated.

    Analogous to the URI design pattern modeled for a prose specification (Example for "Working Draft 02"), a version-specific URI for a schema/wsdl/RDDL would typically reflect versioning elements in the path and/or filename; a version-agnostic (latest) URI for a schema/wsdl/RDDL would typically contain fewer characters. Example: a version specific URI for a schema might be http://docs.oasis-open.org/exampleTC/nutMarkup/2.1/wd2/nut-200708.xsd while the corresponding version-agnostic (latest) URI might be http://docs.oasis-open.org/exampleTC/nutMarkup/2.1/nut.xsd

  3. Citation practice which supports the correct semantic and choice of URI. A critical concern underlying requirements #1 and #2 above is ensuring that users of URIs understand the different semantics so that they can access and cite resources using the correct URI. If a user wanted to make general reference to an in-progress XML schema being produced by a TC, indifferent to its exact content or date of production (today, next month, next year), then URI reference by the "Latest Version" URI might make sense; the citation text and context should make it clear to a reader that the reference is to the "Latest Version".

    In a larger number of use cases, and in any case where reference is made to particular content in a schema or pother resource, it would be dangerous to cite the "Latest Version" URI. When creating a citation to any prose specification or schema/WSDL file component by URI reference (within common prose or in a specification References section; in plain text or hypertext), it is vital to use citation text and URIs which respect the different semantics of "This Version" vs. "any current/future version whatsoever". In the latter, content is changing, and the referent is a moving target. If the different semantics are not observed, one predictably creates data errors, broken links, false assertions, violations of referential integrity, and generally incorrect, inaccurate, misleading references. In particular, indiscriminate use of a "Latest Version" URI creates data problems. Please see the note below for a worked example illustrating this concern for proper citation practice.

Optional Embedded Metadata for Prose Specifications

OASIS TCs are at liberty to include embedded metadata in any of the prose specification formats (e.g., XHTML, PDF, various word-processor formats) using any available support facilities, provided that such metadata information is accurate. Any such embedded metadata corresponding to information presented in the required (title page) display metadata MUST match the display metadata information content.

For such purposes, it is advisable to use the same terms/labels in embedded metadata contexts as are defined for use (above) as display metadata labels. On the other hand, since we are aware of no external applications which will make use of such embedded metadata, and similarly, since OASIS Staff has no plans to do so, any such effort should be considered a TC's private affair.

XHTML authoring templates and guidelines for Document Template Usage prepared by OASIS Staff in the 2004-2005 timeframe specified a few required metadata elements for use in embedded contexts; see for example XHTML Template with Legacy IPR Notices. The use of these META markup elements is no longer required as of 2006-09-29.

Should use cases and additional requirements come to light which motivate the systematic and consistent inclusion of machine-readable metadata in prose specifications, OASIS will formalize guidelines for doing so; TCs may or may not be required to assist in that task. We believe that the more efficient and effective path will lie in the direction of dedicated "specification XML" vocabulary for standards production. This strategy will support not only native structured metadata in documents, but superior design opportunities for data normalization and for machine processing — XML-based data extraction, far superior to including markup-based metadata in XHTML (semi-structured, or awkwardly "flat-structured").

For TCs interested in approved strategies for markup-based metadata, guidelines for including metadata in XHTML/XML are presented in several publications prepared by the Dublin Core Metadata Initiative; see the list of DCMI Encoding Guidelines documents.

OASIS Staff at this time [2006-09] makes no recommendations about the possible risks and benefits of including embedded metadata, other than noting that "more information is usually better that less information" in the event that a document goes stray: someone coming into possession of a document with uncertain pedigree may benefit from any additional metadata included through use of a software application or included manually by the specification editors. On the other hand, we believe that the required display metadata should be adequate for all typical use cases involving a human reader.

Specification metadata appropriate for use in the OASIS document management system (as part of the OASIS Open Library) will be created and maintained by OASIS Staff in various representations and storage formats. It is likely that some controlled vocabulary schemes and encoding methods like those recommended by DCMI will be identified and used within the OASIS setting at some future time. Some of the research and recommendations presented in the 30-January-2006 document Artifact Standard Identification Scheme for Metadata 1.0 produced by the OASIS TAB will be incorporated into these designs.

It is sometimes claimed that embedding high-quality metadata in (X)HTML documents will improve the chances of users finding such documents through the agency of web search engines. We have found little evidence to support this claim, and substantial evidence suggesting it is not true, or of negligible value as a strategy. Since assertions made in "META" empty elements (for example) cannot be trusted [see Metacrap], the popular public search engines (apparently, typically) do not index such content, nor do they otherwise attempt to weigh it independently as reliable information. Google's "Quality guidelines: basic principles" FAQ includes the following advice: "Make pages for users, not for search engines... Avoid tricks intended to improve search engine rankings. A good rule of thumb is whether you'd feel comfortable explaining what you've done to a website that competes with you. Another useful test is to ask, 'Does this help my users? Would I do this if search engines didn't exist?'..."


Other Required Data in Prose Specifications

The OASIS specification authoring templates require the inclusion of information on a specification title page that has not been characterized in this as Required Display Metadata. Determining apriori that an information item is data vs. metadata is of course largely, if not entirely, arbitrary. Any datum may be either data or metadata depending upon a perspective :"one person's metadata is always another person's data."

The following information is required to be included (when applicable) in either the "Status" section or "Notices", as presented in the model templates:


Embedded Metadata for Ancillary Files

The TC process document makes reference to specification-related files other than "documents" which require careful treatment as OASIS resources. These may include [machine-processable] schemas and XML instances or other parts of a specification made available separately in their own plain text files.

The metadata elements identified for inclusion on a prose specification title "page" may also be used in specification-related files intended primarily for machines, but there is no requirement to do so, other than to include the OASIS copyright notice — for example, Copyright (c) OASIS Open 2006.

While OASIS levies no requirement on TCs to embed (unstructured) metadata information in XML schema files, WSDLs, DTDs, Catalogs (etc), there should be no harm in doing so, provided that the metadata information is accurate. Including incorrect metadata may be worse than including none at all.

The inclusion of formally structured metadata into machine-readable files is deprecated: only such mechanisms directly supported by the syntax specification for a schema (for example) should be used. Otherwise, freeform textual material should be used, following the normal conventions for informal comment.


Metadata in Namespace Documents

Instructions above provide guidance on inclusion of display metadata in prose specification formats and embedded metadata in a range of document format types, including files intended for machines.

TCs are also encouraged to consider the advantages of creating and maintaining specification metadata in namespace documents, which live quite naturally "at the end" of the specification namespace URI, and provide a convenient locus for updated information about resources related to an XML namespace. A namespace is a URI reference; an HTTP scheme namespace URI, when dereferenced, should resolve to the namespace document. The Resource Directory Description Language (RDDL) namespace document, as with other namespace documents, is designed to be useful to both machines and humans. The Web Architecture "good practice" statement for namespace documents recommends that the owner of an XML namespace name SHOULD make available material intended for people to read and material optimized for software agents in order to meet the needs of those who will use the namespace vocabulary."

RDDL documents are easily edited, and can provide a stack of information about specifications related to that namespace, as well as to closely related namespaces. The RDDL may also provide an excellent metadata document which identifies and describes the key constituent resources which make up a multi-part specification (e.g. a core document supported by several profiles; a specification in two or more "parts"; a specification having several key XML schemas and WSDLs).

The OASIS Templates and Guidelines document provides brief description of a RDDL namespace document as used in the OASIS context, including a draft RDDL Template. The RDDL document should include reference to the namespace URI, the name of the associated OASIS Technical Committee, URI reference (hyperlink) to the TC Public Page, and version-specific URI references to the key resources related to the namespace (prose specification, schemas, WSDLs, etc.).

Example RDDL namespace documents for inspection:


Appendices

Technical Committee Process: Specification Quality

From the OASIS Technical Committee Process document (approved January 25, 2007 and effective as of March 01, 2007), with some added emphasis and links to enhance usability in this citation context:

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, 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. The name of any specification may not include any trademarks or service marks not owned by OASIS.

A specification that is approved by the TC at the Public Review Draft, Committee Specification or OASIS Standard level must include a separate section, listing a set of numbered conformance clauses, to which any implementation of the specification must adhere in order to claim conformance to the specification (or any optional portion thereof). [*Effective " as of 1 June 2007", per the Note to Section 1(dd)]

A specification that is approved by the TC at any level must include a list of people who participated in the development of the specification. This list shall be initially compiled by the Chair, and any Member of the TC may add or remove their names from the list by request.

A specification that is approved by the TC at any level must clearly indicate whether each reference in the specification to a document or artifact is a Normative Reference.

Editable formats of all versions of TC documents must be submitted to the TC's document repository. TC Working Drafts may be in any format (i.e. produced by any application). All TC-approved versions of documents (i.e. Committee Drafts, Public Review Drafts, and Committee Specifications) must be submitted to the TC's document repository in the editable source, XHTML, and PDF formats. Any links published by the TC shall be to the XHTML and/or PDF formats stored using repositories and domain names owned by OASIS and as approved by the TC Administrator.

All schema and XML instances, whether by inclusion or by reference, including fragments of such, must be well formed. All expressions must be valid. Each schema and XML instance that is part of the specification must be submitted in its own separate plain text file.

A specification may be composed of any number of files of different types, though any such multi-part specification must have a single specification name and version number. Irrespective of the number and status of the constituent parts, the specification as a whole must be approved by a single TC ballot. Any change made to a specification requires a new version or revision number, except for changes made to the title page and in the running footer noting the approval status and date, which must be made after the approval of the specification.


Examples: Common Conventions for Publishing Specification URIs

This appendix provides illustrative examples of common practice at standards organizations similar to OASIS on the topic of presenting specification URIs on a specification title page, and on the use of Latest Version, Previous Version, and This Version URIs. Examples are listed from specifications published by:

Unicode Consortium Examples

See also other examples listed in Unicode Technical Reports.

Unicode Standard Annex #34
Unicode Named Character Sequences

Version 4.1.0
Authors Ken Whistler
Date 2005-03-25
This Version http://www.unicode.org/reports/tr34/tr34-3.html
Previous Version http://www.unicode.org/reports/tr34/tr34-1.html
Latest Version http://www.unicode.org/reports/tr34/
Revision 3

Unicode Technical Standard #35
Locale Data Markup Language (LDML)

Version 1.4
Authors Mark Davis (mark.davis@google.com)
Date 2006-07-16
This Version http://unicode.org/reports/tr35/tr35-6.html
Previous Version http://unicode.org/reports/tr35/tr35-5.html
Latest Version http://unicode.org/reports/tr35/
Corrigenda http://unicode.org/cldr/corrigenda.html
Latest Working Draft http://unicode.org/draft/reports/tr35/tr35.html
Namespace: http://unicode.org/cldr/
DTDs: http://unicode.org/cldr/dtd/1.4/ldml.dtd
http://unicode.org/cldr/dtd/1.4/ldmlSupplemental.dtd
Revision 6

W3C Examples

See also other examples from the listing of W3C Technical Reports and Publications.

Web Services Policy 1.5 - Framework
W3C Working Draft 27 September 2006

This version:
http://www.w3.org/TR/2006/WD-ws-policy-20060927
Latest version:
http://www.w3.org/TR/ws-policy
Previous versions:
http://www.w3.org/TR/2006/WD-ws-policy-20060731
Editors:
Asir S Vedamuthu, Microsoft Corporation
David Orchard, BEA Systems, Inc.
Maryann Hondo, IBM Corporation
Toufic Boubez, Layer 7 Technologies
Prasad Yendluri, webMethods, Inc.

This document is also available in these non-normative formats: PDF, PostScript, XML, and plain text.


XHTML 1.0 The Extensible HyperText Markup Language (Second Edition)
A Reformulation of HTML 4 in XML 1.0
W3C Recommendation 26 January 2000, Revised 1 August 2002

This version:
http://www.w3.org/TR/2002/REC-xhtml1-20020801
Latest version:
http://www.w3.org/TR/xhtml1
Previous version:
http://www.w3.org/TR/2000/REC-xhtml1-20000126
Diff-marked version:
http://www.w3.org/TR/2002/REC-xhtml1-20020801/xhtml1-diff.html
Authors:
See acknowledgments.

Please refer to the errata for this document, which may include some normative corrections. See also translations.
This document is also available in these non-normative formats: Multi-part XHTML file, PostScript version, PDF version, ZIP archive, and Gzip'd TAR archive.

WS-I Examples

See also other examples listed in the WS-I Working Group Deliverables Index.

Basic Security Profile Version 1.0
Working Group Draft
2006-08-17

This version:
http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0-2006-08-17.html
Latest version:
http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html


Basic Profile Version 1.1
Final Material
2006-04-10

This version:
http://www.ws-i.org/Profiles/BasicProfile-1.1-2006-04-10.html
Latest version:
http://www.ws-i.org/Profiles/BasicProfile-1.1.html
Errata for this Version:
http://www.ws-i.org/Profiles/BasicProfile-1.1-errata-2006-04-10.html

DCMI Examples

See also other examples from the listing of DCMI Documents.

DCMI Type Vocabulary

Title: DCMI Type Vocabulary
Creator: DCMI Usage Board
Identifier: http://dublincore.org/documents/2006/08/28/dcmi-type-vocabulary/
Date Issued: 2006-08-28
Latest Version: http://dublincore.org/documents/dcmi-type-vocabulary/
Replaces: http://dublincore.org/documents/2004/06/14/dcmi-type-vocabulary/
Translations: http://dublincore.org/resources/translations/
Document Status: This is a DCMI Recommendation.
Date Valid: 2006-08-28


DCMI Metadata Terms

Title: DCMI Metadata Terms
Creator: DCMI Usage Board
Identifier: http://dublincore.org/documents/2006/08/28/dcmi-terms/
Date Issued: 2006-08-28
Latest Version: http://dublincore.org/documents/dcmi-terms/
Replaces: http://dublincore.org/documents/2005/06/13/dcmi-terms/
Translations: http://dublincore.org/resources/translations/
Document Status: This is a DCMI Recommendation.
Date Valid: 2006-08-28

Bibliographic References

This collection of references supplements the citation list provided in the Guidelines for Filenames, URIs, Namespaces, and Metadata.


Notes

Revision History