7. Document Architecture

Document Architecture

Baseline Conformance

The AKOMA NTOSO framework is composed of a number of schemas, files, and auxiliary data that compose the overall picture of an interoperable standard for accessing and exchanging parliamentary, legislative and judiciary documents.

Conformance to AKOMA NTOSO, on the other hand, does not mean rigid adoption of all and only these documents and data files. AKOMA NTOSO provides ample possibilities for local customization of systems, while maintaining overall ?open access? functionality.

In particular, AKOMA NTOSO provides the following conformance requirements:

AKOMA NTOSO General Schema: MANDATORY. All AKOMA NTOSO-conforming applications and systems need to handle correctly and completely the GS and the associated usage guideline.
AKOMA NTOSO Detailed Schema: OPTIONAL. Parliaments and emanating bodies that wish to enforce stricter constraints on published documents may decide to adopt or even create their own DS, as long as overall compatibility with the DS is maintained. The basic compatibility rule here is that all documents validated with the custom DS are also valid with the overall GS.
AKOMA NTOSO Metadata Common Set: MANDATORY. AKOMA NTOSO provides a list of fundamental metadata items that need to be filled in for every AKOMA NTOSO-compliant document. All systems and tools must handle correctly and completely the Core Set.
AKOMA NTOSO Metadata Document-specific Set: MANDATORY. The document-specific set contains a number of metadata elements that are descriptive of a specific document type. Thus they are required metadata whenever associated to the corresponding document type. All documents of a given type must contain all metadata of that particular document type. Conversely all tools and systems handling all document types need to be able to manage the whole set of options metadata items, and tools and systems handling specific document types must handle the document-specific set for that particular type.
AKOMA NTOSO Metadata Local Extensions: PARTIALLY OPTIONAL. Some documents types and some documents can contain metadata that does not belong to either the MCS or the MDS. In this case, all systems and tools, regardless of the level of support enforced, are required to keep without modifications the unknown metadata items. On the other hand, they are not required to know what they mean and to enact any specific behaviour to handle their content.
AKOMA NTOSO HTML stylesheets: OPTIONAL. AKOMA NTOSO provides a few sample XSLT and CSS stylesheets aimed at generating an HTML+CSS representation of the XML documents. These stylesheets are to be considered as examples and starting points for local customization of the presentation of the documents. They are in no way representative of the way document should be presented in AKOMA NTOSO-compliant systems (AKOMA NTOSO does not enforce any rule at all about the presentation on screen or paper of AKOMA NTOSO-compliant documents).

Markup Structures

The AKOMA NTOSO model deals with a rather complex situation of five document types and, eventually and hopefully, 53 African countries, by creating two classes of document types, the General Schema (GS) and several Detailed Schemas (DSs) that provide support for differences in document types. Interoperability across these schemas is granted by a generalized approach that maintains full descriptions of the element while unifying and limiting in scopes the structures. The theory of markup languages clearly distinguishes between the name (the label I can associate to a fragment of text) and the content model or type (the structural constraints associated to a name). Thus, for instance, if we decide to call a paragraph an "explanation" and another paragraph a "definition", they will have different names (i.e., "explanation" and "definition"), but will have the same model (i.e., they will both be "paragraphs", i.e., they will both contain text as well as inline styles such as bold or italic).

Complexity in XML software and XML document management arises in two different situations:

For tool implementers, when a large number of types increases the amount of code necessary for handling them in presentation, editing, etc.
For document encoders (e.g., in our case, the legal drafter) cannot find the most appropriate name or label to describe a document fragment and needs to choose between a varying number of imprecise and unsatisfying alternatives.

By clearly differentiating between names and types, AKOMA NTOSO simplifies the tasks (and the costs, too!) of toolmakers by considerably limiting the variety of types, yet maintains a full and expandable list of names for precise description of the actual meaning and role of each document fragment.

In fact, although there is no precise and definite number of names in the elements foreseen for AKOMA NTOSO documents, the types (or content models) that are associated to these names run along a small number of patterns; indeed, these patterns are exactly five, and can be determined by a very simple exam of their definition:

The marker: markers are content-less elements that are meaningful for their position within the text, for their names as well as for their attributes. 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.

The inline: an inline element is a container of text placed within a block to indicate some special semantic or structural characteristics associated to it. For instance, a reference, the speaker name and some official date within a larger text are all examples of inline elements, comparable to examples of bold or italic text within a paragraph. In the following example, both term and ref are inline elements contained, mixed with plain text, within a block.

The block: a block element is a container of text that stands autonomously and can contain inline elements. Examples of blocks could be paragraphs, clauses, headings, etc. In the following example, clause is a block containing both text and inline elements.

<clause>
<term>Commission</term> means the commission established by
<ref xhref="#sect20">section 20</ref>;
</clause>

The container: a container is a grouping element that collects elements of other types and gives them a cumulative name. It has no presentation requirements, but provides justification to other presentational elements. In the following example, act is a container element containing meta, preamble, sections and attachments. Although not shown in the example, meta, preamble and attachments are containers themselves, while section is a hierarchical container, as explained in the next bullet point.

The section, or hierarchical container: these are special containers that form a similarly named hierarchy of containment. They contain other hierarchical containers and possibly a numbering and a heading, down to the lowest level which is a plain container. In the following example, clauses, chapter, paragraph and clause are sections, while p is the lowest level container.

<clauses>
    <chapter id="chap2">
    <num>Chapter 2</num>
    <title>Traditional communities and ...</title>
    <paragraph id="chap2-para2">
        <num>2</num>
        <title>Recognition of traditional ...</title>
        <clause id="cla1">
            <num>1</num>
            <p>A community may be recognised as ...</p>
        </clause>
        ...
    </paragraph>
    ...
    </chapter>
    ...
</clauses>

Next: 8. Naming Conventions

Previous: 6.3. Other Metadata Initiatives

Personal tools

Document Actions

7. Document Architecture

Baseline Conformance

Baseline Conformance

Markup Structures

Markup Structures