Tamino Annotations in XML Schema

While XML Schema covers the logical aspects of document type definitions, it does not prescribe how to define the physical aspects. Many XML processors require extra information on how to process the instances of a given document class. Tamino, for example, needs to know the collection to which a document class belongs, the elements or attributes which are used for indexing, the type of indexing that is used, how document elements may be mapped onto fields in external databases, and so on.


Annotation and Appinfo

For these and other purposes XML Schema provides an extension mechanism. Any schema, element or attribute definition in XML Schema can be equipped with one or more annotations. Each annotation can consist of two child elements: documentation and appinfo. The documentation element contains documentation for human readers, and the appinfo element contains information for machines.

Tamino uses the appinfo element to store Tamino-related information within a schema file:

<?xml version = "1.0" encoding = "UTF-8"?>
<xs:schema
        xmlns = "http://www.softwareag.com/tamino/doc/examples/models/jazz/encyclopedia"
        xmlns:xs = "http://www.w3.org/2001/XMLSchema"
        xmlns:tsd = "http://namespaces.softwareag.com/tamino/TaminoSchemaDefinition"
        targetNamespace = "http://www.softwareag.com/tamino/doc/examples/models/jazz/encyclopedia"
        elementFormDefault = "qualified"
>
  <xs:annotation>
    <xs:appinfo>
      <tsd:schemaInfo name = "albumSchema">
        <tsd:collection name = "encyclopedia"/>
        <tsd:doctype name = "album">
          <tsd:logical>
            <tsd:content>open</tsd:content>
            <tsd:accessOptions>
              <tsd:read/>
              <tsd:insert/>
              <tsd:delete/>
              <tsd:update/>
            </tsd:accessOptions>
          </tsd:logical>
        </tsd:doctype>
      </tsd:schemaInfo>
    </xs:appinfo>
  </xs:annotation>
  ...
</xs:schema>

These annotations are generated by the Tamino Schema Editor.

Schema-Level Definitions

The example above shows an annotation on the schema level. This is indicated by the <tsd:schemaInfo> element. The attribute name specifies the name of the schema (albumSchema).

graphics/schemaprop.png

Enclosed in the <tsd:schemaInfo> element is a definition for the Tamino collection to which the schema belongs. Typically a collection contains document types that are somehow related, for example the document types derived from a specific conceptual model or all schemas that belong to a given application.

Here, we define a collection encyclopedia that will eventually contain all the document types (jazzMusician, style, collaboration, album, review and critic) that we defined earlier (From Conceptual Model to Schema::From Model to Schema).

In addition to the <tsd:collection> element, the element <tsd:schemaInfo> contains a <tsd:doctype> element which defines the name of the document type as album. This name is not necessarily the same as the schema name, but must match the root element name of each document instance belonging to that particular document type.

The <tsd:doctype> element may contain an element <tsd:logical>. This element specifies the access options for the document instances and the content type:

  • The access options specify the database operations (read, insert, update, delete) that are allowed for this document type;

  • The content type "closed" specifies that a document instance may not contain deeper structures than specified in the schema. In contrast, content type "open" allows document instances to be extended with tags that are not defined in the schema.

This is a more flexible - albeit non-standard - approach to the open content model than using xs:any and xs:anyAttribute. For a discussion of the pros and cons of the Tamino-specific open content model, see also Tamino-specific Extensions to Logical Schema::Open Content vs. Closed Content Validation.

We could, for example, define our style document type with content type "open" because its description element may contain other markup. However, using an xs:any child node for the description element definition is probably the better choice here: thus we stay with the W3C XML Schema recommendation, and we are able to specify a namespace for the XHTML content of the description element.

Node-Level Definitions

The physical properties of each document node can be specified with similar annotations. Again, these annotations are generated by the Tamino Schema Editor. Here is an example for the attribute ID of our schema jazzMusician:

graphics/attribute.png

and the resulting code:

<xs:attribute name = "ID" type = "xs:NMTOKEN" use = "required" form = "unqualified">
  <xs:annotation>
    <xs:appinfo>
      <tsd:attributeInfo>
        <tsd:physical>
          <tsd:native>
            <tsd:index>
              <tsd:standard></tsd:standard>
            </tsd:index>
          </tsd:native>
        </tsd:physical>
      </tsd:attributeInfo>
    </xs:appinfo>
  </xs:annotation>

Contained in the <xs:appinfo> element is the element <tsd:attributeInfo>, which describes the properties of this attribute node. In the Tamino Schema Editor we have specified that the storage type of the attribute is "Native". This means that the attribute is to be stored as native XML in Tamino. There are also other options, for example, to map a document node to a Tamino Server Extension (see Utilizing Server Extensions::Derived elements) or to fields in a foreign database such as Adabas or a third-party RDBMS.