Skip to main content

4 IRI[1] (Normative)

4.1 Introduction to compliant IRI syntaxes​

The Akoma Ntoso standard defines a number of referenceable concepts that are used in many situations in the lifecycle of legal documents.

The purpose of this section is to provide:

a) a standard referencing mechanism to these concepts through the use of IRI references associated to classes and instances of an ad hoc ontology (the Akoma Notoso Naming Convention). The referencing mechanism discussed in this document is meant to be generic and evolving with the evolution of the underlying ontology;

b) a set of requirements for other naming conventions to be usable within Akoma Ntoso XML resources in a proper way (Functionally Equivalent Naming Conventions see 4.12).

4.2 Document IRIs​

The most important concepts of the Akoma Ntoso informal ontology are related to documents that have legal status. All discourses and all descriptions of legal sources can be characterized as referring to one of the four levels of a document as introduced by IFLA FRBR ( [ FRBR ] ):

(a) Work – the abstract concept of the legal resource (e.g., act 3 of 2015).

(b) Expression - any version of the Work whose content is specified and different from others for any reason: language, versions, etc. (e.g., act 3 of 2015 as in the version following the amendments entered into force on July 3 rd , 2016).

(c) Manifestation - any electronic or physical format of the Expression: MS Word, Open Office, XML, TIFF, PDF, etc. (e.g., PDF representation of act 3 of 2015 as in the version following the amendments entered into force on July 3 rd , 2016).

(d) Item – the physical copy of any Manifestation in the form of a file stored somewhere in some computer on the network or disconnected (e.g., the file called act32015.pdf on my computer containing a PDF representation of act 3, 2015 as in the version following the amendments entered into force on July 3 rd , 2016).

All documents at all levels can be composed of sub-elements that, when combined, form the whole document. These are called components and abstractly represent the notion that several independent subdocuments form the whole document as it appears to the reader (i.e., a main body possibly followed by a number of attachments such as schedules and tables):

  • WorkComponents (e.g., main, schedule, annexes, table) - the WorkComponents are abstract entities that can be referenced to refer to different ExpressionComponents in time.

  • ExpressionComponent (e.g., main, schedule, annexes, or table.) - the ExpressionComponents represent the visible division of the document as generated by the content author (Parliament, etc.) for a specific Expression of the Work.

  • ManifestationComponent (e.g., xml files, PDF files, or TIFF images.) - the ManifestationComponents represent the division of the document as generated by the Manifestation author (e.g., the XML editor) for a specific Manifestation of a specific Expression.

  • ItemComponent - the actual files corresponding to the ManifestationComponents

Other concepts dealt by the Akoma Ntoso informal ontology also derive from the IFLA FRBR ontology, and include, but are not limited to, individuals (Person), organizations (Corporate Body), actions and occurrences (Event), locations (Place), ideas (Concept) and physical objects (Object).

4.3 Absolute and Relative IRIs​

At all levels, the Akoma Ntoso IRIs belong to the http:// scheme and are normally resolved using mechanisms widely available in browsers and web servers. Within documents, IRIs are used as references to addressable resources, and are thus called IRI references .

According to the authoritative source RFC 3986 [2] , all http:// IRI references are divided into absolute IRI and relative IRI references . An absolute IRI starts with the string “http://”, which is then followed by an officially registered domain name, and the local part that starts off the first individual “/” character. A relative reference, on the other hand, has no indication of the scheme, no indication of the domain name, and may have further missing parts at the beginning of the whole string (no missing parts on the end, though). Browsers are able to build the absolute IRI corresponding to the relative IRI by adding at the beginning of the provided IRI the missing parts that are taken from the IRI of a base resource.

In XML manifestations of Akoma Ntoso documents, IRI references are always expressed in relative forms.

This implies that any resolution is carried out by the source of the base document (e.g., the one where the IRI reference is stored). This makes all IRIs independent of the actual resolution mechanism, and allows for very flexible storage, access, and reference mechanisms. This means that all resolution mechanisms used to access an Akoma Ntoso document from another Akoma Ntoso document will rely on the same resolution mechanism as the original one, regardless of the resolution mechanism employed to generate the documents themselves. In case the hosting document lacks a base IRI, it is the responsibility of the active application to provide a base IRI in its stead.

Since it is a requirement of Akoma Ntoso that all existing FRBR items of a Manifestation are byte-per-byte identical to each other, it is a natural consequence that it is not abstractly relevant which resolution engine dereferences the actual Item whose IRI is resolved out of a Work-level, an Expression-level, or a Manifestation-level IRI reference. This, in practice, means that protocol and authority are not contributing information to the resolution, and are thus interchangeable. Parties interested in absolute IRIs for Akoma Ntoso are required to produce their own resolution engine and use its protocol and authority for the purpose.

Another distinction is between global and local IRI references [3] . A global IRI reference is a relative IRI reference where all parts are present except for protocol and authority (i.e., domain name). Thus, a global IRI reference always starts with a slash, to indicate that all other parts are explicitly specified. A local IRI reference, on the other hand, may have one or more parts missing (necessarily from left to right), and the corresponding global (and, subsequently, absolute) IRI reference is determined by adding the corresponding parts taken from the base document, as usual with relative IRI references with missing parts. In the following we will call all IRI references as simply IRI (they are all references, after all), and distinguish between absolute IRIs, global IRIs and local IRIs.

In XML manifestations of Akoma Ntoso documents, all Work, Expression, and Manifestation-level references to whole documents must be global , and all references to individual components within the same level (or lower levels) must be local and are stored simply as the name of the corresponding component.

Thus, for instance, "/akn/kn/act/2015-01-01/1/!schedule_1" is the relative, global Work-level IRI for schedule 1 of act 1/2007 of Kenya. However, a Work-level reference to schedule 1 placed within the main document of the act will only contain the local IRI "1/!schedule1". This guarantees that these references continue to work even after new expressions are created of the same Work, either if the part containing the reference is changed or if it remains untouched.

Akoma Ntoso XML elements refer to other documents according to different levels of the FRBR hierarchy. In particular, < ref>, <mref>, and <rref> point to Work-level and occasionally Expression-level IRIs only, while < object>, <img>, and <attachment> always point to Manifestation-level IRIs. As the global/local distinction is involved, < ref>, <mref>, and <rref> elements always use global IRIs for documents different than the host, while < img> or <attachment> always refer to components of the host document, and thus always use local references.

In the Akoma Ntoso Naming Convention, a reference to a different document is always global:

< ref href="/akn/kn/act/2015-08-10/123/! main ~ sec_12" > section 12 of act 13/2006 < /ref >

This means that whenever referring to a different document it is necessary to provide the full list of identification parts even when they are identical to the ones of the base document. On the other hand, local IRI references are used in the Akoma Ntoso naming convention for references to components or fragments, and implicitly make use of the identification parts of the base document for the correct resolution of the IRI reference.

Global IRI references are discussed in sections 4.4 through 4.8, while local IRI references are discussed in section 4.9.

4.4 Resolving Akoma Ntoso IRI references​

The Akoma Ntoso naming architecture is built so as not to rely on the existence of a single storage architecture, since the IRIs stored within documents are differentiated from the ones physically representing the resource being sought.

The mapping from architecture-independent IRIs into accessible architecture-dependent URLs (representing the best Item for the document being sought) is realized through specific applications called IRI resolvers . The Akoma Ntoso naming architecture is built so as not to rely on the existence of any individual IRI resolver, but assumes that all IRIs are always correctly resolved to the best available Item regardless of the resolving mechanisms. In fact, each naming authority is given the global task of resolving any possible Akoma Ntoso IRIs, regardless of whether it belongs or not to the country or countries managed by the naming authority. This implies that the authority-specific details of IRIs are purposefully omitted in this specification, and need to be considered only when first accessing a document.

For this reason, all IRIs in this specification are prefixed with the arbitrary domain name [http://www.authority.org] that stands for any of an arbitrarily large number of equivalent naming authorities.

The IRI reference for the Work is the baseline for building the IRI reference for the Expression (section 4.5), which is the baseline for the IRI reference of the Manifestation (section 4.6). Additionally, all IRI references can be enriched with information about the component and the fragment requested (section 4.8). IRI references for items are beyond the scope of this Naming Convention.

4.5 The IRI reference of a Work​

The IRI for the Work consists of the following pieces, separated by forward slashes “/”:

  • The base URL of a naming authority with IRI-resolving capabilities (not relevant for the Naming Convention) . In all our examples this will always be described as [http://www.authority.org] , as explained in section 4.3.

  • A detail fragment that organizes additional data in a hierarchical fashion:

– The /akn prefix to allow the identification of the IRI as belonging to the Akoma Ntoso Naming Convention (required)

– Country or subdivision (a two-letter or code according to ISO 3166-1 [ISO3166] or a short and unique alphanumeric codes according to ISO 3166-2 [ISO3166-2] ). For an Akoma Ntoso XML representation, this value MUST correspond to the content of the element <FRBRcountry> in the metadata. (required)

– Type of document. For an Akoma Ntoso XML representation, this value MUST correspond to the element immediately below the akomaNtoso root element (e.g., act, bill, or debateReport.) (required)

– Any specification of document subtype, if appropriate. For an Akoma Ntoso XML representation, this value MUST correspond to the content of the element <FRBRsubtype> in the metadata or, in its absence, to the “name” attribute of the document type (optional).

– The emanating actor, unless implicitly deducible by the document type (e.g., acts and bills do not usually require actor, while ministerial decrees and European legislation do). For an Akoma Ntoso XML representation, this value MUST correspond to the content of the element < FRBRauthor> in the <FRBRWork> section of the metadata (optional).

– Original creation date (expressed in YYYY-MM-DD format or just YYYY if the year is sufficient for identification purposes). For an Akoma Ntoso XML representation, this value MUST correspond to the content of the element <FRBRdate> in the <FRBRWork> section of the metadata (required).

– Number or title or other disambiguating feature of the Work (when appropriate, otherwise optionally the string nn ). For an Akoma Ntoso XML representation, this value MUST correspond to the content of element <FRBRnumber> or <FRBRname> , respectively, in the metadata (required when necessary for disambiguation, optional otherwise).

– Component and fragment specifications, as specified in sections 4.7 and 4.8 (optional)

For example:

4.6 The IRI reference of an Expression​

Characterizing the Expression is the specific identification of the features of the content. This includes specifications of the version and the language of the Expression. Therefore, different versions of the same Work, or the same version of the same Work expressed in different languages correspond to different Expressions and will have different IRIs. Expressions are organized in components (the ExpressionComponents), and therefore we need to identify separately the Expression as a whole from the individual IRIs for each ExpressionComponent. All of them are all immediately derived from the baseline, which is the IRI for the Work.

4.6.1 The IRI for the Expression as a Whole​

The IRI for the Expression as a whole consists of the following pieces:

  • The IRI of the corresponding Work as discussed in section 4.4

  • The character “/”

  • The human language code in which the Expression is drafted (a three-letter code according to ISO 639-2 alpha-3). For an Akoma Ntoso XML representation, this value MUST correspond to the content of the first element < FRBRlanguage> in the metadata section. According with ISO 639-2 alpha-3 “mul” means multilingual document (text with different languages), while “und” means undetermined language

  • The “@” character (required)

  • Zero or more semicolon-separated version identifiers as follows:

  • If an approved act, the version date of the Expression in syntax YYYY-MM-DD. For an Akoma Ntoso XML representation, this value MUST correspond to the content of element < FRBRdate> in the < FRBRExpression> section of the metadata. If appropriate, the date can be integrated with a time using values for the XSD:dataTime datatype: Thh:mm:ss±hh:mm. The difference between the local time and Coordinated Universal Time (UTC) is specified using the sign + or - followed by the difference from UTC represented as hh:mm (note: the minutes part is required). See ISO 8601 Date and Time Formats and XML Schema Part 2: Datatypes ( http://www.w3.org/TR/xmlschema-2/ ).

  • If any other document, the presentation date is appropriate, or the version number if one exists, or any other disambiguating string that helps identifying the specific version of the document. For an Akoma Ntoso XML representation, this value MUST correspond to the content of element <FRBRversionNumber>

  • Any content-specification date (as opposed to validity dates) (optional).

  • Any content authoring information to determine the authoriality of the text content (optional). This is separate and independent of the authoring information relative to the metadata and markup, which are among the features of the Manifestation (optional). For an Akoma Ntoso XML representation, this value MUST correspond to the content of element <FRBRauthor> in the < FRBRExpression> section of the metadata.

The absence of the version identifiers signals two different situations depending on the type of document:

  • If the document is not versioned (e.g., the debate record of an assembly) then version identifier need not and cannot be present.

  • If the document is versioned (e.g., an act in force), then the lack of version identifiers refers to the version in force at the moment of the resolution of the IRI (i.e., the “current” version of the act, where “current” refers to the moment in time in which the IRI is dereferenced, rather than the moment in time in which the document containing the IRI was created: today for the reader, as opposed to today for the author of the references).

A particular Expression is the first version of a Work. This Expression should not be confused with the Work itself (which considers the first Expression in no special way to all other possible expressions), and it is a very specific, although peculiar, Expression. The first version of an Expression is referred to with an IRI with a dangling "@" character (which implies that the actual version date is the first appropriate date for that Work).

  • [http://www.authority.org] /akn/dz/debaterecord/2004-12-21/nn/fra Algerian parliamentary debate record, 21st December 2004, French version, with nn optional undefined number.

  • [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng Sierra Leone enacted Legislation. Act number 2 of 2004. English version, current version (as accessed today [according to the reader])

  • [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@ Sierra Leone enacted Legislation. Act number 2 of 2004. English version, original version

  • [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@2004-07-21 Sierra Leone enacted Legislation. Act number 2 of 2004. English version, as amended on July 2004

  • [http://www.authority.org] / /akn/uy/bill/ejecutivo/carpeta/2005-04-04/137-2005/esp@2005-05-02T13:30:00-03:00 Uruguay bill. Number 137-2005, at 2005-04-04. Spanish version, as amended on May 2 nd , 2005, at 10.30 Montevideo time.

  • [http://www.authority.org] /akn/ng/bill/2003-05-14/19/eng@first Namibia Bill number 19 of 2003, first version, English version

  • [http://www.authority.org] /akn/mg/act/2003-03-12/3/mul Madagascar. Act 3 from 2003, current version (as accessed today [according to the reader]) in multilingual text (in this case, French and Malagasy).

  • [http://www.auth.org] /akn/sl/act/2004-02-13/2/eng@2004-07-21/officialpublisher Sierra Leone enacted Legislation. Act number 2 of 2004. English version, as amended on July 2004. Official version. Emitted by publisher body.

  • [ http://www.authority.org] /akn/ eu/bill/DIR/ CONSIL /2013/COM(2013)344/eng@ final_2 Proposal for an European directive of the Council – English variant, version “final/2”.

  • [ http://www.authority.org ] /akn/uy/act/2008-08-11/18331/esp@2009-12-12;2010-01-01~art_3__para_5__point_c Act of Uruguay n. 18331 in the version of 2009, Dec 12, with a retroactive modification happened in 2010.

4.6.2 The IRIs for Virtual Expressions​

In some situations, the information such as the actual enter-in-force date or the language of an Expression is not known in advance, or it is necessary to create references or mentions of documents whose features are now known completely (possibly, because their exact delivery date is not known yet). These are called virtual expressions (i.e., references to expressions that probably do not exist yet or ever, but can be unambiguously deduced once all relevant information is made available.)

There are at least three cases where such a situation may arise:

  1. The information is not known by the author of the reference (e.g., the legislator), in which case the act of actually retrieving the correct information is in itself an act of interpretation.

  2. The information is not known by the editor of the text containing the reference (e.g., the publisher of the XML version of the document), in which case the information can theoretically be available, but is too much of a burden for the publisher to retrieve it.

  3. The information is not known by the query system when evaluating the reference.

In these cases, the syntax for the IRI of the virtual Expression uses a similar syntax to the specification of the actual Expression, but the character “:” is used before each unknown value and instead of the “@” at the end of the specification of the Work-level IRI. For instance, if we need to reference the Expression of an act in force on date “1/1/2007”, we will probably need to refer to some Expression whose enter in force date was in a previous date to 1/1/2007.

– [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng:2007-01-01 Sierra Leone enacted Legislation. Act number 2 of 2004. English version, as amended on the closest date before January 1st, 2007

– [http://www.authority.org] /akn/eu/act/2004-11-13/87/und:2015-01-10 European Directive number 2004/87/EC of 2004. All the language versions, as amended on the closest date before January 10, 2015

Similarly, if we need to refer dynamically to the expressions in German of a specific act, we need to make a virtual reference whose date is left unspecified, and the language is forced to be German, as follows ( deu is SO 639-2 alpha-3 code for German).

– [http://www.authority.org] /akn/ch/act/2009-05-09/432/deu: Swiss enacted Legislation. Act number 432 of 2009. Dynamic reference to any of the German versions.

– [http://www.authority.org] /akn/it/act/2005-03-07/82/eng:2010-01-01->2015-12-31 Italian enacted Legislation. Act number 82 of 2005-03-07. Dynamic reference to any of the Italian versions valid within the interval January 1 st 2010 to December, 31 st 2015.

4.7 The IRI reference of a Manifestation​

Characterizing the Manifestation is the specific process that generates an electronic document in a specific format. This includes specifications of the data format used. Therefore, different Manifestations of the same Expression generated in different data formats will have different IRI references.

All of them are all immediately derived from the baseline, which is the IRI for the Expression.

The IRI for the Manifestation as a whole consists of the following pieces:

  • The IRI of the corresponding Expression as a whole

  • The markup authoring information (useful to determine the authoritativeness of the markup and metadata) (optional). For an Akoma Ntoso XML representation, this value MUST correspond to the content of element <FRBRauthor> in the <FRBRManifestation> section of the metadata.

  • Any relevant markup-specific date (optional). For an Akoma Ntoso XML representation, this value MUST correspond to the content of element <FRBRdate> in the <FRBRManifestation> section of the metadata.

  • Any additional markup-related annotation (e.g., the existence of multiple versions or of annotations.) (optional)

  • The character “.” (required)

  • A unique three or four letter extension signifying the data format in which the Manifestation is drafted (required). For instance, such extension can be “pdf” for PDF, “doc” or “docx” for MS Word, “htm” or “html” for HTML “xml” for an XML Manifestation, or “akn” for the package of all documents including XML versions of the main document(s) according to the Akoma Ntoso vocabulary. For an Akoma Ntoso XML representation, this value MUST correspond to the content of element <FRBRformat> in the <FRBRManifestation> section of the metadata.

Some examples:

– [http://www.authority.org] /akn/dz/debaterecord/2004-12-21/fra@.doc Word version of the Algerian parliamentary debate record, 21st December 2004, Original French version

– [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng.pdf PDF version of the Sierra Leone act number 2 of 2004, English version, current version (as accessed today)

– [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@2004-07-21.akn Package of all documents in Akoma Ntoso XML of the Sierra Leone act number 2 of 2004. English version, as amended in July 7th 2004.

– [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@2004-07-21/CIRSFID/2011-07-15.akn Package of all documents including XML versions of the Sierra Leone enacted Legislation. Act number 2 of 2004. English version, as amended in July 2004. Rendered in Akoma Ntoso by CIRSFID on 15 July 2011.

4.8 Specifying components and portions​

Referring to within-documents destination is possible by adding to a whole-document reference an additional item pointing to the specific destination. Within this specification we distinguish between components and portions .

Some documents are made of many components; some are only composed of a main document. Within each component, structured portions can be localized and referred to by means of identifying information. Legal citations often point to a specific portions of the abstract document, as in “Article 3 of Directive 2003/87/EC”.

In order to explicitly refer to individual components and portions, it is therefore necessary to introduce a naming convention that identifies them, and allows an easy connection between the component and the document it belongs to.

Components and portions are a way to organize content. As such, they are naturally Expression-level concepts, which is where content is actually expressed and structured. Yet, it is sometimes appropriate to refer to components and portions in Work-level references, and therefore a syntax for these situations is provided. For instance, consider an original act that refers to table A of schedule 1. After a little time, schedule 1 is completely abrogated and table A thus becomes (implicitly) an attachment of the main document. As such, it is important that all references to table A of schedule 1 are considered as references to table A of the main document after that event. This brings about the necessity to have IRIs for Work Components. These are to be used when referring in a Work-level style to components that have official names and positions, but may change in name and position with time.

Components and portions are specified at the end of the IRI for Work-level and Expression-level references, and just before the data format for Manifestation-level references. They are introduced by a special character to separate the parts of the IRI reference identifying the document as a whole from the parts identifying the component and/or portion.

4.8.1 Specifying components in IRI references​

A Work-level IRI reference including a component specification consists of the following pieces:

  • The IRI of the corresponding Work as a whole

  • The character “/”

  • The character “!” and

  • Either:

– The name “main” if the component is the only component or the main component in a hierarchy

– A unique name for the attachment, optionally followed by the number associated to this component in the document. If this number is provided, it is separated from the name with “_”.

For instance:

– [http://www.authority.org] /akn/kn/act/2007-01-01/1/!main Kenya, main document of act 1, 2007

– [http://www.authority.org] /akn/eu/act/DIR/2014-03-01/16/!annex_1 annex 1 of the European directive 16 of 1 March 2014

An Expression-level IRI reference including a component specification consists of the following pieces:

  • The IRI of the corresponding Expression as a whole

  • The character “/”

  • The character “!” and

  • Either:

– The name “main” if the component is the only component or the main component in a hierarchy

– A unique name for the attachment, optionally followed by the number associated to this component in the document. If this number is provided, it is separated from the name with “_”.

For instance:

– [http://www.authority.org] /akn/dz/minutes/2004-12-21/nn/fra/!main

– Algerian parliamentary debate record, 21st December 2004, French version, main document, current version

– [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@/!main Main body of the Sierra Leone enacted Legislation. Act number 2 of 2004. English version, original version

– [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@2004-07-21/!schedule_1 Attachment “schedule 1” of Sierra Leone enacted Legislation. Act number 2 of 2004. English version, as amended on July 21 st , 2004

In order to allow the specification of the data format of a Manifestation to be the last item of the IRI as usual in web addresses, Manifestation-level IRI references are built differently than Work-level and Expression-level IRI references.

In fact, a Manifestation-level IRI reference including a component specification consists of the following pieces:

  • The IRI of the corresponding Manifestation as a whole, minus the “.” and the specification of the format,

  • The character “/”

  • The character “!” and

  • Either:

o The name “main” if the component is the only component or the main component in a hierarchy o A unique name for the attachment, optionally followed by the number associated to this component in the document. If this number is provided, it is separated from the name with “_”.

  • The character “.” (required)

  • A unique three or four letter extension signifying the data format in which the Manifestation is drafted (required). For instance, such extension can be “pdf” for PDF, “doc” or “docx” for MS Word, “htm” or “html” for HTML “xml” for an XML Manifestation, or “akn” for the package of all documents including XML versions of the main document(s) according to the Akoma Ntoso vocabulary. For an Akoma Ntoso XML representation, this value MUST correspond to the content of element < FRBRformat> in the < FRBRManifestation> section of the metadata.

For instance:

  • [ http://www.authority.org] /akn/it/bill/2004-02-13/C245/ita@2/official/2004-02-15/publisher/!annex_1.pdf Italian bill number C245 as of 2004-02-13, second version, official expression, manifestation released on 2004-02-15 by publisher in pdf format.

4.8.2 Hierarchies of components in component specifications​

A frequent situation occurs when an attachment has itself further attachments. This creates a complex hierarchical situation in which the component should be considered, in a way, as a document by itself, composed of components which need to be listed and properly differentiated. The process is further iterated whenever its attachments also have further attachments and so on. The situation must also foresee the situation in which attachments at different levels of the hierarchy end up having the same name (e.g., table A in schedule 1 and table A in schedule 2).

In such situations, each component must be considered as a document by itself. Recursively, the specification of components in IRI references are as follows:

  • If the component does not have attachments, its IRI reference is determined as detailed in the previous sections, without further additions.

  • If the component has attachments, the IRI reference detailed in the previous sections is meant to refer to the component as a whole, including its attachments.

  • To refer to the main document of a component that has further attachments, an additional “/main” part is specified.

  • To refer to any further attachment of component, a further “/” followed by a unique name for the attachment is added.

Some examples:

– [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@2004-07-21/!main/schedule_1 and equivalently [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@2004-07-21/!schedule_1 Attachment “schedule01” of the Sierra Leone Act number 2 of 2004. English version, as amended on July 21 st , 2004.

– [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@2004-07-21/!main/schedule_1/main and equivalently [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@2004-07-21/!schedule_1/main Main component of the attachment “schedule01” of Sierra Leone Act number 2 of 2004, English version, as amended on July 21 st , 2004.

– [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@2004-07-21/!main/schedule_1/table_A and equivalently [http://www.authority.org] /akn/sl/act/2004-02-13/2/eng@2004-07-21/!schedule_1/table_A Attachment “Table A” of attachment “schedule01” of Sierra Leone act number 2 of 2004, English version, as amended on July 21 st , 2004.

– [http://www.authority.org] /akn/eu/debate/2004-02-13/2/mul@/ ! main Main document of the European parliament debate report number 2 of 2004, containing multiple languages, original version

– [http://www.authority.org] / akn/ /eu/bill/DIR/consil/2013/COM(2013)366/eng@ second/ ! annex_1 Annex 1 of the proposal for a Council directive, second version.

4.8.3 Describing Components in the Akoma Ntoso Package Manifestation​

The Akoma Ntoso package Manifestation is a very specific Manifestation using a number of data formats (mainly XML but other multimedia formats could be present as needed) with a very specific organization of parts and components. Since it makes explicit choices in terms of data formats and reciprocal references, it is important to provide clear and non-ambiguous rules as to the internal naming mechanism and its overall structure. An Akoma Ntoso package manifestation is a package composed of one or more files organized in a flat fashion. The transportable format is a ZIP file whose extension is “.akn”. Other formats are possible and acceptable as long as they adhere to these rules.

The following are alternative options for the Akoma Ntoso package:

  1. If the document is just composed of text and does not refer to any multimedia fragment of any form, then the ZIP package contains a single document called “main.xml”.

  2. If the document is composed of many Manifestation-level components but does not refer to any multimedia fragment of any form, then the zip package is composed of many XML files, one for each Expression-level component . Each Manifestation-level component is then called as its corresponding Expression-level component, plus the “.xml” extension. The name “main” is reserved for the main component. Numbers are never used except when they are already part of the Expression-level component’s name.

  3. If the document contains multimedia fragments of any kind, these fragments do not have a corresponding Expression-level component, but are just Manifestation-level components specified in “src” attributes, for instance in < img> elements. All multimedia components MUST be stored within an inner structure (e.g., a folder) called “media”. Multimedia components can be called freely, but MUST use the appropriate extension to refer to their content type. Thus a logo can be called “logo.tif” or any other name, as long as the extension is correctly specifying the content type.

Reciprocal references to Manifestation-level components are necessary within a specific Manifestation. For instance, the Manifestation of the main document refers to the manifestations of its attachments via the < attachment> elements, and the schedule showing an image refers to the file of the image via the < img> element. In these cases, all references MUST be relative to the package (i.e., the Manifestation as a whole):

  • attachment1.xml Manifestation of the first attachment of the current document

  • schedule3.xml Manifestation of the third attachment of the current document

  • media/logo.tif Manifestation of an image within the current document

4.8.4 Specifying portions​

A portion is a specific document type in Akoma Ntoso XML, that contains a only a part of a whole document. Portion documents are used when the full document is large, and only a smaller part is necessary, such as a few sections or articles.

Requesting a portion is therefore only appropriate for Akoma Ntoso XML Manifestations, and is not guaranteed to be supported by all servers. A request for a portion therefore MUST return a manifestations containing at least the requested part, but possibly containing much more than the requested part, up to and including the whole document the part belongs to.

In an Akoma Ntoso IRI reference, the specification for the portion of a document is introduced by the special character “~”.

Therefore, a Work-level IRI reference (or an Expression-level IRI reference) including a portion specification consists of the following pieces:

  • The IRI of the corresponding Work (or, respectively, of the corresponding Expression) as a whole,

  • The character “/” (required),

  • A specification of the component according to section 4.7.1 (optional),

  • The character “~” (required),

  • Either:

– The eId of the element containing the subtree being requested, or

– A pair of eIds of the first and last elements of the sequence of parts being requested, separated by a dash “->“.

In order to allow the specification of the data format of a Manifestation to be the last item of the IRI as usual in web addresses, Manifestation-level IRI references are built differently than Work-level and Expression-level IRI references.

In fact, a Manifestation-level IRI reference including a portion specification consists of the following pieces:

  • The IRI of the corresponding Manifestation as a whole, minus the “.” and the specification of the format,

  • The character “/” (required),

  • A specification of the component according to section 4.7.1 (optional),

  • The character “~” (required),

  • Either:

– The eId of the element containing the subtree being requested, or

– A pair of eIds of the first and last elements of the sequence of parts being requested, separated by a dash “->“.

  • The character “.” (required)

  • A unique three or four letter extension signifying the data format in which the Manifestation is drafted (required). For instance, such extension can be “pdf” for PDF, “doc” or “docx” for MS Word, “htm” or “html” for HTML “xml” for an XML Manifestation, or “akn” for the package of all documents including XML versions of the main document(s) according to the Akoma Ntoso vocabulary. For an Akoma Ntoso XML representation, this value MUST correspond to the content of element < FRBRformat> in the < FRBRManifestation> section of the metadata.

For instance:

  • [http://www.authority.org] /akn/eu/act/2003-11-13/87/!main ~ art_3 The portion containing article 3 of the Work of the European Directive 2003/87/EC

  • [http://www.authority.org] /akn/eu/act/2003-11-13/87/eng@/!main ~ art_3 The portion containing article 3 of the Expression of the European Directive 2003/87/EC in English

  • [http://www.authority.org] /akn/eu/act/2003-11-13/87/eng@2015-01-20/!main ~ art_3 ->art_5 The portion containing article 3 to article 5 of the Expression of the European Directive 2003/87/EC in English at the version dated 2015-01-20

  • [http://www.authority.org] /akn/eu/act/2003-11-13/87/eng@2015-01-20/!main/schedule_1 ~ art_3.xml The portion containing article 3 of schedule 1 of the XML Manifestation of the European Directive 2003/87/EC in English at the version dated 2015-01-20.

When the component is the main component of the document, the “!main” part can be omitted. So the following IRIs are equivalent to the previous examples:

4.9 The IRI of an Item​

Akoma Ntoso makes no assumption about the physical storage mechanism employed to record actual manifestations. As such, there is NO rule for IRIs of the items, which are free to assume any form whatsoever and correspond to whatever storage mechanism has been employed locally.

On the other hand, the actual URL for the Item must be provided to a resolution mechanism in order for the hyper-textual feature of the Akoma Ntoso publication systems to work correctly and automatically.

4.10 Local IRI references​

A global IRI reference is a relative IRI reference where all parts are present except for protocol and authority (i.e., domain name). A global IRI reference always starts with a slash, to indicate that all other parts are explicitly specified. A local IRI reference, on the other hand, has one or more parts missing (necessarily from left to right), and the corresponding global (and, subsequently, absolute) IRI reference is determined by adding the corresponding parts taken from the base document, as described in RFC 3986.

In the Akoma Ntoso Naming Convention, a reference to a different document is always global. Local IRI references are used for references to components, portions or fragments, and implicitly make use of the identification parts of the base document for the correct resolution of the IRI reference.

There are three types of local IRI references in this specification:

4.10.1 Fragment references​

A fragment reference is composed of just the fragment part of the Akoma Ntoso IRI reference, according to the specification of RFC 3986. It is composed of the following parts:

  • The character “#” (required)

  • The eId of the element requested

For instance:

  • #art_5

As per RFC 3986, dereferencing this IRI reference does not imply making a request to the origin server. This request scrolls the current document so as to bring into view the part of the document whose eId has been requested.

The implication of using this type of local references is that the requested part of the document is already dereferenced and available at the client. On the other hand, any Akoma Ntoso document can contain this type of references.

4.10.2 Local component references​

A local component reference is composed of just the component part of the Akoma Ntoso IRI reference, according to the syntax in section 4.7.1. It is composed of the following parts:

  • The character “!” and

  • Either:

o The name “main” if the component is the only component or the main component in a hierarchy o A unique name for the attachment, optionally followed by the number associated to this component in the document. If this number is provided, it is separated from the name with “_”.

For instance:

  • !schedule_3

  • !main

Dereferencing this IRI reference implies making a new request to the origin server. The server may choose to return the requested component either as an autonomous document or as a component of a document collection document type.

The implication of using this type of local references is that the base IRI MUST already contain either the component or the portion part. It is unspecified and usually incorrect to use a local component reference in a document whose base IRI does NOT include a component or portion part.

4.10.3 Local portion references​

A local portion reference is composed of just the portion part of the Akoma Ntoso IRI reference, according to the syntax in section 4.7.4. It is composed of the following parts:

  • The character “~” (required),

  • Either:

– The eId of the element containing the subtree being requested, or

– A pair of eIds of the first and last elements of the sequence of parts being requested, separated by a dash “->“.

For instance:

  • ~art_5

  • ~sec_3->sec_5

Dereferencing this IRI reference implies making a new request to the origin server. The server MUST either return the requested part as a portion document type containing at least the part being requested, OR the full document or component containing the part being requested, even when they correspond to the current document.

The implication of using this type of local references is that the base IRI MUST already contain either the component or the portion part. It is unspecified and usually incorrect to use a local component reference in a document whose base IRI does NOT include a component or portion part.

4.10.4 Mixed local references​

It s always possible to combine the three different types of local references into a complex local IRI reference. For instance:

  • !main/schedule_1~art_3->art_5#art_4 a portion document containing at least the sequence from article 3 to article 5 of the component called schedule 1 of the current document. When dereferenced, scroll to article 4.

4.11 The IRI of Non-Document Entities​

The object of all discourses within the Akoma Ntoso framework can be described as a set of abstract classes and their instances and of the relationship among them. Cumulatively, definition of classes, relationships and instances are called an ontology .

The four most important classes of the Akoma Ntoso informal ontology (Work, Expression, Manifestation, and Item) are surely connected to documents, but many more exist, even if they are not connected directly to physical documents. The purpose of this section is to provide syntax for non-document entities (i.e., instances of non-document classes such as people, organizations, or concepts.) Furthermore, the syntax described here can also be used for document entities as an equivalent syntax to the one specified in the previous sections.

Akoma Ntoso entities are always associated to a class, providing a structure of properties and relationships to other instances of the same and other classes. Classes in the Akoma Ntoso informal ontology are organized in a complex maze of sub/superclasses. These are useful to give shape and meaning to a domain, and to provide structure to the overall set of instances of a base class. It is important to notice that sub/superclasses do not form necessarily a tree, but can form a more complex structure, namely a directed graph .

For instance, the class of Kenyan judges can be considered a sub class of both Kenyan persons and of persons whose job description is judge. That is, there is a (implicit or explicit) subclass of Judges and (implicit or explicit) subclasses of Kenyans, both of which are, in turn, subclasses of Person, and Kenyan Judges is a subclass of both. In fact, we immediately derive the principle that every different value in every different property or relationship implicitly generates a class, that turns into an explicit class only because of our whim or need. For instance, the class of all persons named “Joe” exists implicitly, identifies all persons whose first name is “Joe”, and, if so desired, can be made explicit through the definition of a subclass of Person.

While this is very useful for determining relationships between entities, it affects the mechanism to associate IRIs to such entities. In particular, being that there is no single hierarchy of classes, it is not appropriate to propose a single path of specifications from the super class to the final class. As such, ideally /person/judge/ken/JoeSmith must point to the same individual as /person/ken/judge/JoeSmith .

In order to maintain meaningfulness, permanence and invariance (which are the main requirements for our naming convention, as specified in the introduction of this document) we need to find a reliable naming mechanism for clearly identifying entities that does not depend on the sub/superclass organization except when strictly necessary.

In particular, we define the concept of Top Level Classes (TLC) that are guaranteed to be a partition of the overall domain of the Akoma Ntoso standard. TLC include Work, Expression, Manifestation, Item, Person, Organization, Concept, Object, Event, Process, Role, Term and Location. The list of TLC may, in the future, include more, as long as they keep on generating a partition (i.e., that they are disjoint and cumulatively describe all possible instance of the Akoma Ntoso domain). Members of the TLC classes can be subclassed at will and with no theoretical constraints.

Given the high number of foreseeable subclasses of the TLC, and the pointlessness of determining a fixed hierarchy in such number, the naming of entities should not depend on the presence or absence of a given class except for TLC. This means that it is necessary that each instance of each TLC is provided with an ID string that is guaranteed to be unique within the TLC. The syntax of this ID is dependent of the TLC class, and the syntax for each of the existing TLC is provided in the next section.

Therefore, the IRI for non-document entities consists of the following pieces:

  • The base URL of a naming authority with IRI-resolving capabilities

  • A detail fragment organizing in a hierarchical fashion the additional data:

– The /akn prefix to allow the identification of the IRI as belonging to the Akoma Ntoso Naming Convention (required)

– The string “/ontology”

– The official name of the appropriate TLC

– Any number (including none) of slash-separated subclasses of the TLC, as long as they all refer to correct properties of the corresponding instance

– The ID of the instance, guaranteed to be unique within the TLC.

All components are separated by forward slashes (“/”) so as to exploit relative IRIs in references.

– [http://www.authority.org] /akn/ontology/person/kn.joe.smith.1964-12-22 Joe Smith

– [http://www.authority.org] /akn/ontology/person/kn/kn.joe.smith.1964-12-22 Joe Smith (implying that he is a Kenyan)

– [http://www.authority.org] /akn/ontology/person/kn/judge/kn.joe.smith.1964-12-22 Joe Smith (implying that he is a Kenyan who is a judge)

– [http://www.authority.org] /akn/ontology/person/judge/kn/kn.joe.smith.1964-12-22 Joe Smith (implying that he is a judge who is a Kenyan)

– [http://www.authority.org] /akn/ontology/person/kenyanjudge/kn.joe.smith.1964-12-22 Joe Smith (implying that he is a Kenyan judge)

Please note that the classes Work, Expression, Manifestation, and Item belong to the ontology as much as the other classes. As such, each Work, Expression, and Manifestation can also be indicated with an ontology-based IRI that refers to exactly the same entity. Therefore, the following IRIs are equivalent pair-wise, and refer to the same entities:

– [http://www.authority.org]/ akn/sl/act/2004-02-13/2 [http://www.authority.org]/ akn/ontology/work/sl.act.2004-02-13.2

– [http://www.authority.org]/ akn/sl/act/2004-02-13/2/eng@2004-07-21 [http://www.authority.org]/ akn/ontology/expression/sl.act.2004-02-13.2.eng@2004-07-21

– [http://www.authority.org]/ akn/sl/act/2004-02-13/2/eng@2004-07-21!schedule_1 [http://www.authority.org]/ akn/ontology/expression.component/sl.act.2004-02-13.2.eng@2004-07-21!schedule_1

– [http://www.authority.org]/ akn/sl/act/2004-02-13/2/eng@2004-07-21.akn [http://www.authority.org]/ akn/ontology/manifestation/sl.act.2004-02-13.2.eng@2004-07-21.akn

4.11.1 The Identifiers for Top Level Classes​

As mentioned in the previous section, the hierarchy of path elements is of no use for identifying instances of each TLC, given the fact that there can be no unique hierarchy of subclasses in the Akoma Ntoso informal ontology. Thus, each instance of the ontology needs to be provided with an ID guaranteed to be unique within the TLC it belongs to. The syntax of the ID depends on the actual TLC, and is briefly explained in the following schema.

4.11.1.1 TLCPerson​

A dot-separated string composed of the country of citizenship, the first name, the family name, the birth date in yyyy-mm-dd format, and an optional arbitrary string if ambiguity exists (e.g., if two individuals with the same name and the same birth date exist in the same country).

– kn.joe.smith.1964-12-22 Mr. Joe Smith, the only Kenyan citizen with that name born on December 22nd, 1964

4.11.1.2 TLCOrganization​

A dot-separated string composed of the country of registration (or the string “ int ” if international, or the string “ unreg ” if not registered anywhere), a recognizable form of the organization name and an optional arbitrary string if ambiguity exists (e.g., if two organizations with the same name exist in the same country).

– kn.parliament the Kenyan Parliament

4.11.1.3 TLCConcept​

Concepts differ from terms as they refer to some concept regardless of the linguistic form used. For instance, "pope" and "pontiff" are different linguistic forms for the same concept, while "date" is a single linguistic form potentially referring to two different concepts (a calendar date as opposed to a type of fruit). TLCConcepts must be associated to a specific reference resource that disambiguates it. This must be an item of a thesaurus, of an encyclopedia, or of a commonly available dictionary. The identifier of the TLCConcept is a unique representation of the name of the concept joined with dots and preceded by an unambiguous name for the resource being used. No country specifications are necessary for concepts.

– wikipedia.Presidential.election the concept of Presidential Election as defined in Wikipedia.

4.11.1.4 TLCObject​

Objects must refer to a specific reference resource that can be used to disambiguate the object being referred to. This must be a thesaurus, an encyclopedia, or a commonly available dictionary. A unique form of the terms specifying the concept joined with dots preceded by an unambiguous name for the resource being used. No country specifications are necessary for objects.

– wikipedia.weapon a weapon (as a physical object) as defined in Wikipedia

4.11.1.5 TLCEvent​

Events must refer to a specific reference resource that can be used to disambiguate the object being referred to. This must be a thesaurus, an encyclopedia, or a commonly available dictionary. A unique form of the terms specifying the concept joined with dots preceded by an unambiguous name for the resource being used. No country specifications are necessary for events.

– wikipedia.world.war.ii The second World War as defined in Wikipedia

4.11.1.6 TLCLocation​

Places must refer to a specific reference resource that can be used to disambiguate the object being referred to. This must be a thesaurus, an encyclopedia, or a commonly available dictionary. A unique form of the terms specifying the concept joined with dots preceded by an unambiguous name for the resource being used. No country specifications are necessary for places.

– wikipedia.rome The city of Rome as defined in Wikipedia

4.11.1.7 TLCProcess​

Processes must refer to a specific reference resource that can be used to disambiguate the object being referred to. This must be a thesaurus, an encyclopedia, or a commonly available dictionary. A unique form of the terms specifying the concept joined with dots preceded by an unambiguous name for the resource being used. Country specifications are necessary for processes since processes with the same name may exist with different steps across different countries.

– wikipedia.kn.promulgation The promulgation as defined in Wikipedia and as carried out in Kenya.

4.11.1.8 TLCRole​

Roles must refer to a specific reference resource that can be used to disambiguate the object being referred to. This must be a thesaurus, an encyclopedia, or a commonly available dictionary. A unique form of the terms specifying the concept joined with dots preceded by an unambiguous name for the resource being used. Country specifications are necessary for roles since roles with the same name may exist with different characteristics across different countries.

– wikipedia.kn.speaker The role of the speaker of the house as defined in Wikipedia and as conceived in Kenya.

4.11.1.9 TLCTerm​

Terms differ from concepts as they refer to a linguistic form, rather than to the concept expressed by it. Therefore, for instance, "majority vote" and "mayoría de votos" are different linguistic forms in different languages for the same concept. TLCTerms must be associated to a specific reference resource that disambiguates it. This must be an item of a thesaurus, of an encyclopedia, or of a commonly available dictionary. The identifier of the TLCTerm is a unique representation of the words of the linguistic form joined with dots and preceded by an unambiguous name for the resource being used. No country specifications are necessary for terms, but a language reference is necessary for the correct attribution.

– eurovoc.eng.majority.vote The meaning of the majority vote as defined in Eurovoc and expressed in English.

4.11.1.10 TLCReference​

The domain-less IRI of the Work, Expression, Manifestation, as specified in this document, or the full IRI of the Item, with all slash substituted with dots.

  • sl.act.2004-02-13.2

Sierra Leone enacted Legislation. Act number 2 of 2004.

  • sl.act.2004-02-13.2.eng@2004-07-21

Sierra Leone enacted Legislation. Act number 2 of 2004. English version, as amended on July 2004

  • eu.bill.directive.CONSIL.2013.eng@ver_second European proposal for a Council directive. English variant in second version.

  • sl.act.2004-02-13.2.eng@2004-07-21.!schedule_1

Attachment “schedule01” of Sierra Leone enacted Legislation. Act number 2 of 2004. English version, as amended on July 2004

Package of all documents including XML versions of the Sierra Leone enacted Legislation. Act number 2 of 2004. English version, as amended in July 2004

The main document (in XML) of the Sierra Leone enacted Legislation. Act number 2 of 2004. English version, as amended in July 2004

4.12 Functionally Equivalent Naming Conventions (FENC)​

A functionally equivalent naming convention (FENC) is defined as follows:

  1. recognizable : a syntactical means exists to recognize the specific syntax used for the URI (e.g., a specific prefix);

  2. published : a sufficiently detailed description of the syntax is publicly available and backed by a recognizable institution;

  3. FRBR compliant : A full distinction between "distinct intellectual creations", "specific intellectual forms", "physical embodiments" and "exemplars" of relevant documents must be explicitly supported and aligned with the FRBR conceptualizations. Support for items is not necessary nor requested.

  4. active : at least one working, available, robust dereferencing mechanism (e.g., a URI resolver, a URI redirector or the standard URI resolution mechanism in HTTP) that provides for dereferencing of URIs/IRIs according to the specific syntax;

  5. equivalent : at least one working, accessible, available, robust mechanism must exist that converts URIs/IRIs according to the specific syntax into equivalent URIs/IRIs according to the Akoma Ntoso Naming convention;

  6. evident : Akoma Ntoso XML documents identifying themselves (in <FRBRUri> and <FRBRThis> elements) using a FENC URI must also: a. EITHER provide <FRBRalias> elements equivalent to the <FRBRThis> element, with URI references that use the Akoma Ntoso Naming Convention, one for each of the first three FRBR levels, b. OR treat as REQUIRED instead of optional the following elements (in their respective FRBRWork, FRBRExpression and FRBRManifestation containers): * FRBRdate, FRBRauthor, FRBRcountry, FRBRsubtype, and FRBRformat (always required); * FRBRnumber or FRBRname (at least one MUST be present); * FRBRversionNumber (REQUIRED if the FRBRdate in the Expression level does not exist); * FRBRportion (REQUIRED if the the document is split into portions). Any Naming Convention that complies with these requirements (items 1. through 6.) is termed a functionally-equivalent Naming Convention (FENC) and its URIs/IRIs can be used in any context where Akoma Ntoso URIs/IRIs are appropriate.