ZedAI Primer: Z39.98-AI Profiles

From zedwiki
Jump to: navigation, search

Contents

  1. 1.1 A simple Z39.98-AI document
  2. 1.2 Default namespace
  3. 1.3 Default RDFa profile
  4. 1.4 Identifying profiles
    1. 1.4.1 Profile resources
  5. 1.5 Metadata
  6. 1.6 The document content
  7. 1.7 Validating the document

1.1 A simple Z39.98-AI document

We will begin with the simplest possible valid Z39.98-AI document:

Example 1.1 - A minimal Z39.98-AI document

<document xmlns="http://www.daisy.org/ns/z3998/authoring/" xml:lang="en">
  <head>
    <meta rel="z3998:profile" 
          resource="http://www.daisy.org/z3998/2012/auth/profiles/genericdocument/1.0/">
        <meta property="z3998:name" content="genericdocument"/>
        <meta property="z3998:version" content="1.0"/>
    </meta>
    <meta rel="z3998:rdfa-context" resource="http://www.daisy.org/z3998/2012/vocab/context/default/"/>
    <meta property="dc:identifier" content="daisy-z2011-exemplar-01" />
    <meta property="dc:publisher" content="DAISY Consortium" />
    <meta property="dc:date" content="2011-07-27T18:50:05Z" />
  </head>
  <body>
    <h>Hello, world.</h>
  </body>
</document>

We will go through this document and explain the various markup items found there.

1.2 Default namespace

Z39.98-AI documents may contain a mixture of many different markup languages to express different kinds of content. In order to keep these straight, all Z39.98-AI documents use XML namespaces. But while the different namespaces that may be used in a Z39.98-AI document may vary, all Z39.98-AI documents must use the same default namespace, which is the namespace for the Z39.98-2012 core modules: http://www.daisy.org/ns/z3998/authoring/. In our example document, this default namespace is declared on the root document element.

1.3 RDFa initial context

Every Z39.98-AI document references an RDFa initial context document, which defines a default vocabulary for metadata terms as well as a number of prefixes for additional commonly-used vocabularies. For example, all RDFa context documents define the dc and z3998 prefixes to standardize the way that the required document metadata gets attached to a file (more on metadata below).

A meta element defining the relationship z3998:rdfa-context is used to make explicit the association between the Z39.98-AI document and its initial context document, and must always be included. In the preceding example, the meta element points to the Z39.98 Default context document available at http://www.daisy.org/z3998/2012/vocab/context/default/, which defines a default set of vocabularies for use in the Z39.98-AI Book documents (and others).

Every Z39.98-AI profile defines the RDFa context document that compliant documents must reference, so there is no choice when it comes to setting the document (refer to the Resource Directory for each profile to locate the URI of the context document you must reference).

By setting the RDFa Default context, terms from the Z39.98-2012 Structural Semantics Vocabulary may be referenced in the document without a prefix (this context document defines this vocabulary as its default). The following markup could then be added to indicate a proper name:

Example 1.2 - Using terms from a default vocabulary

<name property="personal-name">
  <span property="first-name">Charles</span>
  <span property="last-name">Darwin</span>
</name>

The terms personal-name, first-name and last-name would be ambiguous without the default initial context to map them back to the vocabulary they were taken from. Without this information, each term would need to be prefixed to indicate the parent vocabulary and each prefix would have to be manually mapped back to the parent vocabulary; a needlessly cumbersome way to attach metadata from the most commonly used vocabulary.

Each context document can only define a single default vocabulary, so there is still a need and use for prefixes. Some prefixes are defined in the context document, which ensures standard use across all documents and producers, but not every possible RDF vocabulary has been, or could be, included for use. The lack of a pre-defined prefix in the context document does not mean you are restricted to only using the vocabularies that have been defined in it, however.

Z39.98-AI documents also allow the use of the prefix attribute on the document element to declare additional vocabularies. Terms from the Friend of a Friend vocabulary could be used in addition to those defined in the default RDFa profile by declaring a foaf prefix as in the following example:

Example 1.3 - Declaring a vocabulary prefix

<document xmlns="http://www.daisy.org/ns/z3998/authoring/" prefix="foaf: http://xmlns.com/foaf/0.1/" xml:lang="en">
  … 
</document>

The previous example might then be re-implemented as:

Example 1.4 - Using prefixed terms

<block typeof="foaf:Person">
  <name property="foaf:name">
    <span property="foaf:givenname">Charles</span>
    <span property="foaf:surname">Darwin</span>
  </name>
</block>

The prefix attribute must never be used to define new prefixes for vocabularies that have already been defined in the RDFa context document, however.

1.4 Identifying profiles

Every Z39.98-AI document references a Z39.98-AI profile. A profile defines markup designed to support the creation of XML documents from a particular type of information resource. Simple books, periodicals, newspapers, textbooks, and examinations all might require different XML vocabularies in order to be fully and clearly expressed in an XML document. Therefore, each of these kinds of resources could have a different Z39.98-AI profile that provides the tools necessary for document authors.

Our example document references version 1.0 of the "generic document" profile, one of the profiles defined by the Z39.98-2012 specification, using the meta element:

Example 1.5 - Identifying the profile

<head>
  <meta rel="z3998:profile" 
        resource="http://www.daisy.org/z3998/2012/auth/profiles/genericdocument/1.0/">
    <meta property="z3998:name" content="genericdocument"/>
    <meta property="z3998:version" content="1.0"/>
  </meta>
</head>

The rel attribute value of "z3998:profile" here indicates that this meta element is a profile declaration. The prefix z3998 is declared in the document element, and points to the Z39.98-2012 Instance Metadata Vocabulary (we will describe vocabularies and how to reference them in 3, Adding semantic inflections). As you can also see in the example, profiles are identified by a unique URI, given in the resource attribute of the meta element. The URI for each profile is defined by the agency that created and maintains that profile (in this case, the DAISY Consortium).

The name and version of the profile are specified in the nested meta elements. The profile URI in the resource attribute may include this information in uniquely identifying the profile, but is not required to do so. Processing agents, however, require this information to determine whether are able to process a document, so their inclusion is not optional.

1.4.1 Profile resources

At its core, a profile defines specific XML markup to be used for documents. This markup is defined using one or more normative schemas, written in a schema language such as RelaxNG. There may be other resources associated with a profile, such as translated W3C XML Schemas, and stylesheets. We will touch on other profile resources later on in this primer.

Beyond uniquely identifying the profile, the profile URI points to the location where the resource directory for the profile is available. This resource directory contains all the information related to the profile and is described using XHTML+RDFa (as defined in RDFa in XHTML: Syntax and Processing). Resource directory documents are thus based on XHTML, which means that they can be viewed in a web browser. The document will typically have a description of the purpose of the profile, links to the normative schema and other profile resources, and to any associated specification documents. XHTML+RDFa documents are also machine-readable, which means that they can be used by systems that process Z39.98-AI documents to discover necessary schemas and other resources at run time. In sum, by following the profile link appearing in the head of the document, any person or processing system can find all the information available about that profile.

The various resources for the profile are identified as the targets of links within the XHTML+RDFa document. The nature of each resource being linked to is typically identified using the rel attribute of the a element.

Normative schemata links differ in that they are grouped into a section of the document defined using the rd:normative-schemata term. More than one link to a normative schema can be contained within the section, so more information is necessary to locate the appropriate format than can be expressed in a simple rel relationship. Each schema is instead identified using an about attribute (which also points to its location), and contains information about itself in the child properties.

Here is an excerpt of the source for a resource directory, where a single normative schema is identified:

Example 1.6 - Profile resource directory (partial)

<div class="rd-section" property="rd:normative-schemata">
   <h3 id="h_normativeschemata">Normative schemata</h3>
   <p about="z3998a-book.rng"> The normative 
      <span property="rd:schema-type" content="rng">RelaxNG</span> schema for version 
      <code property="rd:version">0.8</code> of the Book profile is 
      <a href="z3998a-book.rng">z3998a-book.rng</a>. 
   </p>
</div>

As the above example shows, release version 0.8 (as identified by the rd:version property) of the normative schema z3998a-book.rng is available in RelaxNG syntax (as identified by the rd:schema-type property). The a tag provides a user-linkable reference to the schema, but is not necessary for locating the resource (it is always the same as the about value).

1.5 Metadata

As with XHTML and earlier versions of Z39.98, Z39.98-AI documents contain metadata in the document head. There is an intentionally small set of required metadata items: unique identifier, publisher, and last modification date (the latter also serving as a version identifier).

Example 1.7 - Basic document: metadata

<head> 
  … 
  <meta property="dc:identifier" content="daisy-z3998-exemplar-01" />
  <meta property="dc:publisher" content="DAISY Consortium" />
  <meta property="dc:date" content="2011-07-27T18:50:05Z" />
  …
</head>

As is described further in 5, Metadata in Detail, Z39.98-AI documents allow you to associate metadata resources with the document. These resources are intended to contain more "complete" metadata about the document (and, as sometimes needed in a republishing context, about the document source).

1.6 The document content

Following the profile identification and metadata in the document head of our minimal document comes our minimal document content: a single heading, expressed with the h element. This comes from the Z39.98-2012 core modules, and hence does not need a further namespace identification. The Z39.98-2012 core modules define a few basic elements and attributes that are likely to be used in all profiles. The elements defined here include all the basic structural elements (head, body) and attributes that are needed throughout Z39.98-AI documents, such as xml:id and role. For our minimal document, no further markup is needed, and hence no schema modules outside the Z39.98-2012 core modules are used.

1.7 Validating the document

That is all there is to the document, which is nevertheless a completely valid, conforming Z39.98-AI document. For those used to DTDs, the lack of a doctype and system identifier may raise the question of how one validates this document.

As we saw in Section 1.4.1, “Profile resources”, the profile's resource directory (found at the profile identification URI in the document head) defines at least one normative schema to use in validating the document. The way in which the schema validation process takes place depends on the schema language(s) used, and which tools are used to perform the validation.

The profile's resource directory can also reference informative schemas or DTDs, that allow authoring and (to a certain extent) validation within a variety of tools. Note however that the concept of informative means that the informative schemas are provided for utility and convenience reasons - not to perform the ultimate test on whether a document is valid or not. That latter task is reserved for the schema defined by the resource directory to be normative.


Primer Table of Contents

  1. Z39.98-AI_Profiles
  2. Modules and Namespaces
  3. Adding Semantic Inflections
  4. Features
  5. Metadata
Personal tools