Next: 5.2. General Schema Previous: 5. Schema  

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

Next: 5.2. General Schema Previous: 5. Schema