Personal tools

Skip to content. | Skip to navigation

 
You are here: Home → AKOMA NTOSO in detail → Schema → General Schema
 
We are in the process of updating this content to reflect changes to the latest release of AKOMA NTOSO!!!
Document Actions
Next: 5.3. AKOMA NTOSO Detailed Schemas Previous: 5.1. General Schema: Patterns and Content Models  

5.2. General Schema


5 Schema

5.1 General Schema: Patterns and Content Models

patterns are the abstraction and distillation of past experiences
5.2 General Schema

components of the general schema
5.3 AKOMA NTOSO Detailed Schemas

Specialized schemas for all document types of individual countries

All AKOMA NTOSO documents share the same root element <akomantoso>, under which the specific document type is selected. The single root element follows a specific design pattern "Universal root" aimed at better identification of the root and separation of namespace and schema declaration (available in the root) and meaningful attributes (available in the document type element).

Types, Attributes and Groups 

The schema starts with a few <group>s and <attributeGroup>s used throughout the schema for content models and types. They are followed by common simple types (mostly enumerations of string values) and complex types. Complex types in this section include those supporting four of the five main content model patterns used throughout this schema:

  1. hierarchy (a hierarchy of nested elements with number and titles as shown below:);
Fig. 1 The structure of the hierarchy content model


  1. blocks (a sequence of block elements - e.g., paragraphs) used within containers either with required or optional identifiers);
  2. inline (the content model for all mixed model elements such as paragraphs);
  3. marker (zero length elements characterized by their attributes) either with required or optional identifiers);
  4. container (the fifth content model pattern, has no common form, but lists different elements in different orders, and individual container-like complex patterns are spread throughout the schema. Content model patterns are described in the section "Content Models used in the General Schema");

Elements

After the previously described section of the schema, the next section contains Elements which are organized in meaningful sequence as follows:

  1. The root element <akomantoso> 
Fig.2 akomantoso root element

  1. The document elements, one for each document type (<act>, <bill>, <doc>, <report> and <minutes>), that share one of the three document formats: &HierarchicalStructure; (that has an explicit hierarchy inside), &OpenStructure;, that allows basically everything inside, and &DebateStructure;, a slightly hierarchical structure for minutes and reports.  
Fig. 3 AKOMA-NTOSO with act document type showing

  1. The container elements, one for each main part of the above mentioned structures, except for clauses, described next, and meta, described in the opposite section.
  2. The hierarchical elements, listing the main elements that are used in the full hierarchy of nested structures of acts and bills, as well as <title>s, <num>s and <subtitle>s.
  3. Elements for parliamentary debates, particularly <subdivision>, <speech>, <question> and elements for open structures, particularly <item>.
  4. AKOMA NTOSO specific block and inline elements, including the table of content (<TOC>), the normative reference (<ref>), the defined term in a definition (<def>) the note marker (<noteref>) pointing to an editorial note placed out of line (in the meta section), the recorded time of a spoken remark (<recordedTime>), the container for amendments (<mod>) and of two types of amendment quoted fragments: simple text fragments (such as a few words inside quotes) or full structures (such as an entire clause or article). 
Fig 4. An example of an inline element, the <ref> element


  1. Generic elements: the list of available generic elements (one for each of the five main patterns for content models), explained in detail in a separate section.
  2. HTML elements: the list of elements, directly derived from HTML, used to provide for presentation-oriented, rather than semantic-oriented, markup within AKOMA NTOSO documents. They form a very strict simplification of the HTML language, but allow for all many useful structures inside a legislative act. HTML elements and how to use them in AKOMA NTOSO are described in the section "HTML elements and CSS rules".
  3. Metadata elements provide a location for all relevant information about an AKOMA NTOSO document that does not belong to its actual content. Metadata thus are all, by definition, editorial additions to the text as originally composing the document. Metadata are described in a separate section.

In this release the AKOMA NTOSO 1.0 schema contains a full total of 129 elements, of which 59 specific to the AKOMA NTOSO vocabulary, 6 generic elements, 16 HTML elements, and 51 metadata elements.

Design details

Generic Elements

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.

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 should 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 needs to have a place outside of the meta section in the appropriate content sections.

All discourse and all description of legal sources can be characterized as referring to one of the four levels of a document as introduced by IFLA-FRBR (International Federation of Library Associations and Institutions-Functional Requirements for Bibliographic Records http://www.ifla.org/VII/s13/frbr/frbr.pdf)

  • WORK: the abstract concept of the legal resource (e.g., act 3 of 2005)
  • EXPRESSION: any version of the WORK (whose content is specified and different from others for any reason: language, versions, etc.)
  • MANIFESTATION: any electronic or physical format of the EXPRESSION: word, xml, Tiff, pdf, etc.
  • ITEM: physical copy of any manifestation in the form of a file stored somewhere in some computer on the net or disconnected.

These levels impact both on the metadata elements (each metadata element refers to one and only one level of the four) and the identifiers (each level is associated to a different identifier).

Meta elements are divided in eight subsections:

  • Identification: i.e., a set of information providing identification information about each of the four FRBR levels, such as authorship, delivery date and URI.
  • Publication: all metadata elements specifying publication information about the document, such as issue and date of the official gazette.
  • Classification: a set of keywords belonging to a specified vocabulary (typically, a thesaurus such as Eurovoc or similar) that describe the content of the document and each individual fragment thereof.
  • Lifecycle: information about the events that the document has undergone, and references to the documents that have caused these events. Lifecycle is explained in section 10.
  • Analysis: a set of analytical statements about the document. Currently, these only include information about active modifications (for amending documents) and passive modifications (for amended documents), but can in future expand to include detailed formal analysis of the contained provisions.
  • References: a set of references to external entities explicitly or implicitly mentioned in the document and in the metadata. These include both other documents (amending, amended, referenced, referencing acts) and instances of the AKOMANTOSO ontology.
  • 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.

The development of the meta section is not finished yet. For instance, support for Dublin Core metadata is currently imperfect (there are semantic equivalences between Dublin Core elements and AKOMA NTOSO elements, but they are not complete nor officially described as equivalent).

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.

Two kinds of identifiers are relevant to the schema:

  • Document URIs: A resource is identified by a unique name according to the naming convention specified in section XX.
  • Section identifiers: 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.
  • Other concepts dealt with the Akoma Ntoso 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).

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 events on the amended act.

Handling events in AKOMA NTOSO centres around the <lifecycle> and <references> elements in the <meta> section. The <lifecycle> element is used to list the dates of all the events affecting a document, while <references> contains 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:

  1. 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.
  2. 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.
  3. 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 IDREF 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 exists 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.
Next: 5.3. AKOMA NTOSO Detailed Schemas Previous: 5.1. General Schema: Patterns and Content Models