General Schema: Patterns and Content Models

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 element categories (or patterns in content models, which are a restriction of content models to the ones that are actually useful in real life text documents) and best practices (or patterns in schema design, which are 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 about markup language.

The AKOMA NTOSO general schema is systematically based on five element categories . This means that all content models and complex types used in the schema follow precisely the form of the relevant category, and all elements can be simply described and treated according to their category rather than individually.

These categories are:

1. The marker: markers are content-less elements that are meaningful for a combination of their position within the text, their names and 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 where text can be found, and metadata elements that only appear in some subsection of the metadata  section.
   <noteref n=”1” href=”#note1”/>
   <enactmentDate date=”20030919”/>.
2. 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 within an act's section, the name of a speaker within an hansard  and the official date in the heading of a bill  are all examples of inline elements, and simlarly would be examples of bold or italic text within a paragraph. In the following example, both term and ref are inline elements contained within a block and mixed with plain text.
3. The block: a block element is a container of text that stands autonomously and can contain inline elements. In Western countries blocks are presented as stacked vertically over each other. Examples of blocks are paragraphs, scenes, headings, etc. In the following example, p is a block containing both text and inline elements.
   <p><term>Commission</term> means the commission established by <ref href=”#sect20”>section 20</ref>;</p>
4. 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. Containers are all different from each other (since the actual list of contained elements varies), and so there is no single container content model, but rather a number of content models that belong to the container category. 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.
   
   <act>
       <meta> ... </meta>
       <preamble> ... </preamble>
       <clauses> ... </clauses>    
       <attachments> ... </attachments>
   </act>
5. The section, or hierarchical container: these are special containers that form a hierarchy of containment. 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. 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. 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>

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><ul> elements to contain only text, and nested lists to be direct children of the main list element (s within <ul>). Since this goes against universal HTML practice, it was decided against full adherence to the category and in favour of the HTML tradition. 
• The <mod> element allows quoted text and structures within its content. No problems exist 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 some inline elements that only make sense in the preface and preamble parts of the document: these are <DocTitle>, <DocNumber>, <DocType>, <DocProponent>, <DocDate> and <DocPurpose>. They are in fact part of the unique existing inline content model and thus are technically available everywhere in the document, rather than simply within the preamble. There is no simple way to define blocks within <preamble> and <preface> to allow these elements and blocks elsewhere to not allow them, so it is better to allow them everywhere rather than unnecessarily complicating the schema. 

Regarding guidelines, or 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 in the following documentation.