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 general schema and the associated usage guideline.
  • Akoma Ntoso customized Schema: OPTIONAL. Parliaments and emanating bodies that wish to enforce stricter constraints on published documents may decide to adopt or even create their own customized schema, as long as overall compatibility with the general schema is maintained. The basic compatibility rule here is that all documents validated with the custom schema are also valid with the overall general schema.
  • 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 common Set.
  • Akoma Ntoso Metadata custom 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 may contain metadata items that do not belong to either the the common set or the document-specific set. In such cases, all systems and tools, regardless of the level of support enforced, are required to keep these metadata items 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.

Markup Structures

The Akoma Ntoso model deals with a rather complex situation of several document types and, eventually and hopefully, most countries, by creating ta General Schema and as many custom schemas are needed 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 that can be associated 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 reduces the costs of toolmakers by considerably constraining 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 categories; indeed, these categories are exactly five, as explained in section 6.2, and can be determined by a very simple exam of their definition.