On the replacement of '~' for '#' in Akoma Ntoso URIs.

[Fabio Vitali <fvitali@gmail.com>]

Dear all, 

a few brief reflections about the idea of introducing yet another section in our URIs, introduce by the character '~' (or whatever) instead of the hash ('#') or the specification of the individual fragment of the reference. I am not commenting on the specific character, but just of the idea of replacing the hash with something else. 

The example provided by Monica refers to a MANIFESTATION-level references. 

> Example:
> /akn/us/act/usc/title9/eng@2014-10-10/main.akn#chp_3
> 
> to arrive to this:
> /akn/us/act/usc/title9/eng@2014-10-10/main.akn~chp_3

I have minor quibbles about the order of things, but in general the idea of replacing the hash in MANIFESTATION-LEVEL references seems to me kind of contrived, but not wrong per se. 

At the EXPRESSION and WORK level, on the other hand, the situation is completely different. I am strongly convinced that it is wrong to replace hashes, and that it provides no advantages neither in the short nor in the long term. Consider a WORK-LEVEL identifier such as /akn/us/act/usc/title9~chp_3

The problem lies around the fact that /akn/us/act/usc/title9~chp_3 and /akn/us/act/usc/title9~chp_2 are different URIs and therefore represent DIFFERENT WORKS. What is the relationship between X~chp_2 and X~chp_3? None whatsoever. They are not related, they are not connected, they know nothing of each other. X~chp_2 is not even a legislative document, but a fragment exactly composed of chapter 2. Does it have a preceding chapter? No. Does it have a following chapter? No. It's a monad. 

What about X~chp_2__cla_1? Does it exist, too? What is its relationship with X~chp_2? With X? None whatsoever. We end up with an uncontrolled proliferation of WORKS each of which is completely disconnected from the others. 

Let me give you another example. Suppose we have a modification act that says something like the following: 

---

Sect 1 - Modification to act 123 of 2014. 
The Act 123 of 2014 is modified as follows: 
1) Sect. 1 is replaced by the following: 
   "Sect 1: .... "
2) At the end of sect. 2 the following words "xxx" are appended.
3) Clause 2 of sect. 3 is suppressed. 

---

In case of replacement of the has with some other character, this section corresponds to the modification of THREE different works: /akn/xxx/act/2014/123~sect_1, /akn/xxx/act/2014/123~sect_2 and /akn/xxx/act/2014/123~sect_3__cla_2, or maybe /akn/xxx/act/2014/123~sect_3#cla_2. Not only mod elements have to repeat the whole URI every time, but the activeModifications section reports three different works and the references section also three different works. 

This is in contrast with common sense and with the human readable text that clearly mention three modifications to ONE text, and not ONE modification each to THREE texts. 

This would clearly build a separation between what the words of the law say and what the operations we perform do. I do not like it. I would very much like that the integrity and conceptual closeness between natural language text and actual operations are maintained.

A way out
---------

Fortunately, we are not alone in this situation, and ways out are starting to appear to maintain URI handling and conceptual operations close together. 

The technique is called "routing/dispatching", it does not have a wikipedia page yet, but has a history both for server-side management of URI and, more recently, for client-side management to include hash-based URIs. 

Server-side: 
Django: https://docs.djangoproject.com/en/dev/topics/http/urls/
CakePHP: http://book.cakephp.org/2.0/en/development/routing.html
PHP codeIgniter: http://www.codeigniter.com/user_guide/general/routing.html
Rails: http://guides.rubyonrails.org/routing.html

Client-side:
AngularJs: https://docs.angularjs.org/api/ngRoute
MeteorJs: https://github.com/EventedMind/iron-router
jQuery: http://xoxco.com/projects/code/router/ ,  
        https://github.com/camme/jquery-router-plugin ,  
        https://github.com/iSimonWeb/jQuery-Router, 
        etc.
Backbone.js: http://backbonetutorials.com/what-is-a-router/
No-dependencies: http://millermedeiros.github.io/crossroads.js/

What is routing? Simply put, it means intercepting the request for a URI (as specified in the DOM of a document displayed in the browser) and executing arbitrary procedures (including accessing a completely different URI) according to application-specific logic. Thus, the DOM may contain a reference to /a/b/c#d, the user clicks on the link and the routing application actually loads /z/w/x. 

Why is this useful? Because it maintains the illusion of reasonable and meaningful URIs in the DOM while the application's working requires much uglier and 'practical' URIs. This is very useful for REST APIs, which requires beautiful and meaningful URIs to be acceptable. Let me give you an example which is somewhat close to our needs. 

Suppose you have a REST API that exposes, say, customers through a URI such as 

domain.com/customers/                (returns the list of customers)
domain.com/customers/rec1321         (returns the record for customer 'rec1321')

Suppose we have 4 million customers. Plainly accessing domain.com/customers/ would therefore require the browser to wait for a list of 4 M items, just to show a handful. That is clearly absurd. Therefore the API provides additional parameters (say, start and count), so that you can make requests such as domain.com/customers/?start=0&count=100 to get only the first 100 items of the customers' list. 

Now what happens if I want to scroll near item 1321? I will NOT use a URI such as domain.com/customers/rec1321, because that does not return a list, but a single record. I could use a URI such as domain.com/customers/?start=1300&count=100#rec1321, but that would mean messing up considerably the content of the DOM to handle appropriately every possible scrolling request, to determine exactly the 100 items to load for each possible situation. Nonsense. What I want is to use a URI such as domain.com/customers/#rec1321, plain and simple: get the list of customers, and scroll it to rec1321.

All routing platform that I mentioned before are able to intercept a request for URIs such as these and replace them with practical URIs. The server, the browser and the HTTP connection are all part of the conspiracy, because the actual URI domain.com/customers/#rec1321 is never actually sent over the wire, but both the DOM (i.e., the document as stored) and the user (i.e., the document as displayed) contains and use only the nice and meaningful URI, and not the ugly one. 

This is like a good magic show: when we see the magician floating over the stage without support, we all rationally know there is a wire somewhere he is hanging from, but we DO NOT WANT  to see the wire, and seeing it would mean ruining the illusion and destroying the credibility of the magician. Wires need to be kept hidden and unseen. 

Instead, by specifying hash-free URIs in the documents (in the XMLs!!! For ever!!!) we are subjecting our documents, and our users, to the quirkiness of over-abundant Work URIs of disconnected documents, we are forcing our semantic tools to work with multiple URIs for the same documents (we have to explicitly assert that by modifying /akn/xxx/act/2014/123~sect_2__cla_1 we also modified /akn/xxx/act/2014/123~sect_2 and /akn/xxx/act/2014/123, which is not obvious) we are destroying the user's illusion of a single, long document which can be navigated by clicking on links and scrollbars, we are not only displaying our wires, we are painting them yellow. 

No, I can't say I like such idea. Especially considering that there are alternative solutions perfectly working. 

More than happy to illustrate routing in greater details during the teleconf and in subsequent chats and mail, if the need arises. I might be slow and intermittent, but I will try to my best to avoid going through these route. 

Ciao

Fabio

--


On 11/nov/2014, at 15:36, monica.palmirani <monica.palmirani@unibo.it> wrote:

> Dear Fabio,
> 
> it is fantastic! The next TC meeting will be Nov. 12th 18.30-19.30 CET.
> 
> The main topic will be the opportunity of using '~' instead of '#' in the AKOMA NTOSO URI.
> 
> Example:
> /akn/us/act/usc/title9/eng@2014-10-10/main.akn#chp_3
> 
> to arrive to this:
> /akn/us/act/usc/title9/eng@2014-10-10/main.akn~chp_3
> 
> This could favour the communication between client and server using HTTP in order to manage also the fragment information and also the <fragment> docType of Akoma Ntoso.
> 
> Yours,
> Monica
> 
> 
> Il 11/11/2014 14:26, Fabio Vitali ha scritto:
>> Dear all,
>> 
>> sorry for my silence of the past few weeks, I had some unforeseen health issue that I had to take care of and that have taken my whole attention for months now. Now I am slowly healing and while I don't think I am ready to take on the full weight of my duties, some of them are important enough for me to try to get beck onto them as soon as possible.
>> 
>> I would also like to thank Monica to have taken the load of my absence and to have kept me updated and informed (for the little that my mind could absorb in those weeks) about the topics being discussed.
>> 
>> I know for instance that a discussion has started about the opportunity of using '_' instead of '#'to separate document and fragment in Akoma Ntoso URIs.
>> 
>> I haven't been able to find out anything about the rationale behind it in the mailing list, but I'll try to send you a brief note about my thoughts on the topic in the next few hours.
>> 
>> Ciao
>> 
>> Fabio
>> 
>> 
>> 
>> --
>> 
>> Fabio Vitali                            Tiger got to hunt, bird got to fly,
>> Dept. of Computer Science        Man got to sit and wonder "Why, why, why?'
>> Univ. of Bologna  ITALY               Tiger got to sleep, bird got to land,
>> phone:  +39 051 2094872              Man got to tell himself he understand.
>> e-mail: fabio@cs.unibo.it         Kurt Vonnegut (1922-2007), "Cat's cradle"
>> http://vitali.web.cs.unibo.it/
>> 
>> 
>> 
>> 
>> 
>> 
>> --
>> 
>> Fabio Vitali                            Tiger got to hunt, bird got to fly,
>> Dept. of Computer Science        Man got to sit and wonder "Why, why, why?'
>> Univ. of Bologna  ITALY               Tiger got to sleep, bird got to land,
>> phone:  +39 051 2094872              Man got to tell himself he understand.
>> e-mail: fabio@cs.unibo.it         Kurt Vonnegut (1922-2007), "Cat's cradle"
>> http://vitali.web.cs.unibo.it/
>> 
>> 
>> 
>> 
>> 
>> ---------------------------------------------------------------------
>> To unsubscribe from this mail list, you must leave the OASIS TC that
>> generates this mail.  Follow this link to all your TCs in OASIS at:
>> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>> 
>> 
> 
> 
> -- 
> ===================================
> Associate professor of Legal Informatics
> School of Law
> Alma Mater Studiorum Università di Bologna
> C.I.R.S.F.I.D. http://www.cirsfid.unibo.it/
> Palazzo Dal Monte Gaudenzi - Via Galliera, 3
> I - 40121 BOLOGNA (ITALY)
> Tel +39 051 277217
> Fax +39 051 260782
> E-mail  monica.palmirani@unibo.it
> ====================================
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 



--

Fabio Vitali                            Tiger got to hunt, bird got to fly,
Dept. of Computer Science        Man got to sit and wonder "Why, why, why?'
Univ. of Bologna  ITALY               Tiger got to sleep, bird got to land,
phone:  +39 051 2094872              Man got to tell himself he understand.
e-mail: fabio@cs.unibo.it         Kurt Vonnegut (1922-2007), "Cat's cradle"
http://vitali.web.cs.unibo.it/