This page is for providing feedback on the Citable Documents Specification.

 

Please group feedback by respective section in the specification, then use a simple list under that section. Please date-stamp and sign your feedback.

 

 

4.0 CitableDocumentLocator Syntax

 

 

•     2010-04-08 from Mark. Consider removing much of the semantic detail from the identifier (or, at least don't require it).  For instance, a CitableDocumentLocator could be:

<resolver-host>/<identifier> : for linking to the latest version of the document.

<resolver-host>/<identifier>#fragment : for linking to a specific section.

<resolver-host>/<identifier>?version=<versionid> : for linking to a specific version.

 

 

Where <resolver-host> is the service that's keeping track of the document versions.  It could even create the identifiers.

 

A great deal of work has been done on persistent identifiers that can help here.  Look at crossref.org and their use of the Handle System (http://www.cnri.reston.va.us/).

 

Giving a document a permanent name and using that name whenever you want to cite it is very useful.  You don't need to remember what date a particular version was released in order to remember the URL.

 

Having the extra layer of indirection is also good because you can delegate the management of the URI space and resolution services (that's what the Handle System mentioned above does).

 

 

• 2009-219 from Tantek. Regarding <datetimestamp>, a few points:
1. Please use YYYYMMDDTHHMMSS instead of YYYYMMDDHHMMSS in order to at least create a valid ISO8601 datetime (with "T" separator between the date and time). This is a minor point of syntax, thus it is better to err on the side of conforming to an existing standard.
2. Allow coarser granularity for <datetimestamp>, most systems will not need seconds (or even minutes) granularity, e.g. thus allow the following:
• YYYYMMDDTHHMM
• YYYYMMDDTHH
• YYYYMMDD
• YYYYMM
• YYYY
3. Allow hyphenation of dates. From experience with readability in microformats, it may be desirable to use hyphens and thus also permit:
• YYYY-MM
• YYYY-MM-DD
• YYYY-DDD (ordinal ISO8601 date)
4. Permit the <datetimestamp> to be a suffix rather than a path component, e.g. allow both <documentname>-<datetimestamp> as well as <documentname>/<datetimestamp>. The reasons for this are (1) it may be easier for some systems to simply put versions of a document in the same folder, and (2) there is pre-existing experience/conventions with doing so (e.g. W3C Pubrules, see details/links on PastWork page. e.g. "shortname-YYYYMMDD".)
• 2009-08-08 from Kevin D. Keck, to amplify and extend Tantek's points:
1. I agree about allowing omission of time (providing a simple date), and conforming to ISO8601.
2. I would recommend using specifically the ISO8601 profiles specified in XML Schema (and also used in RDF, by reference): xsd:dateTime and xsd:date.  Both require hyphens within the date, and xsd:dateTime also requires colons within the time part.  These profiles use more characters, but are much more human-readable.  They do not support the ordinal date (YYYY-DDD) format, and I feel this is a virtue as it also is not very human readable.
3. The standard really ought to specify whether timestamps are to be understood as local (according to the time zone of the host machine) or as UTC.  If they are to be understood as UTC (as are timestamps in, e.g., HTTP headers), then the time should be required to end with a 'Z', for compatibility with XML and RDF. 

 

We also need to discuss additional formats:

PDF

CVS and Excel spreadsheets

Websites

RSS feed

Video

 

Return to

• Citable Documents Specification