Balisage Paper: Akoma Ntoso:

3.1 The Akoma Ntoso SubSchema Generator

Modules are fragments of schema that can be selected and combined freely, always generating a valid subschema of the complete one. In Akoma Ntoso, a modular architecture of the schema has been developed, and a tool has been created that allows anyone to create custom schemas by selecting individual modules of the vocabulary.

The current version of the tool is aligned with the latest version of Akoma Ntoso and is composed of four independent but cooperating tools:

These tools introduce three types of customization mechanisms:

Akoma Ntoso uses 34 modules, shown in fig. 1. Only one of them, the core set, is always required and cannot be deselected, but users can choose any of the other optional modules. They are organized firstly in document types (legislation, reports, amendments, judgments, collections) and then for optional features (specific elements such as titled blocks, tables of content, etc.).

Figure 1: Akoma Ntoso SubSchema Frontend

fig. 1: the modules’ interface of the Akoma Ntoso SubSchema Frontend

To further simplify the creation of subschema, preset combinations have been created for the most common situations. They are available in a different page of the same application, shown in fig. 2.

Figure 2: Akoma Ntoso SubSchema Generator

fig. 2: The combinations’ interface of the Akoma Ntoso SubSchema Generator

The remaining panels are used to select, customize or create co-constraints on the schema. In particular, the third pane, Heading rules, gives access to a mechanism to control the content model of the hierarchical containers of the schema (hcontainers).

Figure 3: Akoma Ntoso SubSchema Interface

fig. 3: The heading rules interface of the Akoma Ntoso SubSchema Generator

The Heading Pane allows users to select, for each hierarchical element, whether num, heading, subheading and content are required, allowed or prohibited, and which other hierarchical containers are allowed.

3.2 The Akoma Ntoso SubSchema Generator and its co-constraints

The Subschema Generator tool is better accessed through the Akoma Ntoso Subschema Frontend, but in reality, this is an autonomous web service accessible by any other tool through a simple REST interface. The subschema accepts a list of module names, as specified in the actual XSD schema and chosen in the first two tabs of the Frontend, and of rules, detailed in the third, fourth and fifth tabs.

Rules are additional XSD Schema 1.1 co-constraints. Rules can specify further constraints to the content model of any element of the schema, according to a simple syntax. They allow to specify required elements, prohibited elements, or the full list of allowed elements.

As an example, the rule 11_hcm-chapter-reqnum-reqheading-section-nocontent is decomposed as follows:

The SSG tool will generate modifications of the schema in a controlled way. In particular, the above-mentioned rule adds a new specification replacing the original one, where the

 <xsd:assert>

<xsd:element name="chapter">
   <xsd:complexType>
		<xsd:complexContent>
			<xsd:extension base="hierarchy">
				<xsd:assert test="every $x in (*) satisfies $x = (num | heading | subheading | section)"/>
			<xsd:assert test="num"/>
			<xsd:assert test="heading"/>
			<xsd:assert test="not(content)"/>
			</xsd:extension>
		</xsd:complexContent>
	</xsd:complexType>
</xsd:element>

Rules are orthogonal and independent of each other and of the content models specified in the rest of the schema. The actual validation corresponds therefore to the global intersection of the full list of constraints. Thus, if the basic complex type of an element allows an element, and the co-constraint rule forbids it, the element is prohibited, and vice-versa.

3.3 Validating Akoma Ntoso SubSchema using XSD1.1 rules

The Akoma Ntoso Subschema Validator Frontend (AKNSSVF), currently available at the URI http://akn.web.cs.unibo.it/akgenerator/validator.html, is a web interface to activate and control the Schema Validator (AKNSSV) tool, by allowing users to upload Akoma Ntoso subschemas and XML files and verify the validation results of each. In reality, the Akoma Ntoso Schema Validator provides validation for any XML file against the main Akoma Ntoso schema or any subschema thereof.

The co-constraint rules of the subschema generator REQUIRE an XML Schema 1.1 validation engine with full XPath support. The XML Schema 1.1 standard mandates support only for an extremely simplified syntax of XPath for co-constraints (see section 3.11.6.3), and leaves to individual implementations the choice of providing the full XPath 2.0 language as an option. Unfortunately, the co-constraints used in Akoma Ntoso require full XPath 2.0 support.

At the moment, only two XML parsers provide XML Schema 1.1 validation with full XPath support: Saxon Enterprise Edition, which is a commercial application (the freeware Saxon Home Edition does not support it), and Apache Xerces, which is an open source tool. Thus, the schema validator is composed of a Java .jar module that loads and activates Xerces 2.12-beta-r1667115 with full XPath support and represents its error messages in JSON, plus a PHP web script that provides a REST interface to the Xerces engine.

4.1 Adding new metadata

Akoma Ntoso does not allow existing, pre-defined metadata elements to be extended or used in different ways, but it provides a subsection of the metadata section of the document where any new metadata element can be added without constraints.

Consider the following Akoma Ntoso fragment:

<akomantoso>
  <act contains="OriginalVersion">
    <metagt;
      <identification source="#au1"> ... </identification>
     <publication … /gt;
      <proprietary source="#au1"
                 xmlns:cirsfid="http://www.cirsfid.unibo.it/proprietary">
          <cirsfid:MissingInfo>
            <cirsfid:mActDate>1992-12-28</cirsfid:mActDate>
          </cirsfid:MissingInfo>
      </proprietary>
    </meta>
….
</akomantoso>

Akoma Ntoso makes no restrictions as to the vocabulary or containment constraints of the content of the proprietary block. The only requirement is that all new elements belong to a namespace different than Akoma Ntoso. This guarantees the immediate identification of the new elements. Some attributes should be used whenever possible even in proprietary elements:

4.2 Generic elements

The vocabulary of Akoma Ntoso is very rich and aims at supporting precisely the descriptive needs of document authors. Nonetheless, it is clear that there are cases and situations that could not be foreseen when designing the vocabulary, and that would require specific descriptive elements that do not exist in the current version of the Akoma Ntoso language. For these situations there exists a workaround based on the notion of generic element.

A generic element is an element with a generic name and an attribute where its would-be name can be specified, that requires a very precise content model. Once it is determined that an element with the required name does not exist in the vocabulary, a generic element can be used instead, taking good care that the chosen generic element has the right content model.

Akoma Ntoso includes six patterns account for the content models: markers, inline, block, subflow, hierarchical container, container [AKN-voc]. For each of these patterns there exists a corresponding generic element called exactly as the pattern. The name attribute must be used to provide a description of the element, with the explicit requirement that the name attribute should be the name of the element if it were to be accepted in the language as an extension.

For instance, if there were the need for an element wrapping a small fragment of text within a sentence to identify, say, the language of the original version of the document, then the correct content model would be inline, and therefore the inline generic element should be used as showed below:

<inline refersTo="#english" name="originalLanguage">Original: English</inline>

Akoma Ntoso uses a simple and bare-bones ontological approach for fundamental entities mentioned or characterized in the content of the document, called Top Level Classes (person, organization, etc.). There are exactly 14 TLCs, each of which can be associated to better specified entities in external ontologies and connected to the body of the document through specific inline elements. Whenever there is the need to mark elements with a specific connection to an ontology, entities are the right elements to use.

4.3 The <foreign> element

Akoma Ntoso does not provide markup for situations that are very specific and for which better-suited vocabularies exist already. For instance, mathematical formulas or drawings have well-known standard XML vocabularies that should be used rather than inventing a new one. For these situations, the <foreign> element can be used to specify fragments of content that correspond to structures and data that are not currently managed by Akoma Ntoso. For instance, the following is a valid Akoma Ntoso fragment to show the equation ax2+c:

<foreign>
	<math xmlns="http://www.w3.org/1998/Math/MathML">
		<mrow>
			<mi>a</mi>
			<mo>⁢</mo>
			<msup>
				<mi>x</mi>
				<mn>2</mn>
			</msup>
			<mo>+</mo>
			<mi>c</mi>
		</mrow>
	</math>
</foreign>

The foreign element is a block-level element, which means that it is presumed that its content appears in a vertically isolated block. Furthermore, only fully qualified XML fragments can appear there, and they must belong to a different namespace than Akoma Ntoso.

5.1 Custom types

The first and most evident customization of the schema is the redefinition of existing types. Regardless of whether one creates a new type, restricts an existing type or edits the main Akoma Ntoso definition of the existing type, the basic requirement is that the fundamental rule for the customization of Akoma Ntoso holds: the resulting type must make sure that valid documents for the custom schema are valid documents for the main schema.

5.2 Custom attributes

While being very rigid about new elements, the Akoma Ntoso schema is much more flexible about custom attributes to existing elements. The rule is that it is possible to create new attributes and assign them to any of the existing elements, as long as these attributes are assigned to a different namespace than Akoma Ntoso.

XML Schema requires that each XSD file is associated to only one namespace (its target namespace), so that the definition of the new attributes must be in a different namespace than the schema. This means that we need two separate schemas if we edit the Akoma Ntoso schema directly, and three files if we redefine the schema: the original Akoma Ntoso schema, the schema containing the new attributes, and the pivot schema that redefines the Akoma Ntoso structures.

Although XML Schema would allow custom attributes to be specified in the Akoma Ntoso namespace, this would go against the rule of the Akoma Ntoso language and should not be performed.

5.3 Custom elements

A shown in the previous section, defining new attributes is easy, and there is no requirement for sequence and organization of the text content of the document. On the other hand, new elements are a completely different problem, because Akoma Ntoso expects a specific sequence of containment when dealing with the actual text content of a document. Custom elements, therefore are only indirectly introduced as generic elements or within special contexts, i.e. those whose type is defined as anyOtherType, a list which includes only one content-oriented element (i.e., <foreign>) and several metadata element.