The purpose of the Akoma Ntoso URI Resolver is to provide completion, resolution and dereferencing to a legal document given its URI according to the Akoma Ntoso Naming Convention. Documents containing Akoma Ntoso URIs can use this resolver to provide hypertextual navigation between them. FRBR features are used to map abstract identifiers into lower-level identifiers and then used to find the physical URL of the most appropriate document.

The Akoma Ntoso URI Resolver relies on a federated architecture where the steps for the resolution are assigned to different modules according to issues related to jurisdiction, geographical location, authorship of documents and efficiency of the overall system.

The Akoma Ntoso URI Resolver divides the overall resolution process in four steps:

Parse: the requested URI is analyzed and structured in explicit features containing the information of the request in accessible form.
Complete: URI requests will often contain insufficient features to identify clearly and unambigupusly one physical resource. In particular, Work-level URIs and Expression-level URIs need completion to determine the best corresponding Manifestation-level URI. Missing information are provided by examining the user's preferences, the browser's settings, and the server's settings.
Resolve: one physical URL best matching the features of the request is determined (or none if the request is wrong or too vague). Optionally, additional URIs may be provided for navigation suggestions (e.g., the same document in different languages, or in different versions).
Perform: the response is delivered to the requesting agent according to one of following four verbs:

Redirect: the requesting agent is redirected to the corresponding physical resource, similarly to any URI shortener. The browser displays the physical URL and the Akoma Ntoso URI is gone and forgotten.
Dereference: the requested document is delivered to the requesting agent as if the request URI is the physical URL of the document. A complete virtualization of the namespaces of the document is therefore fully implemented.
Resolve: the features of the requested document are provided to the requesting agent, possibly with explanations and details, as well as the physical URL of the document and all the optional suggestions of the resolution step.
Wrap: the requested document is delivered inside a wrapping HTML document that contains services and information about the document and the resolution process.

In the following we provide some details about the most important concepts used in this document and by the resolver.

Akoma Ntoso: Akoma Ntoso is a proposed standard for the representation in XML of legal and legislative documents including enacted legislation (acts), proposed legislation (bills), parliamentary debate reports, formal amendments, judgements and other types of documents. Its characteristics are being discussed in the LegalDocML Technical Committee of OASIS, and additional details are found here.
Akoma Ntoso Naming Convention: Within the Akoma Ntoso proposed standard, an important part is the Naming Convention, a standardized syntax for naming documents that uses IRIs and FRBR for identifying and accessing to them. Details can be found here, but a brief summary of the Convention is found in the next section of this document.
Dereferencing: Dereferencing is the standard term used in IRI/URI management for the operation that performs an action over a web resource, given its IRI/URI: in particular, the dereferencing returns (a copy of) a resource given its IRI/URI. Dereferencing is often distinguished from resolution, which precedes dereferencing and produces an actionable IRI/URI that the HTTP agents can work with to provide the copy of the resource.
FRBR: The Functional Requirements for Bibliographic Records is a conceptual model of documents used by Akoma Ntoso to distinguish different types of references to them. While a full discussion of the nuances of this model is not appropriate here, FRBR introduces four layered concepts all in a way referring to documents: the Work, which is a "distinct intellectual or artistic creation", the Expression, which is "the specific intellectual or artistic form that a work takes each time it is realized.", the Manifestation, which is "the physical embodiment of an expression of a work" and the Item, which is "a single exemplar of a manifestation". The Akoma Ntoso Naming Convention provides a precise interpretation of these concepts, in that a Work-level reference is a reference to the document in its essence, to any and all of its versions and variants depending on context, while a Expression-level reference is a reference to precisely one specific variant of the document; each variant is either related to a specific moment in time, for documents that change and evolve (and they are often called versions), or to a specific linguistic expression, for documents that exist in different languages (and they are called language variants), or to a specific selection of content, for document that are published in different levels of completion, such as verbatim, abridged, anonymized, digest, etc. (and they are often called content variants); a Manifestation-level reference is a reference to a specific representation of a variant or version, in which it is finalized which data format (e.g. XML, HTML, or PDF), which markup, and which editorial content (e.g., commentaries) has been added. Finally, an Item-level reference is a reference to a physical copy of a Manifestation, which is by definition byte-by-byte identical to all the other Items of the same Manifestation. The resolution corresponds to the steps leading from a Work-level, Expression-level or Manifestation-level reference to the URL of any of the identical Items of such Work, Expression or Manifestation.
IRI: IRIs are Internationalized Resource Identifiers, strings formatted according to a specific syntax that are used to identify resources on the web. they follow the syntax specified in IETF RFC 3987 and are the internationalized version of URI (Uniform resource Identifiers) which have been used in the WWW for a decade or so. In this document, we will use equivalently URIs and IRIs to refer to URIs, since the term IRIs is still relatively unknown in the legal domain.
Resolution: Resolution is the operation preceding dereferencing, and it is defined as "the process of determining an access mechanism and the appropriate parameters necessary to dereference a URI; this resolution may require several iterations". From the point of view of this tool, the resolution is the operation of finding the URL of a physical resource (e.g., the Item-level URL) given the URI of a an abstract concept of document (e.g., a Manifestation-level URI). In particular, the abstract, Manifestation-level URI makes no reference to any concrete and physical infrastructure (location, software architecture, local name, etc.), while the resolved URL clearly specifies an actionable reference to a specific Internet server and a specific resource that it can return.
URI: URIs are Uniform Resource Identifiers, the ubiquitous mechanism for the web to refer to its resources, be they physical documents, server-side applications, conceptualizations of documents, or abstractions of concepts. Everything that can be identified and named on the web can be done through a URI, which is a string that is uniquely associated to the resource and is expressed according to the syntax established in IETF RFC 3986. Akoma Ntoso URIs are, technically, IRIs, but the term URI precedes and is often used interchangeably with it for practical purposes.

The general architecture of the Akoma Ntoso URI Resolver relies on two different types of actors, performers and resolvers:

the architecture of the resolver — The general architecture of the Akoma Ntoso URI Resolver

The performer receives the requests by means of an Akoma Ntoso URI.
The resolvers' catalogue is looked up for the most appropriate resolver.
One or more resolvers are found and readied for resolution.
The performer parses the request to create a feature list and queries each resolver for a best match.
The resolver uses the feature list to identify and return to the performer the URL of the best matching physical resource, as well as, optionally, a number of additional suggestions (e.g., copies in different languages or different versions).
The performer acts on the resolved URL either redirecting the user agent to the document's URL, or delivering the document itself, or wrapping the document inside a shell with additional information and tools.

Of course, each resolver can resolve only a subset of the URIs of legal documents, e.g., only those of a specific country or of a specific jurisdiction, but the federated architecture is guaranteed uniform access and equivalent resolution through the use of a shared catalogue of resolvers that lists all available resolvers for all covered jurisdictions. This also guarantees that all performers will resolve the URIs in the same manner and to the same URLs.

The first step performed by the performer is to examine the URI of the request and deliver a list of features to the actual resolver. The URI has to follow the Akoma Ntoso Naming Convention, with a few exceptions. The list of features is a JSON object with a known structure that is then sent to the resolver compacted in base64 so as to avoid representation problems.

This version of the Akoma Ntoso URI Resolver fully supports the Akoma Ntoso Naming Convention relative to Akoma Ntoso version 3. It also adds support for a small number of modifications with respect to it, that are documented in this subsection.

The syntax of the requests is as follows :

Resolver-specific fragment: /use
Work-level fragment: /country -jurisdiction /type /subtype /creator /creationDate /number
Expression-level fragment: /language @versionDate :viewDate /endViewDate /expressionCreator /contentDate
Manifestation-level fragment: /manifestationCreator /manifestationDate .format

*Explanation for each element of the syntax above*
use	one of the services offered by the resolver, such as resolve, redirect, dereference and wrap. Optional. If absent, a default is used.
country	a ISO 3166-1 alpha-2 two-letter code for the country. Required
jurisdiction	the specification of the national, regional or local jurisdiction emanating the document. Uses an open vocabulary. Optional
type	one of the principal document types in Akoma Ntoso, one of 'act', 'bill', 'amendment', ecc. Required
subtype	a subtype of the document, open vocabulary. Optional
creator	The emanating actor, required unless implicitly deducible by the document type
creation date	The original creation date of the work, expressed in YYYY-MM-DD format or just YYYY.
number	A number or title or other disambiguating feature of the work
language	The human language in which the expression is drafted. A ISO 639-2 alpha-3 three-letter code.
version date	The version date of the expression in syntax YYYY-MM-DD or just YYYY.
view date	The view date, i.e., the date relative to which the correct expression needs to be found. In syntax YYYY-MM-DD or just YYYY.
end view date	If end view date is present, the view is a range of dates. In syntax YYYY-MM-DD or just YYYY.
expression creator	The creator of the expression, if different from the emanating actor
content date	The date in which the content of this expression was created, if different from the version date. In syntax YYYY-MM-DD or just YYYY.
manifestation creator	The creator of the manifestation, i.e., the author of the specific markup or PDf or file being shown
manifestation date	The date in which this file was created, in syntax YYYY-MM-DD or just YYYY.
format	The common extension used to indicate the data format for the manifestation, such as xml for XML, PDF for PDF, doc for MS Word, etc.

The result of the parsing is a series of 'name/value' pairs, called features. In addition to the features extracted from the request, the resolver adds two more features:

The use, (i.e. whether to redirect,dereference,resolve or wrap the request URI) if no value has been set in the request
The path, i.e., the full request as it was provided in the URI.

In addition to the parsing, the performer also needs to determine which resolver is best suited to provide the resolved URL. To do so, it checks on a shared soure, the catalogue, looking for all the resolvers that claim to be able to solve the request.

The current catalogue is available at http://akn.web.cs.unibo.it/resolvers/servers.json. It is a simple JSON file that contains a regular expression on the request, and the URL of the associated resolver.

If more than one server matches the regular expression, the performer queries all the resolvers and returns the union of the results of all the queries.

Resolution is done on a full Manifestation-level URI. If the request URI is anything short of a full Manifestation-level URI, then there is missing information in the request that needs to be added before the resolution can take place. This is the completion of features. This is frequent when a Work-level or a Manifestation-level URI is used in the query.

Completion of features is therefore the determination of values for features that are not present in the request URI but needs to be present for the resolution to take place. Usual examples of features that may be missing from request include the language, the view date or the format.

The completion of the features can be taken care of client-side, or at the performer's, or at the resolver's. In fact, every feature that is necessary to resolution is provided, in decreasing order of preference:

in the request;
as user's preferences, delivered via cookie to the performer;
as browser settings, delivered via HTTP headers of the request (e.g., Accept-Language);
as resolver's defaults, which provides values for missing features, or overrides featurs if the relevant choice is not available.

For instance, a multilingual resolver may be able to provide a document in the language specified in the request, or by the user's preferences or by the browser settings. If no language is specified in these forms, then a default language is chosen by the resolver. Similarly, if a language is specified, for which the relevant document is not available, then again a default language is chosen.

The resolution is, strictly speaking, the determination of the physical URL of the actual document best matching the full set of features determined by the request URI and the completion of features. A specific actor called resolver takes care of that. Once the resolver that can perform the actual resolution is identified, it is automatically contacted via HTTP by the performer and delivered the full list of features as well as the preferences set by the user and the relevant HTTP headers. Performers and resolvers are therefore completely separate and independent, and exchange data through a common request and respnse format.

There are two possible ways to resolve into the physical URL:

The physical URL is composed of fragments that are corresponding to or computable from values of the features. In this case, a template mechanism can be used for building the physical URL.
The physical URL is an arbitray string not related in any way to the features. In this situation, a case by case mapping is necessary

This is the where I explain how to use it

Authors:

Fabio Vitali, Department of Computer Science and Engineering, University of Bologna
Monica Palmirani, CIRSFID, University of Bologna
Luca Cervone, CIRSFID, University of Bologna

Permission is hereby granted to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The Software can be used by anyone for purposes without commercial gain, including scientific, individual, and charity purposes. If it is used for purposes having commercial gains, an agreement with the copyright holders is required.

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Except as contained in this notice, the name(s) of the above copyright holders and authors shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: “This product includes software developed by University of Bologna (Department of Computer Science and Engineering and CIRSFID) and its authors (Fabio Vitali, Monica Palmirani, Luca Cervone)”, in the same place and form as other third-party acknowledgments. Alternatively, this acknowledgment may appear in the software itself, in the same form and location as other such third-party acknowledgments.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation
for the Akoma Ntoso URI Resolver, version 3.0

Introduction

Basic terminology

Architecture of the resolver

Parsing the request

The syntax of requests

Finding the resolver

Completing features

Resolving features

Resolution: the response

Performing the action on URL

Resolve

Redirect

Dereference

Wrap

Setting up an Akoma Ntoso URI Resolver

Download

The performer

The resolver

The catalogue

Conclusions

License

Documentation for the Akoma Ntoso URI Resolver, version 3.0