What is it
AKOMA NTOSO 1.0 Schema
Technical Documentation
Document Actions
5. Elements
|
AKOMA NTOSO 1.0 Schema
|
AKOMA NTOSO 1.0 strongly supports the idea of using semantically rich terms whenever a semantically justifiable text fragment exists in the document. This means that it is possible that users of AKOMA NTOSO in daily work will find the need for more elements than currently provided.
Generic elements come to aid in this respect. Whenever a new semantic is needed to describe a text fragment, a generic element of the appropriate content model is used instead, and the correct label is specified in the name attribute.
It is strongly discouraged to use presentation-oriented elements (such as b, i, etc.) elements to emphasize fragments that do have a semantic justification for being emphasized. Also, each text fragment need to be enclosed within the appropriate generic element according to its position and content model, which is the reason for there being five generic elements (one for each content model pattern).
Finally, an explicit equivalence is provided between named elements and generic elements: all named elements are just generic elements in disguise, the value of the name attribute having been upgraded to being the full element name. Therefore, for instance, <section> is absolutely equivalent to <hcontainer name=”section”>, or <noteref> is equivalent to <marker name=”noteref”>.
This is turn means that it is possible to reverse the approach, and, after a revision process, officially enrich the AKOMA NTOSO language with new elements that have been used in the past as values for the name attribute of generic elements.
Generic Elements
AKOMA NTOSO 1.0 strongly supports the idea of using semantically rich terms whenever a semantically justifiable text fragment exist in the document. This means that it is possible that users of AKOMA NTOSO in daily work will find the need for more elements than currently provided.
Generic elements come to aid in this respect. Whenever a new semantic is needed to describe a text fragment, a generic element of the appropriate content model is used instead, and the correct label is specified in the name attribute.
It is strongly discouraged to use presentation-oriented elements (such as b, i, etc.) elements to emphasize fragments that do have a semantic justification for being emphasized. Also, each text fragment need to be enclosed within the appropriate generic element according to its position and content model, which is the reason for there being five generic elements (one for each content model pattern).
Finally, an explicit equivalence is provided between named elements and generic elements: all named elements are just generic elements in disguise, the value of the name attribute having been upgraded to being the full element name. Therefore, for instance, <section> is absolutely equivalent to <hcontainer name=”section”>, or <noteref> is equivalent to <marker name=”noteref”>.
This is turn means that it is possible to reverse the approach, and, after a revision process, officially enrich the AKOMA NTOSO language with new elements that have been used in the past as values for the name attribute of generic elements.
HTML elements and CSS rules
AKOMA NTOSO uses a number of HTML elements for text fragments whose purpose is mainly presentation-oriented. These include paragraphs, lists, images, tables, and so on. Furthermore, as mentioned, even HTML elements have been made into the AKOMA NTOSO namespace, so as to simplify the namespace management.
Only a strict subset of the HTML language has been chosen, and no additional element can be added. In particular, headings (<H1>, <H2> and so forth) cannot be used in AKOMA NTOSO document, since they enforce a flat organization of sections, which is against the fundamentally hierarchical nature of AKOMA NTOSO documents. This is compatible with future developments of the HTML language, in particular considering that XHTML 2.0 will include nested hierarchies with <section> and <h> elements closely resembling AKOMA NTOSO <hcontainer> and <title> respectively.
All HTML elements have exactly the same nature and role as they have in HTML documents, with one exception: <div> is a generic container rather than a generic block as in HTML. This is due to the fact that a generic block already exist (<p>), and that in many automatically produced HTML documents (e.g., Open Office and MS Word), the <div> element is in fact used as a section separator (i.e., a container) rather than a paragraph.
The <div>, <p> and <span> elements can be considered as additional generic elements for the container, block and inline content models, and are in fact to be considered absolutely equivalent to <container>, <block> and <inline> elements, using the class attribute instead of the name attribute.
All HTML elements (and, in fact, all AKOMA NTOSO elements as well) can be optionally enriched with standard HTML core attributes allowing CSS styles with precise presentation instructions to be associated to them. The class and style attributes can be used as in HTML for external or internal CSS rules, liberally and without limitations on both HTML and AKOMA NTOSO elements.
Metadata elements
The meta section contains all the meta-information that needs or can be added to the actual content of the document. As a rule, all editorial content (i.e. content added by the editorial process out of Parliament rooms) need to be placed in the meta section, except for markup and note references. Vice versa, all actual content of the document need to have a place outside of the meta section in the appropriate content sections.
Meta elements are divided in eight subsections:
- Identification: Documents are considered as embodying characteristics from four different levels of characterization:
- Work: A normative act considered as the abstract collector associated to the set of provisions that can be described and named as a single entity, that was originally created by its originator (e.g. a Parliament) in a single creative process, and that is referred to in legal reasoning. Works are realized through expressions of versions.
- Expression or version: (one of) the realization(s) of a normative act in a specific collection of actual sentences and words and punctuation and (where appropriate) presentation choices. For instance, each consolidation of a national act is an expression of that normative act. Expressions are embodied in manifestations.
- Manifestation: one of the physical or electronic embodiments of an expression of a normative act. Thus, a specific XML representation, a PDF file (as generated by printing into PDF a specific Word file with a specific PDF distiller), a printed booklet, all represent different manifestations of the same version of the same normative act. Manifestations are exemplified by items.
- Item: each one specific exemplar of a manifestation: a very specific copy of a booklet, a file stored on a very specific computer in a very specific location, etc.
Each level is characterized by a number of metadata that are specific to that level. For instance, the author property is different when we are considering the abstract author of the work (possibly, the parliament) and the concrete author of the expression (the editorial staff with high legislative competences that created the actual text of the consolidation), the concrete author of the manifestation (the editorial staff with high technical competences that created the XML version of the expression) and the author of the item (who could simply be the person that created a copy of the file and put it on a web server). Analogously for dates (whose role can be further specified by the name attribute), components and URI addresses.
- Publication: details about the publication of the paper-based document.
- Classification: Keywords and descriptive information taken from closed vocabularies and thesauri.
- Lifecycle: the lifecycle element provides information about the events that the document has undergone. These events are always introduced and explained by external documents specified in the references element. Lifecycle is explained in section 9.
- Analysis: A number of metadata elements analyzing the semantic content of the document (provisions). These elements are characterized by scope. In the current release of Akoma Ntoso, only amendment provisions are analyzed. For each provision, several metadata characteristics can be expressed.
- References: the references element provides room for an open number of typed referenced to external entities. These include, depending on the kind of document, active and passive references to amendments affecting the document or to acts affected by the document, attachments, jurisprudence, as well as references to Top Level Classes of the Akoma Ntoso ontology such as people, roles, organizations that need to be specified with precision. References are explained in section 10.
- Notes: this subsection contains the text of the editorial notes that might be produced to comment and expand the actual text of the document. Note references inside the text point to notes contained here.
- Proprietary: this subsection allows any additional metadata to be specified in any order and vocabulary (provided it uses a different namespace than AKOMA NTOSO). Proprietary metadata can be used within a specific document management system to specify additional information useful for internal search and document management that is not worth standardizing and imposing across all AKOMA NTOSO implementations.
Identifiers
Identifiers are systematically used in AKOMA NTOSO. All AKOMA NTOSO elements allow an identifier. Many 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). Also 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 sections are numbered starting each time from 1, so “part 1” is not sufficient to clearly identify the actual part, while “article 12” clearly points to a single and well-specified element.
Each sub-identifier is composed of the 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 |
| <section> | secXX | Section 2 of this act | sec2 |
| <part> | prtXX | Part 1 of section 2 of this act | sec2-prt1 |
| <paragraph> | parXX | Paragraph 3 of part 1 of section 2 of this act | sec2-prt1-par3 |
| <chapter> | chpXX | Chapter 5 of paragraph 3 of part 1 of section 2 of this act | sec2-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 leading zeros are ever used. Elements with an explicit numbering mechanism in place (sich 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-cla3-mod1-art4a”. 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.
Amendments, versions and document lifecycle
AKOMA NTOSO 1.0 includes a sophisticated mechanism to keep track of the life cycle and evolution of a legislative document. This is particularly useful for acts that are amended and modified in time, while maintaining their fundamental nature.
The management of evolution of a document makes two very important assumptions:
- Amendments and events in the life cycle of a document (including original approval, final repeal and any other event affecting its presence in the law system or its content) happen in precise moments in time that can be determined objectively (albeit with difficulty) and attributed a specific date.
- Amendments and events in the life cycle are due to the enactment of a specific, individual document that can be objectively traced back and identified with an URI. If two different documents affect the same act on the same date, then these must be counted as two different and separate event on the amended act.
Handling events in AKOMA NTOSO centers around the <lifecycle> element in the meta section. This contains two containers, <events> and <references>, used to list the dates of all the events affecting a document, and the references to the URIs of all the documents generating these events. Each reference is provided with a required identifier, which is used by the event list to specify which document is responsible for which events. These elements must appear in all documents that have undergone two or more events (i.e., all acts except the ones that still have no amendments).
Documents in AKOMA NTOSO are organized in three main categories, as specified in the contain attribute of the document type element:
- OriginalVersion: this value reflects the fact that the content on the document is exactly the content that has been formally and explicitly approved by the relevant authority, with no amendments applied.
- SingleVersion: this value reflects the fact that the content of the document is an editorially modified version of the original act, according to one or more subsequent amendment acts. These amendment acts and the enactment dates of the amendments must be all present in the <lifecycle> element. Individual additions and deletions are not necessarily marked in the content.
- MultipleVersions: this value reflects the fact that the content of the document is the juxtaposition of fragments belonging to two or more different versions of the same act, each fragment marked as belonging to one or many of these versions. Thus in a MultipleVersions act there could be two or more copies of article 2, each associated to the date it started enactment and ended enactment.
The <lifecycle> element is a required element for all SingleVersion and MultipleVersion documents, and must be complete up to the enactment date of the latest document referenced in the <lifecycle> element (i.e., there can potentially be subsequent amendments non included in a SingleVersion or MultiVersion document, but all intermediate amendments must be correctly listed and referenced, even if they play no part to the displayed content). OriginalVersion documents need not have the <lifecycle> element, but surely can have it if the editors decide so.
In case a MultipleVersions document is being generated, each element and text fragment may be associated an enactment specification through the means of the three enactment attributes: start, end and status. Each fragment (a whole element if appropriate, otherwise a newly inserted <span> or <inline> element if no exact containing element exists) use these attribute to specify their nature.
The start and end attributes contain an URI to the ID of the event that has marked the beginning or the end of the enactment of the fragment. A start attribute with no end attribute marks a fragment that has appeared in an amendment and still exist in the latest recorded version of the document. An end attribute with no start attribute mark a fragment that was part of the original document but has been repealed before or at the latest recorded version of the document. The status attribute records the type of amendment of the fragment. The value “omissis” can only be used by private editors that want to display only part of the whole document. In this case, the structure must be complete anyway, but the actual content can be removed is the status=”omissis” attribute is present. The value “editorial” can be used to add fragments of text of editorial nature (i.e., that are generated by editors rather than authors). Examples include annotations and translated sentences. For instance:
<p xml:lang=”afr” id=”blk123”>Partye wat deel wil vorm van die proses van regering, is vol verligting. ``Sien,'' sˆ die Nuwe NP, ``die ANC is nie magshonger nie!'' Ryke ironie, komende van waar die Nuwe NP sit. <span xml:lang=”eng” status=”editorial”>(Translation of Afrikaans paragraph follows.)</span></p>
<p xml:lang=”eng” status=”editorial” refersTo=”blk123”>[Parties who want to form part of government are quite relieved. ``You see'', says the New NP, ``the ANC is not power-hungry!'' Such irony, if one considers where the New NP is sitting.]</p>