An experiment/draft to add readable deeplinks and fragments using the urn format. The aim is to support both 'digital' and 'physical' usecases of (book) publications.
The provided basic libraries and documentation allows to test, experience, adjust and extend its usability within various (development) environments and applications.
We attempt to maintain a readable format in snippets and internal references that can be translated to both online and offline books based on URN (Uniform Resource Name) formatting (RFC 8141).
The namespace isbn
is registered at IANA in its basic form. There currenlty is no standard contained within the definition to reference to segments/fragments within the publication.
Image source: Wikipedia (CC BY-SA 4.0) URN syntax diagram - namestring.png
Below is our proposal/implementation of how URN formatting will be based on our interpretation using (?=)[q-component] and (#)[fragment] within the spec. This could results in both technical and human readable urns that can be used to refer to a source or link like:
urn:isbn:9795363916662?tocitem=3.3.3
urn:isbn:9795363916662?tocitem=3.3.3#offset(10,34)
urn:isbn:9795363916662?tocitem=3.3.3#offset(10,34)the+ugly+fox+jumped+into+the+bushes...
Reference to publication with ISBN number (existing spec)
urn:isbn:9795363916662
Suggested: Reference to chapter
Numerical toc item (if present)
urn:isbn:9795363916662?tocitem=3.3.3
Chapter number (if no numerical toc present)
urn:isbn:9795363916662?segmentnum=5
Suggested: Reference to text section
urn:isbn:9795363916662?tocitem=3.3.3#offset(10)
urn:isbn:9795363916662?tocitem=3.3.3#offset(10,34)
Suggested: Extended Reference to text section (for readability)
urn:isbn:9795363916662?tocitem=3.3.3#offset(10,34)the+ugly+fox+jumped+into+the+bushes...
The formatting of the urn according to RFC 8141 allows for ?query and #fragment parameters to be included. At the time of writing, we have not found any existing formatting/query for urn:isbn specifically, that would enable referencing specific sections or parts within an isbn resource.
E.g. urn:isbn:9795363916662?chapter=bushes+and+foxes
would not be reliable.
To refer to a chapter, we add a ?query= parameter that refers to the numerical level/value within the Table of Contents (TOC).
Assuming the chapter to be referred to is called '3.3.3 Bushes and Foxes,' the numerical value 3.3.3 results in the urn.
urn:isbn:9795363916662?tocitem=3.3.3
[urn]:[nid]:[nss](q-component[?=])
If the chapters do not have a numerical value, a sequential number will be used (regardless of any jumps/levels/indents).
For selecting the chapter 'Bushes and Foxes,' the resulting urn would be urn:isbn:9795363916662?segmentnum=5
as this is the 5th chapter.
urn:isbn:9795363916662?segmentnum=5
[urn]:[nid]:[nss](q-component[?=])
* Introduction
* Proposal Round
* Habitat
* Sheep in the Meadow
* Bushes and Foxes
* Final chapter
To refer to a position before any segments (e.g. text before the 'Introduction' chapter), the segment would be '0' segmentnum=0
To refer to a position after any segments (e.g. text outside and after the 'Final chapter' ), the segment would be '-1' segmentnum=-1
For referencing a text fragment, we also use the 'fragment' described in the spec. Except that 'fragment' is preceded by a '#', there is no further definition/suggestion for naming in the found documentation.
[urn]:[nid]:[nss](q-component[?=])(fragment[#])
We define the fragment with an offset from the selected toc= item in the number of characters.
urn:isbn:9795363916662?tocitem=3.3.3#offset([start position], [length])
E.g. urn:isbn:9795363916662?tocitem=3.3.3#offset(10,150)
indicating that this urn refers to chapter 3.3.3
from character 10
up to 150
characters from the starting point (10
)
For readability (fragment identifier component), it is advisable to place a piece of text behind the offset()
e.g.
urn:isbn:9795363916662?tocitem=3.3.3#offset(10,34)the+ugly+fox+jumped+into+the+bushes
To indicate that the fragment is longer than shown in the urn, ...
will be placed behind the text e.g.
urn:isbn:9795363916662?tocitem=3.3.3#offset(10,34)the+ugly+fox+jumped+into+d...
📝 Note:
The use of '+' instead of '%20' to indicate a space might not be striclty valid.
At the moment, we are setting that aside because the use of a '+' supports readability and is also URL encoding compatible/exchangeable with a space. Note that a minus '-' sign is compatible.
Moreover, the spec allows deviation from URI encoding if it increases readability see (RFC 3986 Section 4)
The structure of the described namespace for isbn
is: urn:isbn:[ ISBN-10 | ISBN-13 ]
E.g. urn:isbn:9795363916662
[urn]:[nid]:[nss]
📝 Note: According to the isbn namespace spec, the namespace for isbn allows different writing styles of the ISBN number. Both ISBN-10 and ISBN-13 are permitted either with or without
'-'
. That meansurn:isbn:9795363916662
andurn:isbn:979-5-363916-66-2
are both valid.
composer require pubconnect/isbn-urn
See detailed description README.md in ./php
(WIP)