| 
  • If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • Buried in cloud files? We can help with Spring cleaning!

    Whether you use Dropbox, Drive, G-Suite, OneDrive, Gmail, Slack, Notion, or all of the above, Dokkio will organize your files for you. Try Dokkio (from the makers of PBworks) for free today.

  • Dokkio (from the makers of PBworks) was #2 on Product Hunt! Check out what people are saying by clicking here.

View
 

Citable Documents Specification

Page history last edited by Bob Blakley 12 years, 2 months ago

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

 

  1. Every named or numbered text section of the document is referenced by a CitableDocumentSubdivisionLocator.
  2. 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.
  3. Every imbedded video or audio clip in the document is referenced by a CitableDocumentSubdivisionLocator.
  4. 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:

 

  1. 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.
  2. 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.