CITABLE DOCUMENTS
Version 0.9
5 March 2010
Bob Blakley, Editor
Introduction
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.
1.0 Citable Documents
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.
2.0 Citable Document Locators
A Citable Document can be addressed by a CitableDocumentLocator, which specifies:
- Domain: The name of the Internet domain in which the server hosting the document resides.
- Container: The path from the root of the domain hosting the document to the container within which the document is stored.
- Document: The name of the document or the root element of the document.
- Date/Time Stamp: The time at which the referenced version of the document was created or most recently revised.
3.0 Citable Document Subdivision Locators
A subdivision of a Citable Document can be addressed by concatenating subdivision location information to the document’s CitableDocumentLocator:
- Path to Subdivision: A reference to an individual citable subdivision of the document.
4.0 CitableDocumentLocator Syntax
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.
4.1 Naming Citable Documents
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.
4.2 Publishing Citable Documents
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
5.0 CitableDocumentSubdivisionLocator Syntax
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.
6.0 Creating a Citable Document
A Citable Document MUST be formatted so that
- Every named or numbered text section of the document is referenced by a CitableDocumentSubdivisionLocator.
- Every imbedded figure in the document is referenced by a CitableDocumentSubdivisionLocator; The CitableDocumentSubdivisionLocator for a figure may reference either the figure itself or the figure's caption.
- Every imbedded video or audio clip in the document is referenced by a CitableDocumentSubdivisionLocator.
- Every CitableDocumentSubdivisionLocator referencing a Citable Subdivision of the document is referenced within the document itself.
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.
6.1 Creating <pathtosubdivision> references using HTML Anchors
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.
6.2 Referencing CitableDocumentSubdivisionLocators within Citable Documents
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:
- Table of Contents: The Citable Document contains a Table of Contents, in which each Citable Subdivision's name is linked to the Citable Subdivision itself using the Citable Subdivision's CitableDocumentSubdivisionLocator.
- Self-Referencing Subdivisions: Each Citable Subdivision in the document is linked to itself using its CitableDocumentSubdivisionLocator.
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.
6.2.1 Creating a Table of Contents which References Citable Subdivisions (example)
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>
6.2.2 Creating a Self-Referencing Citable Subdivision (example)
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:
- creates the HTML anchor #S1
- assigns that anchor to the section title text "Section 1"
- creates a link from the section title text "Section 1" to itself using the anchor #S1
7.0 Revision History
5 March 2010
Version 0.9: Revised by Bob Blakley for DC codeathon
- Cleaned up wording
- Replaced "folder" with "container"
- Updated Date/Time stamp format to improve readability and improve conformance to ISO 8601
- Differentiated requirements for publishing, naming, and formatting Citable documents
- Added requirement that Citable Subdivisions be referenced within the Citable Document in which they occur
- Added reference to RFC 2119
7 August 2009
Version 0.5: Initial version of this document.
8.0 References
More information about Citable Documents and the Citability project can be found at:
http://citability.org
http://citability.pbworks.com
http://leagueoftechvoters.org
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
9.0 Intellectual Property Statements
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.
10.0 Authors’ Contact Information
Bob Blakley
VP and Research Director,
Identity and Privacy Strategies,
Burton Group
blakley@burtongroup.com
Silona Bonewald
Founder
League of Technical Voters
silona@silona.com
David Strauss
Owner
Four Kitchens
david@fourkitchens.com
See Also
Comments (3)
Kurt Bollacker said
at 4:35 pm on Aug 18, 2009
I think there needs to be support for nested tags, and thus nested references. If whole document "A" is cited and then it later becomes section 5 of whole document "B", the references should not break. Perhaps globally unique IDs for all documents and sections would solve this.
Kurt Bollacker said
at 4:36 pm on Aug 18, 2009
I'm not sure that <foldername> is useful in the URL of a document. If the document changes folders, the URL and the references break. A flat space of documents IDs might be better.
Bob Blakley said
at 2:15 pm on Mar 5, 2010
I've removed folder names in favor of an optional container name element.
With respect to nested tags, this is a non-goal; the concept behind citability is that whenever a document is revised, a new Citable Document is created and published.
You don't have permission to comment on this page.