From zedwiki

Abstract Document Model, Core Module Pool and Abstract Definitions

This page is a scratch pad for the AI spec sections on Abstract Document Model and Core Module Pool (added during February 2010).

Contents 1 Rationale 2 Basics 2.1 Abstract Document Model (ADM) 2.2 Rules associated with the abstract document model 2.3 Core Module Pool 3 Consequences on spec 3.1 Glossary Entries 3.2 Addition of an Abstract Document Model section 3.3 Addition of a Core Module Pool section 3.4 Rewrite of sections that appear before ADM 4 Consequences on RNGs 5 Spec Prose Development area 5.1 Additions to the top-level glossary 5.2 Modules 5.2.1 Introduction 5.2.2 Components 5.2.2.1 Definition 5.2.2.2 Traits 5.2.2.2.1 Semantic definition 5.2.2.2.2 Initial usage context 5.2.2.2.3 Initial content model 5.2.2.2.4 Initial attribute model 5.2.2.2.5 Alterability 5.2.2.2.6 Omittability 5.2.3 Core Module Pool 5.2.4 Activation 5.2.4.1 Module Inclusion 5.2.4.2 Component Inclusion 5.2.5 Markup Model 5.2.5.1 Schema 5.3 Abstract Document Model 5.3.1 Introduction 5.3.2 Fundamentals 5.3.2.1 Document Structure Layers 5.3.2.2 Document Information Layers 5.3.2.3 ADM Constraints 5.3.2.4 Core Class 5.3.3 ADM Layer Definitions 5.3.3.1 Document 5.3.3.1.1 Description 5.3.3.1.2 Core Class 5.3.3.1.3 Fundamental Member 5.3.3.1.4 Content Restrictions 5.3.3.2 Section 5.3.3.2.1 Description 5.3.3.2.2 Core Class 5.3.3.2.3 Fundamental Member 5.3.3.2.4 Content Restrictions 5.3.3.3 Block 5.3.3.3.1 Description 5.3.3.3.2 Core Class 5.3.3.3.3 Fundamental Member 5.3.3.3.4 Content Restrictions 5.3.3.4 Phrase 5.3.3.4.1 Description 5.3.3.4.2 Core Class 5.3.3.4.3 Fundamental Member 5.3.3.4.4 Content Restrictions 5.3.3.5 Text 5.3.3.5.1 Description 5.3.3.5.2 Core Class 5.3.3.5.3 Fundamental Member 5.3.3.5.4 Content Restrictions 5.3.3.6 Meta 5.3.3.6.1 Description 5.3.3.6.2 Core Class 5.3.3.6.3 Fundamental Member 5.3.3.6.4 Content Restrictions 5.3.3.7 Global Attributes 5.3.3.7.1 Description 5.3.3.7.2 Core Class 5.3.3.7.3 Fundamental Member 5.3.3.7.4 Content Restrictions 6 Expired Prose 6.1 Fundamentals 6.1.1 Specializations 6.1.2 Features 6.2 Core namespace URI 6.3 Core module pool canonical URI 6.4 Core module pool versioning strategy

Rationale

closer coupling between spec and profiles 

Previous drafts of the spec omitted these sections entirely; although clear TODOs in this direction were present in these drafts, the absence made it clear that the distance between the spec and the actual profiles needs to be as tight as possible, without loosing the ability to create profiles with differing scopes. In other words, without an Abstract Document Model and a Core Module Pool, the spec has only limited relevance for profile creators and module providers.

coherent rules for profile creation 

whereas the previous drafts of the spec did specify restrictions and rules for profile creation, they were scattered and did not rely on a common "abstract model"; as such, there was no global fundament of logic to describe the frameworks abilities and groundrules.

rules for module providers 

Similarly, this gives the ability to express design (and annotation, to a less extent) requirements on modules.

establish a core set of elements and attributes 

the notion of a "core module pool" enables us to within the spec scope define a set of elements and attributes that must serve as the starting point when creating new profiles, and that must be taken into consideration when providing new modules. (In terms of retaining flexibility, see the terms omittable and alterable)

Basics

Abstract Document Model (ADM)

Defines an abstract 5-level document topology (see pic reffed from spec), and the overarching nature of (the members of) each of the five levels.

This is an intentionally simple/unobtrusive model, that besides establishing a general idea of the ZedAI document topology, serves the purposes of

• providing generalized "contribution" slots for elements, with associated rules regarding alterability (for example: forbidden to move an element away from its initial level/context)
• using 4 "real" levels (excluding the document level in this argument) instead of the html classic 2-level approach (block+inline) allows a somewhat more controllable/fine-tunable document design

Note: the term level should ideally be replaced by something more suitable. These are like hierarchical abstract containers with behavioral rules attached.

Rules associated with the abstract document model

A set of restrictions are associated with the levels in the ADM. These rules form the basic groundrules that a profile designers and module providers must follow.

(These are available in rough note form in the docbook spec, should be summarized here before rewrite)

Core Module Pool

The Core Module Pool section is autogenerated based on annotations in the modules. (Note that some Feature Resource Directories also render tables akin to the ones in the spec's core module pool section.)

Since the modules in the pool comply to the rules of the ADM, they, for each component that the module contributes, define the following component traits:

• a formal semantic definition of the components meaning/nature (== dcterms:description)
• the initial context of the component (which in current RDF island syntax is directly or indirectly a injection to 1-n levels -- we may want to add some annotation attribute to make it explicit)
• the initial content model of the component (in the case of elements and attributes at least)
• in the case of elements, the initial attribute model of the element
• the omittability of the component - Can this component be omitted when including this module in a profile?
• the alterability of the component - Which of the traits above can be modified by a profile creator when including the module?
  • The default alterability state of a trait is "on" - restrictions on alterability must be explicitly expressed in human-readable module prose (in our case, the RDF islands)
  • Trait alterability restrictions can be complete (you cannot change this trait at all) or partial (example: section or specializations thereof must allow 1 heading in their content model; it may be declared reqruied or optional, but there must never be more than 1 heading)
  • There are restrictions on alterability that are global and need not be repeated locally, for example, a component may have an alterable usage context, but it still cannot be moved out from its ADM level (you cant make span an allowed sibling to section, for example).
  • the semantic definition trait is locked from alteration (should perhaps not be called a trait at all)

The term initial is used to indicate that the definition may change when the component is turned from abstract to concrete (== included in a driver, and depending on which other modules are included). When a component has alterability turned fully off for a trait, the initial trait and the concrete trait are identical.

Consequences on spec

Glossary Entries

Rough drafts of terminology in the docbook spec (starting line 1462). These can either go to the global top-level glossary, or live like at 1462 in a section-local glossary, all depending on how much terms are reused in other parts of the spec. Should be summarized here before rewrite.

Addition of an Abstract Document Model section

At the time of writing this line, early scratchpad stuff added, following the document metadata section in the spec.

Addition of a Core Module Pool section

The autogenerated stuff. Starts with the first absdef PI.

Rewrite of sections that appear before ADM

The sections that occur before the new ADM sections will need a walkthrough+rewrite once the absdef section is in place, as parts of these sections will have become redundant. (JamesP has offered to help with this.)

Consequences on RNGs

• Alterability definitions needs to be added to the RDF islands. See Issue 100. (In the autogenerated absdef sections, these entries could possibly be grouped with the sch assertions, since they all relate to the same topic: constraints that must always be met. However, the sch assertions are more focused on instance constraints, whereas alterability constraints focuses on the profile creation process. So grouping like that may be confusing.

Spec Prose Development area

Additions to the top-level glossary

In the module abstract definitions, the following terms and notation forms are used:

Traits

Just a oneliner here, reference the Modules section on traits

Module Component

An individual element, attribute, datatype, value or pattern defined in a module.

Module Activation

The act of including a module in a profile, thereby including all or some of its components in the markup model. Activation can include making alterations to the traits of the module components, as well as excluding a component entirely (if the module allows this). See alterability.

Specialization

An element or attribute that inherits traits from another element or attribute. Traits include content model, attribute model, and usage context.

Elements contributed to a level typically inherit a set of basic traits from that levels fundamental member, and are thus specializations of the fundamental member. Specializations may however occur among arbitrary members of a level, i.e. with the fundamental members traits only indirectly inherited.

In the abstract definition, specializations are expressed

Customization (what we used to call "variant")

...

Implicit value

Attribute components may declare an implicit value of the given attribute. This value is a fallback value that Processing Agents must assume in the case when the attribute is not specified in the instance. Implicit value declarations may be global (apply regardless of where the attribute occurs) or local (apply only when the attribute occurs in a particular context).

Note that an implicit value is different from XML DTD attribute defaulting in the sense that XML Processors will not report implicit values to the application.

In the abstract definition, implicit values are expressed TODO any info on specific expression syntax for this

class

(Maybe not necessary here)An abstract set of element or attribute declarations, dynamically populated depending on which modules are activated in the current markup model.

Classes do not constitute content model templates; they are simply collections of declarations that can be used to create concrete content models.

Modules

Introduction

Modules are the high-level building blocks of Z39.96-AI profiles and together with features form the basis through which new grammars are created. Modules may be pre-defined, as in the case of the Core Module Pool, may be composed by profile authors to meet their particular structural needs or may be made available for public use by interest groups.

Modules, in their practical form, are schema files that define custom components -- such as elements and attributes -- for use in building profiles. The components within any module typically share a common nature or serve a common structural purpose, allowing for targetted activation of modules for specific uses. This approach to module definition enables element and attribute counts to be kept to a minimum when composing new grammars.

An abstract definition is available for every module, defining the nature of the module and the components it contains. The abstract definitions provide the initial state of a module, and the information they provide is intended to instruct profile creators on their use; the abstract definitions should never be consulted for validation problems that arise during document creation.

Components

Definition

A component is any single element, attribute, datatype, set of values or pattern defined in a module file that can be activated and used to build content models. Components may be usable individually or may be dependent on parental or child relationships also being fulfilled. Some components may also have dependencies on components from other modules.

Each component has a default nature, which includes traits such as its semantics, usage context, content model, and whether or not its traits are open to alterations and customizations. These traits are defined more completely in the traits section.

All usage information for components is contained in their module's abstract definition, which is generated from metadata information embedded in the module and within each component it contains. For modules from the Core Module Pool, the abstract definitions are available in the CMP definition section. For custom modules, the abstract definitions must be provided in the accompanying documentation for the profile.

Traits

A trait is a single piece of metadata information about a component that defines something about its overall nature. Traits provide information about what components are for, how they are used, where they can be used, when they can be used, etc.

Each component must specify the following set of traits about itself:

• a semantic definition;
• an initial usage context;
• an initial content model;
• an initial attribute model;
• a definition of alterability; and
• a definition of omittability.

These traits are expressed in RDF syntax within the definition of each component and allow the abstract definition for the module to be generated. All traits must be specified for every component, and can only be omitted where omission implies a default state.

Note: The prefix "dcterms:" in the following sections indicates that elements are available from the Dublin Core set of metadata terms. The "z:" prefix refers to a set of DAISY metadata elements.

Semantic definition

The semantic definition provides a concise statement about the kinds of structures or data the component is meant to represent.

The semantic statement can be either very restrictive about what the component can capture, in the case of highly-specialized components like tables of contents, or can be very generic if the component defers it semantics to other attributes, for example an element that generally identifies quoted material without specifying what type of material is being quoted or the role that the quoted material serves (such as an epigraph).

The semantic definition must always be respected when including and using components in a Z39.86-AI profile; it is not valid to use a component in a way that contradicts its definition.

To generate the abstract definition, the semantic definition must be declared inside a dcterms:description RDF metadata element:

   <dcterms:desciption>
      The term element represents a word, or compound word, 
      characterized by its particular use and context.
   </dcterms:desciption>

Initial usage context

The initial usage context identifies how the component is initially configured to be used within the Abstract Document Model and/or within other components:

• if the component references classes in the ADM, then the initial parent of the element or attribute is any element that allows the referenced class in its content or attribute model, respectively.
• if the component has a single element as its parent, then the referenced element is the initial parent of the element or attribute.

Elements and attributes have an alterable usage context unless the initial context is explicitly declared to be fixed. When altering a usage context, elements must not be moved across layer boundaries in the ADM.

In the abstract definition, fixed contexts are expressed TODO any info on specific expression syntax for this

To generate the abstract definition, the initial usage context must be declared using prose and/or expressions in [RNC] syntax inside a z:context RDF metadata element:

   <z:context>
      #z3986.Phrase.class
   </z:context>

Initial content model

Each element and attribute in a module must declare an initial content model or data type that specifies its allowed content or value(s):

• in the case of elements, the initial content model is a set of references to classes, elements and/or data type declarations.
• in the case of attributes, a data type must be specified, which may reference other data type declarations and/or enumerated literal values to set the initially-allowed value(s).

Every element or attribute has an alterable content model unless it is explicitly declared to be fixed. Declarations of fixed content models may apply to the content model as a whole, or to individual components of it.

To generate the abstract definition, the initial content model must be declared using prose and/or expressions in [RNC] syntax inside a z:content RDF metadata element:

   <z:content>
      (text | z3986.Text.class)+
   </z:content>

Initial attribute model

In addition to their default content model, elements must additionally declare an attribute model that specifies a set of references to attribute classes or individual attribute declarations that constitute its initial set of allowed attributes.

Every element has an alterable attribute model unless it is explicitly declared to be fixed. Declarations of fixed attribute models may apply to the attribute model as a whole, or to individual attributes within it.

All elements should allow the Global Attributes class by default.

To generate the abstract definition, the initial attribute model must be declared using expressions in [RNC] syntax inside a z:attlist RDF metadata element:

   <z:attlist>
      #z3986.Phrase.attrib
   </z:attlist>

Alterability

Each component specifies, directly or indirectly, whether its initial content model, attribute model and context are open to alteration when its containing module is activated. The semantic definition and rules of alterability and omittability are fixed and cannot be changed, however.

Alterations to the initial content and attribute models can be made to both restrict and loosen their allowed content/values. Complete rewrites of these initial states may also be permissible.

The initial context model can likewise be restricted, loosened or rewritten to change the way that the component can be used by other components and within layers of the ADM.

Alteration of a component's traits is allowed by default, but no alterations are permitted that would cause the nature of the element to conflict with its semantic definition. Components must expicitly express restrictions to this rule.

TODO: write something on how this trait is expresed. how is it??

Omittability

As modules may contain more components than are needed in the Z39.86-AI profile into which they are activated, their components may be specified as omittable to allow exlcusions and reduce needless clutter.

A component cannot be omitted if another included component requires it as a dependency.

Omittability is an implied trait for all components and must be overriden by the inclusion of a dcterms:isRequiredBy RDF metadata element to change to a fixed status: [TODO: is this right??]

   <dcterms:isRequiredBy rdf:resource="."/>

Core Module Pool

The Core Module Pool (CMP) is a collection of pre-defined modules that provide a common base of components for use in all profiles, thereby ensuring a level of structural consistency across profiles.

The modules are grouped so that each contains a single set of semantically and/or structurally related elements and attributes that have been identified as having general applicability across a wide variety of document types. Where an element or attribute already exists in the CMP, profile creators are encouraged to use the existing construct, or a specialization of it, over creating another that is only distinguishable by name.

An abstract definition of each module is included in section xxx. These definitions have been extracted from the module and component metadata and provide detailed information about the nature of each as well as details regarding their use and activation. In the case of discrepancies between the abstract definitions and the actual implementations, however, the latter shall be taken as authoritative.

Activation

Activation of a module is the process of including it into a profile driver file, importing all required and needed components and making any alterations necessary to tailor the components to the requirements of the document type being built.

Note: For information on creating profile driver files, please refer to new section needed.

Module Inclusion

The first step in activating a module is to import the module into a profile driver file. This is done in a RelaxNG syntax using the include command:

   <include href="object.rng"/>

An empty include element indicates that no alterations or omissions are being made to the default nature of the module and its components.

If a module lists other modules as dependencies, those modules will also need to be imported (including any of their dependencies, and similarly on down the import chain). Each dependency only needs to be imported once; multiple inclusions will result in invalid profiles.

Component Inclusion

The next step in activating a module is to assess and satisfy component-specific considerations, namely:

• the omitting of any unnecessary components, if exclusions are permissible; and
• the alteration of the initial content and attribute models and usage context of components, if alterations are permissible.

Individual components are omitted by ...

   <include href="test.rng">
      <define name="z3986.object.phrase">
         ...
      </define>
   </include>

TODO: keep writing examples?

The activation of most modules in the CMP is optional and at the discretion of profile creators, but the following modules must be activated for all valid Z39.86-AI profiles:

• the document module
• the global classes module
• TODO: figure out all required modules

Although the activated modules in a profile is an ingredient in determining its uniqueness, module activation alone does not result in a new Z39.86-AI profile. Two profiles may activate the same modules but modify and specialize their use in different ways. In practical terms, distinction between profiles is determined by variations across all of the following key factors:

• which modules have been activated;
• the number of alterations made to the components of the activated modules; and
• the number of new elements (specializations) introduced.

Markup Model

Schema

Features must be formally expressed using one or several normative schemas. The allowed schema types are the same types allowed for the profiles schemas (as defined in Section 5.3.1, “Schema”).

Abstract Document Model

Introduction

The Abstract Document Model (ADM) underpins the Z39.86-AI specification, providing the basic structure through which all document profiles are defined. The ADM is both a concept for defining the structure of documents and a model for creating valid Z39.86-AI profiles: it decomposes documents into five tiers of increasing structural granularity and adds two complementary tiers of information that flow through them, and exposes those layers for customization and extension:

Figure: The five hierarchical layers of the abstract document model with the information layers flowing through them

Moving structurally from the outer-most Document layer to the inner-most Text layer, the ADM provides the level of abstraction necessary to retain commonality between profiles while leaving open the definition of what a document is to profile creators. As a result, the ADM can be used to create schematic definitions for documents across a wide spectrum of formats and fields while retaining a predictable core structure.

The Z39.86 AI specification was built on the ADM model specifically to address the problem of extensibility that existed in previous standards. No single schema can encompass all document types and provide all the structure and flexibility necessary for all accessible formats, and though extensibility points were introduced in previous specifications to try and address this problem, they were done so in a way that impacted least on the base grammar instead of in a way that allowed proper document recomposition to fit these needs.

The ADM instead provides a common framework and over-arching set of rules in which profiles can be built without imposing unnecessary production and semantic restrictions. With the ability to insert new modules, elements and attributes at each pre-defined layer of the ADM, and at the same time leverage the elements exposed by the Core Module Pool, the Z39.86-AI specification unshackles production from the monolithic approach of dictated and inflexible content models.

Fundamentals

Document Structure Layers

The Abstract Document Model comprises five hierarchically-linked layers that define a document from its most general sense to its most concrete:

• the Document layer — the outermost layer that defines the overall document structure (i.e. the head and body);
• the Section layer — which defines primary structural divisions within documents;
• the Block layer — which defines the major structural elements that occur within sections of documents;
• the Phrase layer — which defines the textual constructs that compose block elements; and
• the Text layer — the mixture of Unicode character data and character elements at the root of all the bounding layers.

The five structural layers of the ADM are a significant enhancement over previous versions of the specification in that they formally lay out a set of common features for documents and improve on the limited concept of block and inline elements. The two new layers — Document and Section — abstract higher-level document structure concepts and the Text layer formally removes the ambiguity of the "inline" concept, leaving a cleaner and more obvious data modeling system in which to design and build profiles.

Moving down through the ADM, each layer is structurally subservient to the layers that contain it, also meaning that no layer can contain elements from a superordinate layer.

Document Information Layers

The ADM also comprises two specialized layers that augment and supplement the information in the document structure layers:

• the Global Attribute layer — which defines common attributes that are available to all elements in a document.
• the Meta layer — which defines metadata attributes and elements for describing information about documents and inflecting structures with semantic meaning.

These layers are not bound or constrained by the structural layers, but are available to them as needed in agreement with each structural layer's own nature and rules.

Although distinct from the structural layers and from each other, these layers behave in similar fashion in the way that they provide cross-document capabilities to annotate structures which is the reason why they are paired together as a common functionality group in the ADM.

The Meta layer exposes the means to append information about documents and embedded documents (the typical metadata found in document and article headers) while keeping that information separate from the content of those documents. It also provides attributes for attaching meta information directly to elements within the document body (e.g., providing the mechanism to distinguish the role of generalized elements).

The Global Attribute layer similarly provides a mechanism for appending common attributes across the entire xml document tree. These attributes typically provide instructions and hints to processing agents, but any attribute can be added if it meets the criteria of universal applicability (typical attributes in this layer include the specially-defined xml attributes and the internationalization attributes).

ADM Constraints

The hierarchical principle of layer containment is the core property of the ADM, and provides the foundation for the following set of constraints when creating new Z39.86-AI profiles:

1. Redefinition of the Document layer core elements is not permitted. The Document layer defines the high-level concept of a Z39-86-AI document and is a universal principle that must remain common across profiles.
2. Every element in a layer must adhere to the definition of content for that layer. This rule ensures the principle of the ADM is respected when building profiles, and prevents creators from hacking the model to force elements out of their element (e.g., to prevent block elements from being pushed into the Section layer for display purposes only). Refer to the layer definitions for the semantics of each layer in {section reference needed} for more information.
3. No element can be used outside of its layer without changing its usage context. For example, a code element from the Block layer cannot also be used in a Phrase context. This rule prevents the unintended invalidation of content models by ensuring that elements from a superordinate layer cannot accidentally be mixed with subordinate layers. It is valid for a module to provide multiple variants of the same element each for use in different layers, and is the correct solution for semantically identical elements being needed in multiple contexts.
4. All layers must be populated. Each layer must contain a fundamental member, which is typically a semantically neutral element that embodies the over-arching properties and traits of that layer. The fundamental member serves both as a generic means of applying the semantics of the layer and as an extensibility point for creating specializations. The Text layer defines Unicode character data as its fundamental member, although elements that represent character data are also allowed.

The above constraints must all be respected for a profile to be valid.

It is not a requirement that all subordinate layers be utilized when creating content models: a Block-layer element may directly contain Text-layer elements and character data, skipping the Phrase layer. Requirements in this regard are detailed in the Content Restrictions sections for each layer.

Core Class

Each layer in the ADM defines a concrete class that represents the practical schematic implementation of its abstract concepts. In RelaxNG schema terminology, the core classes are the equivalent of a name class and are implemented as such in the global-classes schema file (activation of which is a requirement for all valid profiles).

Elements and attributes are added to the classes during module activation both as individual items and as part of default content models that the classes expose. The core classes can consequently be viewed as aggregators and containers of the layers traits; they do not, in and of themselves, define traits, however.

A layer's nature and traits are defined by its corresponding section in the ADM Layer Definitions section.

ADM Layer Definitions

The following sections detail the nature and function of each of the layers in the Abstract Document Model and introduce the rules and constraints inherent to them and that apply when adding new elements and attributes.

When creating a Z39.86-AI feature, the public structures must comply with the membership constraints of the layer to which the structures are contributed.

Document

Description

The Document layer is the top-most and primary bounding layer of the ADM and represents a document in its most abstracted sense: as a container of the metadata and content.

The core content model that this layer defines cannot be changed or altered, ensuring that it remains as a universal principle across all valid Z39.86-AI profiles.

Core Class

The Document class for this layer exposes the core content model, which consists of:

• the document root element;
• the child container for document metadata (the head element); and
• the child container for the document content (the body element).

This top-level document structure is fixed and unalterable, although each container is open to extension and modification.

Modifications to the attribute set and child containers are only permitted as outlined in the Content Restrictions section below.

Fundamental Member

The fundamental member of this layer is the <document>document</document> element, as defined in the Document module of the CMP.

The fundamental member cannot be replaced or specialized.

Content Restrictions

The addition of attributes on all members of this layer is permitted, but the addition and/or modification of new elements is not.

The metadata container may contain standard metadata information about a document as well as meta information about content within the document (e.g., expansion of abbreviations, definitions of terms, etc.).

The document metadata container must always allow at least one meta element from the Meta layer.

The document metadata container must not contain content that must be rendered by user agents as document content.

The document content container typically contains members of the Section layer, however it is permitted to treat the document content container as a specialization of the Section layer's fundamental member, in which case Block layer content may be included directly within the body element.

Section

Description

The Section layer defines structurally-significant document divisions.

Structural significance is defined as the high-level grouping of content according to industry-accepted conventions for divisions, such as defined in the Chicago Manual of Style, and by grouping according to sequentially-related or subordinate headings (real and implied).

Examples include: front, body and back matter divisions, covers and other document bindings and containers, and major document divisions such as sections, parts and chapters.

Core Class

The Section class is the core class for this layer. It may be modified and extended according to the rules set out in the Content Restrictions section below.

Elements contributed to this layer are collectively referenced in the Section class of the global-classes module.

Fundamental Member

The fundamental member of this layer is the section element, as defined in the Section module of the CMP.

The fundamental member may be replaced by a specialization where appropriate.

Content Restrictions

Members of the Section layer must not allow more than one occurrence of a structural heading in their content models. If an element contains headings that are not significant to the overall structure of the document, another distinct non-structural heading type must be used to cover these cases.

Members of the Section layer can contain exclusively Block or Section layer content or a mixture of the two. Phrase and Text layer content is not permitted as direct descendants.

Block

Description

The Block layer contains structures and divisions that complement, and are subordinate to, the structurally significant divisions of the Section layer.

Block content differs from Section content in that it typically encapsulates information for a very specific component of a document or groups content for semantic reasons only.

Block content likewise differs from Phrase content in that it establishes a connection between content ordered and divided vertically on a rendered page.

Examples include: headings, tables, lists, figures, quotes and paragraphs.

Core Class

The Block class is the core class for this layer. It may be modified and extended according to the rules set out in the Content Restrictions section below.

Elements contributed to this layer are collectively referenced in the Block class of the global-classes module.

Fundamental Member

The fundamental member of this layer is the block element, as defined in the Block module of the CMP.

The fundamental member may be replaced by a specialization where appropriate.

Content Restrictions

Members of the Block layer must not allow structural headings.

Members of the Block layer can contain exclusively Text, Phrase or Block layer content or a mixture of the three.

Phrase

Description

The Phrase layer contains grammatical and other semantically significant segments that form the content of documents.

Phrase content differs from Block content in that it establishes a connection between content that flows horizontally across a rendered page.

Phrase content differs from Text content in that it does not define character data, but operates at a grammatical level.

Examples include: sentences, terms and words.

Core Class

The Phrase class is the core class for this layer. It may be modified and extended according to the rules set out in the Content Restrictions section below.

Elements contributed to this layer are collectively referenced in the Phrase class of the global-classes module.

Fundamental Member

The fundamental member of this layer is the span element, as defined in the Span module of the CMP.

The fundamental member may be replaced by a specialization where appropriate.

Content Restrictions

Member of the Phrase layer can contain exclusively Text or Phrase layer content or a mixture of the two.

Text

Description

The Text layer contains character data and character-specific elements and attributes.

Text layer content differs from Phrase content in that it only represents character data and formatting and does not infer any semantic information about itself.

Examples include: emphasis, superscripts and subscripts.

Core Class

The Text class is the core class for this layer. It may be modified and extended according to the rules set out in the Content Restrictions section below.

Elements contributed to this layer are collectively referenced in the Text class of the global-classes module.

Fundamental Member

The Text layer defines the following as having fundamental membership:

• character data, as defined in the Characters section in the XML 1.0 specification; and
• the char element.

Character data is a fixed member and cannot be removed from the layer. The char element may be replaced by a specialization where appropriate.

Content Restrictions

Profiles and features may contribute elements and attributes to this layer in order to allow expressions that are not supported by Unicode or by output formats.

The abstract document model imposes no further restrictions on the allowed character content than is already defined by the Characters definition in [XML].

Individual profiles and features may express additional restrictions on character content only within the scope of the elements and attributes that they define.

Meta

Description

The Meta layer provides the means to annotate documents and structures with meta information relating to their nature or semantics.

The meta layer includes two attributes and an element for attaching metadata information. The meta element is always allowed in the document metadata container where it is used in conjunction with the RDFa attributes.

The RDFa attributes can also be used throughout the document to attach metadata to any specific element. The Meta layer also provides the role attribute which is used by various elements in the CMP to layer additional semantic information.

Core Class

The Meta class is the core class for this layer. It may be modified and extended according to the rules set out in the Content Restrictions section below.

Elements contributed to this layer are collectively referenced in the Meta class of the global-classes module.

The use of metadata in Z39.86-AI documents is explained in more detail in section x.x.

Fundamental Member

The Meta class defines the following attributes and element as having fundamental membership:

• the meta element;
• the RDFa attribute set, as defined in the RDFa feature; and
• the role attribute.

These members are fixed and cannot be removed from the layer or replaced with specializations.

Content Restrictions

Member must not be used in contexts where their contents may be interpreted as document content.

Additional attributes and elements

Global Attributes

Description

The Global Attributes layer makes its member attributes available to all elements in a document.

Core Class

The Attrib class is the core class for this layer. It may be modified and extended according to the rules set out in the Content Restrictions section below.

Attributes contributed to this layer are collectively referenced in the Attrib class of the global-classes module.

Fundamental Member

The Attrib class defines the following standard attributes as having fundamental membership:

• the XML special attributes
• the Internationalization (i18n) attributes

These attributes are fixed and cannot be removed from the class. The requirement for their usage is set during module activation of the core attributes module.

Content Restrictions

All members of this layer must be attributes.

All elements added to the layers of the ADM should include the attributes defined in this layer in their attribute models.

Features added to a profile should allow the global attribute set on the elements they contribute, but the use of local equivalents where this is contextually necessary to avoid naming collisions and/or redefinition of existing attributes is recommended (for example, to avoid the duplication of ID attributes). All deviations must be explicitly expressed in the feature's resource directory.

Expired Prose

TODO: find a new loving home for this stuff...

Fundamentals

Specializations

The abstract definitions for each module also serve as blueprints for creating specializations of the components they contain.

TODO: is a specialization a new component or a content model modification of an existing?

When creating a profile's markup model, new elements may be introduced. While these elements are not members of the core module pool per se, TODO need some rules for this: separate namespace? etc

Features

Features differ from modules in the CMP in that they encapsulate a complete or partial implementation of an external standard. Examples of features include MathML, RDFa and XLink.

The nature of each feature included in the specification or imported into a profile must remain as defined by its host organization. Features typically do not expose their content models to extension, but exist as separate xml islands within Z39.86-AI documents. Refer to the documentation for each feature to determine what extensions are possible.

Any namespace requirements on features must also be respected; features that have not been designed to work as chameleon components must not be altered to inherit Z39.86-AI namespaces.

TODO need to mention that features enablement also impacts grammatical diffs? Features are not part of the profiles markup model?

TODO: better way to group/incorporate these URI sections?

Core namespace URI

The Z39.86-AI Core namespace URI is http://www.daisy.org/z3986/2010/.

Core module pool canonical URI

The canonical URI of the Z39.86-AI Core module pool is http://www.daisy.org/z3986/2010/schema/.

At this URI, all modules of the core module pool are available in their latest version (see core module pool versioning).

Core module pool versioning strategy