7 References — Site
Personal tools

Skip to content. | Skip to navigation

 
You are here: Home → Release Notes → AKOMA NTOSO 1.0 Schema → 7 References
 
Document Actions
Next: 8 Naming Conventions Previous: 6 Document Lifecycle  

All content on one page (useful for printing, presentation mode etc.)


7 References

Documents make references to external entities that need to be identified with clarity and no ambiguity. The current release of Akoma Ntoso includes a section where references to external concepts, people and places are specified. These include references to other Akoma Ntoso documents, to other  non-Akoma Ntoso documents that are accessible through the net, or to individual instances of classes specified in a local ontology.

7.1 The structure of references

All references to external concepts share the same structure, in that they are empty elements in the references section provided with exactly four attributes:

  • href: the URI describing the entity being referred to. This can be a whole document (for instance, the act containing amendments to the current document), or a fragment of a document (for instance, the identifier of the unique record identifying precisely the person being referred to in the document).
  • id: this is the string that identifies within the document the entity being described. All internal references will thus use this id. For instance, every event in the document lifecycle has a source attribute containing a reference to the id of the document affecting or being affected by the document. 
  • showAs: this is the string that can and must be used in displaying information about this entity. For instance, this attribute contains the name of the speaker as it must be displayed.
  • shortForm: this optional attribute contains a secondary form of the display information of the entity. For instance, in some reports it is necessary to provide the full name of a person at the first utterance, and only the name in any further utterance from the same person.

7.2 Referring to precise concepts in the document

 

AKOMA NTOSO provides a series of mechanisms for referring to precise concepts in the documents being marked up. Regardless of whether the textual content of the document is sufficiently explicit and unambiguous, the marker of the document may and should provide additional disambiguating information about individual pieces of fragment denoting precise concepts through the aid of the appropriate attributes.

This disambiguation happens systematically as a two-step process: first of all, a mention to the ontological concept is added to the references section and provided with an id, and then one or more attributes in the document elements are used to refer to it.

For instance, every individual in a debate is associated via the id to an element TLCPerson in the references section: the by attribute of the speech element indicates the speaker (this must be a TLCperson), the as attribute specifies the role of the speaker (which must ne a, if any (and it must be a TLCrole) and the to attribute indicates the addressee (this can either be a person or a role).

The following are the attributes used for this purpose:

  • refersTo: points to any instance of a Top Level Class of the ontology. It is used to notify the reader in a generic way to what specific concept is the element referring to.
  • href: contains the URI of a instance of an FRBR document class or of a web page. Furthermore, it signals the application that the reference must be considered navigable, i.e., activatable by the user (e.g. via a link).
  • upTo: for range references (e.g., rref and rmod) this specifies the URI of the last, or highest, element of the range being referred to.
  • by: points to a person, i.e., an instance of the class TLCPerson in the references section, relative to the person by which the content has been provided.
  • as: points to a role, i.e., an instance of the class TLCRole in the references, relative to the role held by the person when uttering the content.
  • to: points either to a role, a person or an organization, relative to the kind of addressee of the content being provided.

 

Thus, any fragment in the text content of the document referring to Events, Concepts, or other instances of the Top Level Classes need to use the refersTo attribute to point to the id of the corresponding element in the references section.

A few elements can be considered of some use:

  • The element entity provides a standard mechanism to refer to mentions of instances of Top Level Classes in the content of the document. Any instance of any class can be referred to via an instance element.
  • ref, mref, and rref provide a mechanism to refer to other documents in the Akoma Ntoso domain. These elements may use the refersTo attribute, but will most frequently directly use the href attribute to specify a navigable reference to the document they refer to. The element ref specifies a single reference, the element mref a group of references (a list of individual ref elements must be placed inside the mref element, one for each reference) and the rref element specifies a range of references delimited by the href and upTo attributes.
  • mod, mmod and rmod provide a mechanism to specify modifications to other documents. The mod element contains at least one ref element identifying the destination of the modification, and may contain as many quotedStructure and quotedText elements as needed providing the textual modification (if any) in terms of either whole structures or individual words. The element mod specifies a single modification, the element mmod a group of modifications (a list of individual mod elements must be placed inside the mmod element, one for each modification) and the rmod element specifies a range of modifications delimited by the href and upTo attributes.
  • The a element provides a mechanism to refer to web pages, e.g., the official home page of an organization. It should never be used for references to AKOMA NTOSO documents (that are only referred to via *ref elements).

 

The following inline elements may appear to be references, but are rather definitions:

  • date:  specifies that the content of the element is a date. Through the date attribute it is possible to provide the unambiguous form of the date in XSD 1.0 syntax (yyyy-mm-dd).
  • docDate, docType, docNumber, docProponent, docPurpose: specify that the content of the element provide information about a date, a type, a number, a proponent and a purpose of the document, respectively. The attribute refersTo may point to appropriate instances of the Top Level Classes accordingly. Attributes refersTo are required if there are more than ONE such element per type (e.g., a document may have TWO different docNumber or docDate elements, but they must be disambiguated via refersTo elements pointing to different instances of the TLCConcept class).
  • judge, party, lawyer specify the judge, party and lawyer associated to a judgement. These elements need to be used when the document introduces these individuals or organizations in a formal way. Any further reference to them should be done via the entity element. 

7.3 Identifiers

Identifiers are systematically used in AKOMA NTOSO. All AKOMA NTOSO elements allow an identifier. Most relevant elements and sections require it. Identifiers are the main way to identify fragments and parts of the document in an unambiguous form. They can be used in document references (e.g. links and amendment commands) as a precise pointer to the actual part of the document mentioned (as opposed to simply referring to a document as a whole). Even internal links need to use identifiers. 

The schema does not explicitly provide a syntax for identifiers, which is described here in human readable format. Identifiers are composed by juxtaposing subidentifiers of the path needed to access them. Legal documents provide explicit global numbering for sections and articles, and local numbering for hierarchical subparts of them. For instance, all parts in different structures are numbered starting each time from 1, so “part 1” is not sufficient to clearly identify the actual part, while base structures (such as <article>s or <section>s have global numbering, so that for instance “article 12” clearly points to a single and well-specified element.

Each sub-identifier is composed of three letters, plus a string or a number identifying its position within the overall list of similarly named elements. Blocks are all named “blkX”, regardless of their actual names, and inlines are all named “inlX”, regardless of their actual names. An exception to this are references “refX” and amendments “modX”.

The following is a table with some examples of identifiers:

Element Identifier Example Identifier of example

<book>

 secXX Book 2 of this act Bck2
<part>  prtXX Part 1 of section 2 of this act  bck2-prt1
<paragraph> parXX Paragraph 3 of part 1 of book 2 of this act bck2-prt1-par3
<chapter> chpXX Chapter 5 of paragraph 3 of part 1 of book 2 of this act bck2-prt1-par3-chp5
<article> artXX Article 12 art12
<clause> claXX Clause 3 of article 12 art12-cla3 
<li> itmXX item “c” of clause 3 of article 12 art12-cla3-itm3
<p> blkXX Third paragraph of clause 3 of article 1 art12-cla3-blk3

Identifiers never change even if and when the elements get officially renumbered. Insertions may add a character at the end of the identifier. So if an amendment creates an article “12/a” or “12 bis” between articles 12 and 13, then the relevant identifies will be “art12a” in both cases. No trailing zeros are ever used. Elements with an explicit numbering mechanism in place (such as member of the hierarchy) will display the number as written in the document (i.e., with no trailing zeros but will all decorations as present), while unnumbered elements will add the number required to make the count correct.

Structures within the <quotedStructure> elements add the relevant mod identifier before their “natural” identifiers. So for instance if clause 3 of article 15 has an amendment that adds article 4/a to a different act, the identifier of the <quotedStructure> element that contains the new article will be “art15-cla03-mod01-art04a”. Of course, automatic systems that create current versions of texts will remove the prefix belonging to the amendment law and will only keep the “art04a” identifier in the final result. 

7.4 Document URIs

All resources are identified by a unique name. Resources are categorized as Work, Expression, Manifestation and Item, and each of these categories has a different naming structure. The actual syntax of the resource is specified in the following section, the “AKOMA NTOSO Naming Convention”, which is an integral part of the AKOMA NTOSO standard.

 

Next: 8 Naming Conventions Previous: 6 Document Lifecycle