Patterns are the abstraction and distillation of past experiences in designing and resolving design problems. They are general and widely applicable guidelines for approaching and justifying design issues that often occur in XML-based projects.

We distinguish between patterns in content models (a restriction of content models to the ones that are actually useful) and patterns in schema design (guidelines on how to make a schema more modular, flexible and understandable by users). Both types of patterns are well known and well established in the literature, although by different experts in different ways. (For patterns in content models, we used our own resource as a source of guidelines, the document titled "Design patterns for document substructures", by F. Vitali, A. Di Iorio, and D. Gubellini, while the authoritative resource for patterns in schema design is www.xmlpatterns.com)

For Patterns in Content Models, the AKOMA NTOSO Schema uses systematically five of the 7 patterns described in  "Design patterns for document substructures". This means that all content models and complex types used in the schema follow precisely the form of the relevant pattern, and all elements can be simply described and treated according to their pattern rather than individually.

These patterns are:

1. The markers: markers are content-less elements that are scattered here and there in the document and are meaningful for their names as well as their attributes. Markers are also known in literature as empty elements or milestones. There are two main families of markers in the AKOMA NTOSO schema: placeholders in the text content (e.g., note references) that can appear in any position that also has text, and metadata elements that only appear in some subsection of the <meta> section. As discussed in the metadata section, all metadata elements are markers so that metadata values are not part of the text content of a document, but rather are attribute values.
2. The inlines: an inline element is an element placed within a mixed model element that identifies some text fragment as relevant for some reason. There are both semantically relevant inlines and presentation oriented inlines. There is but one content model using inlines (and markers), which means that all mixed model elements (i.e., those that allow both text and elements) also allow a repeatable selection of all inline elements. See at the end of this section for an explanation of why this is only a trade-off decision, and not the ideal solution.
3. The blocks: a block is a container of text or structures that is organized vertically on the display (i.e., has paragraph breaks) and can contain either substructures or text. Most blocks in AKOMA NTOSO are based on the HTML language. There is only one content model using blocks, and it allows a repeatable selection of all available blocks. This means that wherever a block is allowed (e.g., a paragraph), a table or a list is also allowed.
4. The containers: containers are sequences of specific elements, some of which can be optional. The corresponding pattern in "Design patterns for document substructures" is the record. Containers are all different from each other (as the actual list of contained elements vary), and so there is no single container content model, but rather a number of content models that share the record pattern.
5. The hierarchy: a hierarchy is a set of arbitrarily deep nested sections with title and numbering. Each level of the nesting can contain either more nested sections or blocks. The corresponding pattern in "Design patterns for document substructures" is the table. No text is allowed directly inside the hierarchy, but only within the appropriate block element (or, of course, titles and numbering). AKOMA NTOSO uses only one hierarchy, with predefined names and no constraints on their order or systematic layering.

There are three exceptions to the systematic use of patterns:

• The <li> element allows both inlines and other nested lists (<ul> and <ol>). The pattern would require <li> elements to contain only text, and nested lists to be direct children of the main list element (<ul>s within <ul>). Since this goes against universal HTML practice, we have decided against full pattern adherence and in favour of HTML tradition.
• The <mod> element allows quoted text and structures within its content. No problems for quoted texts, but when an amendment clause specifies in full a new structure (such as an article) within the main discourse, the full structure needs to be described, and it is thus possible to have an article within a paragraph within a clause, which is against the inline pattern. There is no simple way out of this issue.
• There are six inline elements that only make sense in the preface and preamble parts of the document: these are <ActTitle>, <ActNumber>, <ActType>, <ActProponent>, <ActDate> and <ActPurpose>. They are in fact part of the one inline content model and thus are available everywhere in the document. There is no simple way to define blocks within <preamble> and <preface> to allow these elements and paragraphs elsewhere to not allow them, so it is better to allow them everywhere rather than unnecessarily complicating the schema. In "Design patterns for document substructures", a direct solution to this issue is proposed (additive context, also known as inclusions), but in the current XML technology such a constraint would require validation using a different or additional language such as Schematron or SchemaPath, which constitutes a possible evolution of the AKOMA NTOSO project, but certainly not an immediate one.

For patterns in schema design, whenever there has been a design choice to be made that was not immediately obvious and naturally acceptable, a relevant pattern has been sought and properly used. You can find the relevant mentions within the schema itself, in comments and documentation.

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:);

2. blocks (a sequence of block elements - e.g., paragraphs) used within containers either with required or optional identifiers);
3. inline (the content model for all mixed model elements such as paragraphs);
4. marker (zero length elements characterized by their attributes) either with required or optional identifiers);
5. 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:

6. The root element <akomantoso> 

7. 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.  

8. 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.
9. 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.
10. Elements for parliamentary debates, particularly <subdivision>, <speech>, <question> and elements for open structures, particularly <item>.
11. 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). 

12. 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.
13. 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".
14. 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.

The AKOMA NTOSO Detailed Schemas are a number of specialized schemas (in both DTD and XML Schema) for all the document types of individual countries. As deemed necessary, they can include up to one schema for each relevant African country of each of the following document types:

1. act – Post Enactment Legislation
2. bill – Pre-Enactment Legislation
3. debate record – Parliamentary Debate Record
4. report – Parliamentary Order Paper
5. doc – Miscellaneous Parliamentary Document
6. judgement – Court's Judgements
   

Although customized to deal with the fundamental structures of the corresponding document types in each national parliamentary system, each AKOMA NTOSO DS contains a subset of the structures contained in the GS and therefore is completely upward compatible with it: all documents valid according to a specific DS is also valid according to the GS.