CITABLE DOCUMENTS
Version 0.9
5 March 2010
Bob Blakley, Editor
The goal of this document is to enable the creation of documents whose subdivisions can be cited, in order to facilitate public discussion and collaborative revision.
A Citable Document is a document in an electronic form which ensures that the document can be addressed by an unambiguous persistent URI called a CitableDocumentLocator and each of its identified subdivisions (paragraphs, sections, subsections, imbedded figures, imbedded video, etc…) can be addressed by unambiguous persistent URIs called CitableDocumentSubdivisionLocators.
A Citable Document contains of a collection of Citable Subdivisions; A Citable Document can be uniquely and persistently referenced using a CitableDocumentLocator, and each of its subdivisions can be uniquely and persistently referenced using a CitableDocumentSubdivisionLocator.
A Citable Document can be addressed by a CitableDocumentLocator, which specifies:
A subdivision of a Citable Document can be addressed by concatenating subdivision location information to the document’s CitableDocumentLocator:
CitableDocumentLocators are URIs which enable location of Citable Documents. A CitableDocumentLocator URI specifies the document's name and a path to the container in which the document is located.
When a Citable Document is created or revised, the new document or revision MUST be saved as a new Citable Document with a unique name. A Citable Document's unique name has the following format:
<citabledocumentuniquename> ::= <documentname>-<datetimestamp>
<documentname>
The name of the document.
<datetimestamp>
The date and time at which the referenced document was created or last revised. It is NOT the date and time at which the document was added to the container containing the document. When a Citable Document is modified, the result MUST be saved as a new Citable Document with the same <documentname> as the original document and a new, unique <datetimestamp>.
<datetimestamp> MUST be in one of the following formats:
YYYY-MM-DDTHH:MM:SSZ
YYYY-MM-DDTHHZ
YYYY-MM-DD
YYYY-MM
YYYY
Where
YYYY is four-digit Gregorian year
MM is two-digit month
DD is two digit day of month
HH is two-digit UTC Zulu hour in 24-hour format
MM is two-digit minute within hour
SS is two-digit second within minute
The timezone qualifier Z MUST be used if time is specified, and dates and times cited MUST be UTC time expressing Gregorian calendar dates.
When a Citable Document is published, it MUST be placed into a publicly-accessible repository and assigned a unique CitableDocumentLocator.
A CitableDocumentLocator is a URI in the following format:
<citabledocumentlocator> ::= http://<domainname>/[<containername>/]<citabledocumentuniquename>
Where the elements are defined as follows:
<domainname>
The name of the internet domain in which the server hosting the document resides.
<containername>
The path from the root of the domain hosting the document to the container within which the document is stored. This element is optional.
<citabledocumentuniquename>
The unique name of the Citable Document, as specified in section 4.1
A Citable Subdivision of a Citable Document can be addressed by a CitableDocumentSubdivisionLocator.
A CitableDocumentSubdivisionLocator is a URI in the following format:
<citabledocumentsubdivisionlocator> ::= <citabledocumentlocator><pathtosubdivision>
Where <pathtosubdivision> is a reference to an individual subdivision of the document expressed in the following syntax:
<pathtosubdivision> ::= #<subdivisionlocator>
<subdivisionlocator> is a string.
<subdivisionlocator> strings may have a variety of formats to accommodate the reference structures of the Citable Documents they reference.
A United States House resolution’s CitableDocumentSubdivisionLocator, for example, might look like this:
http://archive.house.gov/HR1586IH-2003-03-18T23:30:35Z#S1b1Bii
In this example, the <citabledocumentlocator> component is
http://archive.house.gov/HR1586IH-2003-03-18T23:30:35Z
And the <pathtosubdivision> component is
#S1b1Bii
Which indicates that the subdivision being referenced is
Section 1
Subsection b
Chapter 1
Paragraph B
Clause ii
<pathtosubdivision> syntax should be used consistently for documents of the same type; profiles of this specification may arise to standardize <pathtosubdivision> syntax for documents of particular types of interest.
For example, US federal laws have uniform reference syntax; <pathtosubdivision> syntax should conform to this reference syntax and should be standardized for this document type and used consistently.
A Citable Document MUST be formatted so that
A Citable Document MAY contain CitableDocumentSubdivisionLocators which reference elements other than those required in the list above.
Citable Document authors MAY create <pathtosubdivision> elements of CitableDocumentSubdivisionLocators in using any method the document author chooses, as long each Citable Subdivision of the document can be retrieved through a CitableDocumentSubdivisionLocator URI formatted in accordance with the requirements of this specification.
A simple way authors MAY make an HTML document citable is by creating an HTML anchor for each subdivision.
A document with CitableDocumentLocator
http://www.mydomain.com/specdraft-2009-08-07T16:30:35Z
might include the following HTML code:
<H2 id="S1">Section 1</H2>
...section 1 text...
<H3 id="S1a">Section 1, Subsection a</H3>
...subsection 1a text...
This document would allow citation of “Section 1” using the <pathtosubsection> component “#S1”, as follows:
http://www.mydomain.com/specdraft-2009-08-07T16:30:35Z#S1
The document would also allow citation of “Section 1, Subsection a” as
http://www.mydomain.com/specdraft-2009-08-07T16:30:35Z#S1a
Note that the reference structure chosen here has a prefix-condition property; the higher-level subdivisions’ <pathtosubsection> components are prefixes of their various subdivisions. <pathtosubsection> syntax SHOULD be designed to have this property for documents whose subdivisions themselves have lower-level subdivisions.
Citable Documents MUST be formatted so that every CitableDocumentSubdivisionLocator referencing a Citable Subdivision of the document is referenced within the document itself; this formatting MUST be done in one of two styles:
Section 6.2.1 contains an example of the Table of Contents style; Section 6.2.2 contains an example of the Self-Referencing Subdivisions style.
A document containing the following HTML code
<H2 id="S1">Section 1</H2>
...section 1 text...
<H3 id="S1a">Section 1, Subsection a</H3>
...subsection 1a text...
<H2 id="S2">Section 2</H2>
...section 2 text...
MAY be referenced using the following Table of Contents:
<ul>
<li><a href="#S1">Section 1</a>
<ul>
<li><a href="#S1a">Section 1, Subsection a
</ul>
</li><a href="#S2">Section 2</a>
</ul>
HTML code like the following
<a href="#S1"><H2 id="S1">Section 1</H2></a>
...section 1 text...
MAY be used to create a section heading which links to itself via an HTML anchor which serves as its CitableDocumentSubdivisionLocator. Specifically, the example code above:
5 March 2010
Version 0.9: Revised by Bob Blakley for DC codeathon
7 August 2009
Version 0.5: Initial version of this document.
More information about Citable Documents and the Citability project can be found at:
Information about HTML anchors can be found at:
http://www.w3.org/TR/html401/struct/links.html
W3C’s profile of the ISO 8601 UTC time format specification can be found here:
http://www.w3.org/TR/NOTE-datetime
RFC 2396 defines the syntax of URIs:
http://www.ietf.org/rfc/rfc2396.txt
Requirements language in this document is used in the spirit of IETF RFC 2119:
http://www.ietf.org/rfc/rfc2119.txt
This specification is published under a Creative Commons Attribution-Share Alike 3.0 United States License.
The authors certify that that any applicable patent or other IPR claims of which they are aware have been disclosed, or will be disclosed, and any of which they become aware will be disclosed.
Bob Blakley
VP and Research Director,
Identity and Privacy Strategies,
Burton Group
Silona Bonewald
Founder
League of Technical Voters
David Strauss
Owner
Four Kitchens