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.
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.
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.
The specification title should be composed from the specification name followed by the word "Version" and the version number.
Examples:
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 ##.#
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
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.
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
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 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.
A version-specific URI which is persistent, permanently assigned to one particular specification instance, and never re-used [Label: This Version]
A version-specific URI used to reference the previous published instance; it corresponds to the This Version URI of the immediate genetic ancestor of any given instance, unless the specification in question is the very first instance [Label: Previous Version]
A bookmarkable, version-agnostic, generic URI serving as a URI alias which is always associated with the latest/current specification instance, thus having a changing referent; it serves to identify and directly locate each successive published instance of a developing specification, through time [Label: Latest Version]
A URI which identifies the most recent published instance of a specification formally approved by a TC through ballot/vote; this URI is not applicable until a specification has reached its first approved Committee Draft level; it is useful as display metadata for specification URI that matches a Revision of a CD, PR, or CS specification. [Label: Latest Approved Version]
A URI which identifies the previous approved instance of a specification, applicable in case when a new approved specification is published; a specification released as "Committee Draft 02" would display the URI for the preceding approved stage, "Committee Draft 01". [Label: Previous Approved Version]
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:
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:
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:
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:
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:
Designating a URI to serve as "This Version" URI for display metadata is straight-forward: it is the URI which, if dereferenced, resolves under HTTP to fetch the document being viewed. TC editors are at liberty to use path components and filenames appropriate to TC's work, consistent with the rules for path/filename construction and URI design.
Designating a URI to serve as the "Previous Version" URI requires that the TC Editor establish the [This Version] URI used for the immediate predecessor, based upon the notion of a succession of published instances having unique specification URIs, per the discussion under specification stage and revision.
Determining a URI to serve as the "Latest Version" URI requires (as of 2006-09, but hopefully not too much longer) that the TC Editor communicate a request to the OASIS TC Administration, either: (a) proposing a URI alias to serve as the "Latest Version" URI, or (b) asking that one be assigned for the TC. Similarly for any applicable "Latest Approved Version" URI.
A "Latest Version URI" may be shorter in character length than a version-specific URI because it can omit date, stage, and any revision information: it generalizes over the details. Thus, for example, if OASIS members decided to form a 'health' TC, chartered to produce at least one Virus Markup Language (virus-ml) specification, the TC members could agree that URIs composed with the simple filename base 'virusML-1' could serve for all enumerated instances of Working Drafts, Committee Drafts, Public Review Drafts, and Committee Specifications for the "Version 1.0" specification design project. Thus, in the following hypothetical list of specification instances:
URIs 1-3 could serve as "Latest Version" URIs for all successive (HTML, PDF, and full ZIP) instances in #7 - #23
URIs 4-6 could serve as "Latest Approved Version" URIs in contexts requiring their citation
URIs #24 - #26 might represent three successive namespace URIs, mapped to RDDL namespace documents physically stored in the namespace documents directory (#27)
#7 - #23 represent directory URIs, where "*" signifies a collection of instance files (prose spec files in PDF, XHTML. editable source; XSDs, RNGs, WSDLs), and thus corresponding URIs, for each stage/revision
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.
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:
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>
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>
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:
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]
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:
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:
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
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.
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?'..."
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:
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.
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:
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:
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.
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:
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 |
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
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
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
Basic Profile Version 1.1
Final Material
2006-04-10
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 |
This collection of references supplements the citation list provided in the Guidelines for Filenames, URIs, Namespaces, and Metadata.
[ASIS] Artifact Standard Identification Scheme for Metadata 1.0. Approved TAB Document. 30-January-2006. Edited by William Cox and Tim Moses. Artifact Identifier: 'ArtifactStandardIdentificationSchemeForMetadata-1.0.1-req-approved'. Sent out for public review on February 06 2006 ending March 01, 2006. With spreadsheet listing comments and responses from the July 2005 review. Note: Some of the definitions and ideas from the ASIS document (and much of the underlying research) has been carried over into the Guidelines for Filenames, URIs, Namespaces, and Metadata document, along with this Metadata and Versioning supplement. The particular proposal from ASIS about the use of artifactIdentifiers and the required construction of filenames from prescribed metadata components was not accepted by the membership, established through member review and subsequent analysis in the TAB. Thus "Componentized filenames (e.g., IETF-style filenames, using hyphen-separated metadata factoids) are allowed but not required." [local copy]
[DCES] Dublin Core Metadata Element Set, Version 1.1: Reference Description. Dublin Core Metadata Initiative (DCMI) Recommendation. Date Issued: 2004-12-20. "This document is the reference description, version 1.1 of the Dublin Core Metadata Element Set. The Dublin Core metadata element set is a standard for cross-domain information resource description. Here an information resource is defined to be 'anything that has identity'... There are no fundamental restrictions to the types of resources to which Dublin Core metadata can be assigned. Three formally endorsed versions exist of the Dublin Core Metadata Element Set, version 1.1: (1) ISO Standard 15836-2003 (February 2003); (2) NISO Standard Z39.85-2001 (September 2001) (3) CEN Workshop Agreement CWA 13874 (March 2000). The current document has been brought into line with the ISO and NISO standards. The more comprehensive document DCMI Metadata Terms includes the latest and authoritative term declarations for the Dublin Core Metadata Element Set, Version 1.1.
[DCMI-ENC] DCMI Encoding Guidelines
[DC-XML] "Expressing Dublin Core Metadata Using XML.". By Pete Johnston (Eduserv Foundation) and Andy Powell (Eduserv Foundation). Date Issued: 2006-05-30. DCMI Working Draft. "This document specifies an XML format for representing a Dublin Core metadata description set. The XML format is known as 'DC-XML'. The DCMI Abstract Model (DCAM) describes the constructs that make up a DC metadata description set. In order to represent a DC metadata description set in an XML document those constructs have to be represented as components in that XML document, i.e., as XML elements and XML attributes, XML element names and XML attribute names, and as XML element content and XML attribute values..."
[DCQ-HTML] Expressing Dublin Core in HTML/XHTML meta and link elements. By Andy Powell (UKOLN, University of Bath). Date Issued: 2003-11-30. DCMI Recommendation. "This document describes how Dublin Core metadata can be encoded in HTML/XHTML <meta> and <link> elements."
[DC-XML-GUIDELINES] Guidelines for implementing Dublin Core in XML. By Andy Powell (UKOLN, University of Bath) and Pete Johnston (UKOLN, University of Bath). Date Issued: 2003-04-02. Dublin Core Metadata Initiative Recommendation. "This document provides guidelines for people implementing Dublin Core metadata applications using XML. It considers both simple (unqualified) DC and qualified DC applications. In each case, the underlying metadata model is described (in a syntax neutral way), followed by some specific guidelines for XML implementations. Some guidance on the use of non-DC metadata within DC metadata applications is also provided."
[DCMES-XML] Expressing Simple Dublin Core in RDF/XML. By Dave Beckett (Institute for Learning and Research Technology - ILRT, University of Bristol), Eric Miller (W3C), and Dan Brickley (W3C/ILRT). Date Issued: 2002-07-31. Dublin Core Metadata Initiative Recommendation. "The Dublin Core Metadata Element Set V1.1 (DCMES) can be represented in many syntax formats. This document explains how to encode the DCMES in RDF/XML, provides a DTD to validate the documents and describes a method to link them from web pages."
[DCQ-RDF] Expressing Qualified Dublin Core in RDF / XML. By Stefan Kokkelink and Roland Schwänzl. Date Issued: 2002-05-15. DCMI Proposed Recommendation. "This document describes how qualified Dublin Core metadata can be encoded in RDF / XML and gives practical examples."
[DCMI-ABSTRACT] DCMI Abstract Model. By Andy Powell (UKOLN, University of Bath, UK), Mikael Nilsson (KMR Group, CID, NADA, KTH Royal Institute of Technology, Sweden), and Ambjörn Naeve (KMR Group, CID, NADA, KTH Royal Institute of Technology, Sweden), and Pete Johnston (UKOLN, University of Bath, UK). Date Issued: 2005-03-07. DCMI Recommendation. "This document specifies an abstract model for DCMI metadata. The primary purpose of this document is to provide a reference model against which particular DC encoding guidelines can be compared. To function well, a reference model needs to be independent of any particular encoding syntax. Such a reference model allows us to gain a better understanding of the kinds of descriptions that we are trying to encode and facilitates the development of better mappings and translations between different syntaxes. This document is primarily aimed at the developers of software applications that support Dublin Core metadata, people involved in developing new syntax encoding guidelines for Dublin Core metadata and those people developing metadata application profiles based on the Dublin Core."
[DCMI-TERMS] DCMI Metadata Terms. Prepares by the Dublin Core Metadata Initiative (DCMI) Usage Board. DCMI Recommendation. Date Issued: 2006-08-28. "This document is an up-to-date specification of all metadata terms maintained by the Dublin Core Metadata Initiative, including elements, element refinements, encoding schemes, and vocabulary terms (the DCMI Type Vocabulary).
[FRBR] Functional Requirements for Bibliographic Records: Final Report. Available in HTML and PDF format. The International Federation of Library Associations and Institutions (IFLA). Produced by members of the IFLA Study Group on the Functional Requirements for Bibliographic Records. München: K. G. Saur, 1998. UBCIM Publications, New Series #19). ISBN: 3-598-11382-X. FRBR provides an abstract and generic conceptual model for "bibliographic" representation based upon defined entities, attributes, and relationships. Conceptual entities of interest include "work, expression, manifestation, and item, along with a second group comprising entities responsible for intellectual or artistic content, the physical production and dissemination, or the custodianship of such products: person and corporate body. A third group comprises an additional set of entities that serve as the subjects of intellectual or artistic endeavour: concept, object, event, and place."
[ISO-8601] ISO 8601:2004. Data Elements and Interchange Formats — Information Interchange — Representation of Dates and Times. International Organization for Standardization (ISO). 33 pages. Formats for Numeric Representation of Dates and Time. "ISO 8601:2004 is applicable whenever representation of dates in the Gregorian calendar, times in the 24-hour timekeeping system, time intervals and recurring time intervals or of the formats of these representations are included in information interchange. It covers: (1) calendar dates expressed in terms of calendar year, calendar month and calendar day of the month; (2) ordinal dates expressed in terms of calendar year and calendar day of the year; (3) week dates expressed in terms of calendar year, calendar week number and calendar day of the week; (4) local time based upon the 24-hour timekeeping system; (5) Coordinated Universal Time of day; (6) local time and the difference from Coordinated Universal Time; (7) combination of date and time of day; (8) time intervals; (9) recurring time intervals." See also W3C Date and Time Formats below.
[MALER] Proposed Rules for OASIS Document File Naming. Working Draft 02. 18-February-2003. Document identifier: 'chairs-filenaming-02'. Location: http://www.oasis-open.org/spectools/docs. Edited by Eve Maler, Sun Microsystems, Inc. "This document provides a proposed set of file naming rules for TC charters, contributions made to TCs, TC drafts and Committee Specifications, and OASIS Standards."
[NamespaceState] The Disposition of Names in an XML Namespace. Produced by the W3C Technical Architecture Group (TAG). Edited by Norm Walsh (Sun Microsystems). TAG Finding. 9-January-2006.
[Namespaces10] Namespaces in XML. W3C Recommendation. World Wide Web Consortium. Reference: REC-xml-names-19990114. 14-January-1999. Edited by Tim Bray, Dave Hollander, and Andrew Layman. With errata page.
[Namespaces11] Namespaces in XML 1.1. W3C Recommendation. 04-February-2004. Edited by Andrew Layman, Richard Tobin, Tim Bray, and Dave Hollander. See also Namespaces in XML 1.1 Requirements. With errata page.
[Namespaces11-2] Namespaces in XML 1.0 (Second Edition). W3C Recommendation. 16-August-2006. Edited by Tim Bray (Textuality), Dave Hollander (Contivo, Inc.), Andrew Layman (Microsoft), Richard Tobin (University of Edinburgh and Markup Technology Ltd). See also Namespaces in XML 1.1 Requirements. With errata page and public archives for 'xml-names-editor@w3.org' list.
[NOTE-datetime] Date and Time Formats. By Misha Wolf and Charles Wicksteed (Reuters). Submitted to W3C, 15-September-1997. "This document defines a profile of ISO 8601, the International Standard for the representation of dates and times. ISO 8601 describes a large number of date/time formats. To reduce the scope for error and the complexity of software, it is useful to restrict the supported formats to a small number. This profile defines a few date/time formats, likely to satisfy most requirements."
[RFC3986] Uniform Resource Identifier (URI): Generic Syntax. IETF Request for Comments 3986, STD #66. IETF Network Working Group, Standards Track RFC. Updates RFC 1738, Obsoletes RFCs 2732, 2396, 1808. Edited by Tim Berners-Lee (W3C/MIT), Roy Fielding (Day Software), and Larry Masinter (Adobe Systems Incorporated). January 2005. 61 pages. Unofficial HTML version. Summary: "A Uniform Resource Identifier (URI) provides a simple and extensible means for identifying a resource. A URI is an identifier consisting of a sequence of characters matching [a specified] syntax rule. URIs have a global scope and are interpreted consistently regardless of context, though the result of that interpretation may be in relation to the end-user's context... An identifier embodies the information required to distinguish what is being identified from all other things within its scope of identification. Use of the terms 'identify' and 'identifying' refer to this purpose of distinguishing one resource from all other resources, regardless of how that purpose is accomplished (e.g., by name, address, or context)... 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, often depending on the persistence and care in the assignment of identifiers by the naming authority, rather than on any quality of the scheme. Future specifications and related documentation should use the general term 'URI' rather than the more restrictive terms 'URL' and 'URN'..."
[RFC3121] A URN Namespace for OASIS. IETF Request for Comments: 3121. June 2001. Similar, but irrelevant to this naming discussion: A URN Namespace for XML.org.
[URI-Metadata] The Use of Metadata in URIs. Produced by the W3C Technical Architecture Group (TAG). Edited by Noah Mendelsohn and Stuart Williams. DRAFT TAG Finding. 09-June-2006 (or later).
[Versioning] [Editorial Draft] Extending and Versioning Languages Part 1. Edited by David Orchard (BEA Systems, Inc) and Norman Walsh (Sun Microsystems, Inc). Draft TAG Finding. 17-July-2006 or later.
[W3C-Versions] Version Management in W3C Technical Reports. Maintained by Ian Jacobs. Date: 2006/08/10 (or later). Part a series of documents that describe W3C Technical Report Publication Policies.
Comments from reviewers. Any OASIS member wishing to make review comments visible to the public should post email to the OASIS Member Discuss group list. One may join this group to become an 'oasis-member-discuss' list subscriber, but it is not necessary to join in order to post email messages to the list. Non-members wishing to provide feedback may send email to Robin Cover.
One reviewer 2006-10-06 asked whether copyright is a required metadata element. A copyright statement is required in all human-readable specification-related files, including prose specifications and in machine-readable files.
Specification title/name. The TC Process (Section 2.2 TC Formation) refers to a specification title under clause (2)(c): "Optionally, a proposed working title and acronym for the specification(s) to be developed by the TC." No further rules or guidance are provided about:
The specification title referenced in "Section 2.2 TC Formation" is apparently synonymous with the specification name, as referenced in TC Process Section 2.18, "The name of any specification..."
ASIS proposal for componentized filenames. See the comment on ASIS Section 6.2 "Specification and other Prose Document Filenames" which proposed (but was not accepted as a requirement):
"For each artifact that is a specification (or other prose document) associated with a single product, the OASISdefinedName MUST contain the name components in the stated order, except that language MAY be omitted: product, productVersion, artifactType, stage, revision, language, and form. The name components MUST be separated by hyphens, except form, which is separated from the preceding component with a period. [Thus] product-productVersion-artifactType-stage-revision-language.form
Note that the ArtifactIdentifier MAY be a TCdefinedName drawn from the same character set. The filename MUST be the ArtifactIdentifer followed by the optional literal period and form..."
Labels for metadata embedded in word-processing formats and XHTML markup. No specific recommendations are given here for syntaxes and other conventions for use of embedded metadata other than a suggestion that labels matching the required display metadata be used. For example, in XHTML Version 1.0/1.1 markup contexts, a TC could use the repeatable META empty element for "generic metainformation"; in XHTML Version 2.x, the equivalent not-empty META and LINK elements might be used for such Metainformation and other properties. This mechanism is not elegant (e.g., compared to an RDF metadata encoding), and TCs are reminded that use of contrived pseudo-syntax not licensed by the relevant markup language standards to structure information inside the value of a content attribute is strongly deprecated. As an example strategy, one could use lower-case and camel-case spellings as the value of the META element's name attribute, matching the display metadata labels. Illustration:
<meta name="title" content="Some Title" />
<meta name="version" content="1.0" />
<meta name="stage" content="wd" />
<meta name="revision" content="02" />
<meta name="date" content="2006-09-29" />
<meta name="thisVersionURI" content="http://docs.oasis-open.org/something1" />
<meta name="previousVersionURI" content="http://docs.oasis-open.org/something2" />
<meta name="latestVersionURI" content="http://docs.oasis-open.org/something3" />
<meta name="technicalCommittee" content="OASIS DocBook TC" />
<meta name="chair" content="Diane Jordan" />
<meta name="editor" content="Gilbert Pilz" />
<meta name="relatedWork" content="someURI" />
<meta name="declaredXMLNamespace" content="http://docs.oasis-open.org/ws-tx/wscoor/2006/06" />
<meta name="abstract" content="abstractContent" />
Metadata used in the vintage 2005 templates. The OASIS specification authoring templates are being updated in the 2006 Q4 timeframe. Earlier versions of the XHTML Specification Template, including the XHTML Template with Legacy IPR Notices and XHTML Template with 4-15-05 Notices provided for inclusion of certain additional metadata, no longer required as of 2006-09-29. The META elements for tc-short-name and product may be used; the artifact-type metadata element is no longer recommended.
<meta name="tc-short-name" content="tc-short-name" />
<meta name="product" content="product" />
<meta name="artifact-type" content="artifact-type" />
<meta name="version" content="version" />
<meta name="revision" content="revision" />
<meta name="stage" content="stage" />
Versioning in W3C Technical Reports, according to "W3C Technical Reports and Publications: About W3C Technical Reports"
Each W3C Technical Report has two URIs associated with it, located at the beginning of the document:
A "this version" URI, which identifies the specific document. W3C will make every effort to make a given document indefinitely available, in its original form, at its "this version" URI. W3C may correct broken markup and broken links in place (per the in-place modification policy) but otherwise will make every effort not to change content after publication of a document.
A "latest version" URI, which identifies the most recently published draft in a document series. By document series we mean, for example, "all the drafts of the XML Schema 1.0 specification from First Public Working Draft to Recommendation."
We encourage you to consider carefully which of the two identifiers to use when referring to a W3C Technical Report. If you mean to refer to a particular document or passage "forever," please use the "this version" URI. If you need to refer to "whatever is the most up-to-date version", please use the "latest version" URI.
[See also: Technical Report Publication Policy, "Normative Document Representation" - At least one normative representation MUST be available for requests that use the "This Version" URI. More than one normative representation MAY be delivered in response to such requests. A "This Version" URI MUST NOT be used to identify a non-normative representation... Note: Serving two representations at the "this version" URI is an assertion by W3C that the documents are equivalent for the purposes of conveying the requirements of the document. In practice, the Comm Team will not read each alternative to verify that this is the case. If the Communications Team learns of substantive discrepancies between normative alternatives, the W3C Head of Communications may request that the author no longer serve the alternative as normative.
Concern for appropriate citation format and correct URI semantics. This note relates to the sections titled "Latest Version" URIs for Schemas, WSDLs, RDDLs, and Other Specification Components and Specification URIs. It provides a worked example illustrating the creation of data errors when the author of a fictitious document "Musings upon the OASIS Shoe Specification" creates a citation using the "Latest Version" URI instead of the "This Version" URI.
Imagine the following example citation, based upon "Musings" Document A, and spec Documents B1 and B2:
Document A
Title: Musings upon the OASIS Shoe Specification Date: 2007-04-01 URI: http://docs.oasis-open.org/exampleTC/shoes1.0/misc/jSmith.html
Document B1
Title: OASIS Shoe Specification Date: 2007-03-31 Stage: Committee Draft 03 This Version: http://docs.oasis-open.org/exampleTC/shoes1.0/cd/spec03.html Latest Version: http://docs.oasis-open.org/exampleTC/shoes1.0/spec.html Running Footer: shoes1.0-cd-03
Document B2
Title: OASIS Shoe Specification Date: 2007-08-30 Stage: Committee Specification 02 This Version: http://docs.oasis-open.org/exampleTC/shoes1.0/cs/spec02.html Latest Version: http://docs.oasis-open.org/exampleTC/shoes1.0/spec.html Running Footer: shoes1.0-cs-02
Note that between 2007-03-31 and 2007-08-30 the OASIS Shoe Specification has gone through several revisions. Imagine that the author of Document A makes the following statement in writing on 2007-04-01, using the "Latest Version" URI for the 'OASIS Shoe Specification Committee Draft 03':
"I am disappointed that the specification does not model shoe size, as defended in Section 3.4 and in the note."
Analysis: as of 2007-04-01, the statement in Document A makes sense, and the links are both accurate. As of 2007-08-30 (Committee Specification 02), the specification with the title OASIS Shoe Specification has changed. Now the written statement in Document A is absurd, because:
The results identified in the bullet items above illustrate why, in the general case, creating a citation using a "Latest Version" URI would constitute incorrect citation strategy — if the particular content of the referent is important. In making normative reference (to particular content), one should not cite a moving target: a document cited at its "Latest Version" URI is indeed (most) often a moving target, sometimes even if the resource is said to be "final".
The author of Document A should have written as follows, so that the comment would have integrity after the CD 03 was changed and issued with revised content:
"I am disappointed that the specification does not model shoe size, as defended in Section 3.4 and in the note."
Here are three W3C example citations, from "Web Services Addressing 1.0 - Core", which illustrate a strategy for making normative or informative reference to exact content [a particular document at a particular version-specific URI], while allowing, optionally, for indication of the "Latest Version" URI alias:
[WS-Addressing WSDL Binding] Web Services Addressing 1.0 - WSDL Binding, M. Gudgin, M. Hadley, T. Rogers, and U. Yalcinalp, Editors. World Wide Web Consortium, 16 February 2006. This version of the WS-Addressing WSDL Binding specification is http://www.w3.org/TR/2006/WD-ws-addr-wsdl-20060216. The latest version of WS-Addressing WSDL Binding is available at http://www.w3.org/TR/ws-addr-wsdl.
[WSDL 1.1] Web Services Description Language (WSDL) 1.1, E. Christensen, et al, Authors. World Wide Web Consortium, March 2001. Available at http://www.w3.org/TR/2001/NOTE-wsdl-20010315.
[XML Schema Datatypes] XML Schema Part 2: Datatypes Second Edition, P. Byron and A. Malhotra, Editors. World Wide Web Consortium, 28 October 2004. This version of the XML Schema Part 2 Recommendation is http://www.w3.org/TR/2004/REC-xmlschema-2-20041028. The latest version of XML Schema Part 2 is available at http://www.w3.org/TR/xmlschema-2.
Version 03
Changed document title for Part 1 from "Guidelines for Filenames, URIs, Namespaces, and Metadata" to "OASIS Naming Guidelines: Filenames, URIs, Namespaces", to clarify that the OASIS Naming Guidelines is (as of 2007-03) in two parts. The companion Part 2 document is OASIS Naming Guidelines: Metadata and Versioning
Added Specification URIs Model Example to show what a typical specification title page should include for Specification URIs.
Added a new section "Latest Version" URIs for Schemas, WSDLs, RDDLs, and Other Specification Components to provide guidance on the design and use of version-agnostic URIs for XML schemas and related ancillary file types. The corresponding rule in Part 1 for URI aliasing strategies was updated.
Added a new paragraph and reference to the draft RDDL Template in the section Metadata in Namespace Documents, suggesting required elements in RDDL namespace documents.
Improved the wording about URI and resource permanence, clarifying that 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.
Clarified the rule about allowance for URN-based namespaces to remind TC editors that OASIS has no current plans to implement the online resolution system for URNs referenced in IETF RFC 3121.
Added a new rule about avoiding URI collision/confusion and semantic overloading at the point of a XML Namespace URI which could be mistaken for a regular directory URI, or vice versa: design of directory URIs and NS URIs should avoid contention by not storing resources at a collision point.
Added a new guideline about the preferred use of path components for creating new sets of specification URIs as a prose specification document and supporting files (e.g., XML schemas, DTD, WSDL, RDDL) progress through various stages and revisions.