Resource directory for the Z39.98-2012 Authoring and Interchange
Content Selection Feature
version 1.0

Table of Contents

Introduction

The Content Selection feature provides a mechanism with which publishers can define alternate renditions of content fragments, and a mechanism for defining conditional expressions that allows runtime selection of these renditions.

One core use-case for this feature is to vary the information set of output documents, based on criteria such as output content type, or target consumer group. As examples,

In the Z39.98 Authoring and Interchange context, this feature may also be used to provide feature fallbacks . While a publisher would normally be in a situation where the feature support in used processing agents is known, this is not always the case, especially in a content interchange scenario. Not knowing whether a processing chain has full support for a certain feature, a publisher may choose to use the Content Selection feature to provide a fallback for that feature.

The Content Selection feature employs a conditional switch mechanism, represented by 1-n when elements appearing as children to the parent select element. There is an always-present default choice within the switch, represented by the otherwise element.

This feature is maintained by the ANSI/NISO Z39.98 advisory committee under the auspices of NISO.

Normative References

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this section are to be interpreted as described in RFC2119.

Version information

This resource directory represents version 1.0 of the Content Selection feature:

This release may not be the most recently published (current) version of the Content Selection feature. The current version should always be obtained from the static URI: http://www.daisy.org/z3998/2012/auth/features/select/current/

Identification

This feature must be identified as select in Z39.98-AI document feature declarations.

The canonical identity URI is: http://www.daisy.org/z3998/2012/auth/features/select/1.0/

Specification compliance

This version of the feature is compliant with the Z39.98-2012 Specification.

Normative schemata

The normative RelaxNG schema for version 1.0 of the Content Selection feature is z3998-feature-select.rng.

Note - this feature schema does not represent an entire document model; it is intended for inclusion in host profiles.

Available components

This feature makes the following components available for inclusion in host profiles:

Definition of terms

Content fragment

For the purposes of this feature, a content segment is an XML fragment, appearing within a when or otherwise element. When a processing agent evaluates a parent select element, the result is that one of the descendant content segments is selected for inclusion in the resulting document. (See further in processing agent Behavior Requirements below.)

Note that the when and otherwise elements are allowed to be empty, i.e. provide content fragments that when selected contribute nothing to the resulting document.

Conditional expression

An expression used at runtime to test whether a content fragment should be selected or not. The expression appears as the value of the expr attribute on the when element.

A conditional expression is syntactically a combination of one or more functions, and zero or more operators. The result of the evaluation of a conditional expression must always be a boolean.

The syntax of a conditional expression is normatively defined in EBNF Definition of the Conditional Expression.

Function

A function is the core component of a conditional expression. The return value of a function must always be boolean. A function can take zero or more arguments.

A function must not take another function as an argument, with the exception of the not() function, which always takes another function as its argument.

The literal reference to a function always uses a prefix. This prefix defines which function set the function belongs to.

The method with which function arguments are bound to system variables at runtime is application specific.

Logical Operators

The operators and and or are used when referencing more than one function in a conditional expression. These operators have the following meaning:

and:

the return value of a conditional expression is true if, and only if, all functions in the expression evaluate to true.

or:

the return value of a conditional expression is true if, and only if, at least one of the functions in the expression evaluates to true.

The and and or operators must not occur simultaneously in the same conditional expression. There is no limitation on the number of functions to be connected through logical operators.

This feature also defines the function not(), with one, and only one, argument, which must be another function. The purpose of this function is to return the value false if the argument function evaluates to true, and vice versa. Note that, contrary to all other functions, the not() function must not be prefixed.

Function Set

A Function Set is a collection of 1-n functions. The set is defined by a canonical URI, where human-readable prose is available defining the name and nature of each function included in the set.

When a function is used in a conditional expression, is uses a name prefix as a token for that URI.

The Content Selection feature provides a set of predefined function sets.

General document model requirements

The namespace of all members of the Content Selection feature element set is http://www.daisy.org/ns/z3998/authoring/features/select/.

The otherwise element must not contain descendants in the http://www.daisy.org/ns/z3998/authoring/features/select/ namespace.

Declaration of function set prefix-URI mappings

The prefix of each function set that is used in a document instance must be declared in the document instance head using meta elements with the prefix property of the Resource Directory Vocabulary.

The declared prefix must resolve to a URI which must contain a human-readable document where the processing behavior of included functions are defined. This URI serves as the canonical identifier of the function set.

In the example below, a target prefix is bound to the URI http://www.daisy.org/z3998/2012/auth/features/select/functionSets/#targetFunctionSet:

<head xmlns:res="http://www.daisy.org/z3998/2012/vocab/resourcedirectory/#">
  <meta about="http://www.daisy.org/z3998/2012/auth/features/select/functionSets/#targetFunctionSet" 
    property="res:prefix" content="target" />
</head>
      

Function set prefixes, such as target in the example above, are static throughout the document scope; they must not be redeclared locally.

Several prefixes for the same function set URI must not be declared within the document scope.

With the exception of the not() function, which is unique in that it takes no prefix, all functions in Conditional Expressions must be literally referenced using prefixes, and these prefixes must be bound to a URI using the mechanism defined above.

EBNF Definition of the Conditional Expression

Conditional Expression := function, (operator, function)*
function := ('not','(' .*')') | (qname, ('()' | '(' .*')'))
operator := 'and' | 'or'
qname := prefix ':' localname
prefix := ncname
localname := ncname
ncname := [A-Za-z][A-Za-z0-9_]*
      

Predefined Function Sets

A set of predefined Function Sets are available.

Processing agent behavior requirements

This section defines processing agent behaviors that extend the default behaviors defined in Processing agent conformance definition.

Feature supported

If a processing agent supports this feature, it must comply to the following:

Processing of the select element

While traversing the document tree, each encountered select element is replaced by the content of exactly one of its when or otherwise element descendants.

The process of selecting a when or otherwise element descendant is as follows:

  1. For each encountered select element in the given XML (sub)tree, evaluate the conditional expressions of each when child, starting with the first when child in document order:

    • If the given conditional expression uses a function from an unrecognized or unsupported function set, or if it contains an unrecognized parameter, continue processing the next sibling in document order (which is a when or otherwise element). Processing agents must issue a warning when encountering unrecognized or unsupported functions or parameters.
    • If the evaluation of the conditional expression on the current when element results in true, select the content of the current when element. If the selected content contains select element descendants, apply these steps on the selected content recursively, then return.
    • If the evaluation of the conditional expression on the current when element results in false, continue processing the next sibling in document order (which is a when or otherwise element).
  2. If none of the when element conditional expressions evaluate to true, select the content of the otherwise child, and return.

Feature recognized

If a processing agent recognizes but does not support this feature, it must employ one of the following behaviors:

Abort

Upon encountering a document instance with this feature enabled, the processing agent issues a notification, and then aborts the processing.

Fallback

While traversing the document tree, the processing agent selects the content of the otherwise child element of each encountered select element. The resulting document is identical to a processing pass in Feature supported mode where zero when element conditional expressions evaluate to true.

The abort behavior is the default; the fallback behavior must only be employed when the processing agent is explicitly instructed to do so by the client.
Processing agents that employ the fallback behavior should issue a notification.

Feature not recognized

If a processing agent does not recognize this feature, it must, as dictated in Processing agent conformance definition, abort processing and issue an error message.

Feature component definitions

The component definitions provided below follow the conventions used in Core Modules.

The Content Selection Feature

Provides a mechanism for defining alternate renditions of content fragments, and a mechanism for defining conditional expressions that allow runtime selection of these renditions.

Two variants of the select element are available: one for use in a Block context and a second for use in a Phrase context.

The Content Selection Feature: Element overview
Name Default attribute model Default content model Default usage context
select xml:id?, xml:base? sel:when+, sel:otherwise Phrase.class
select xml:id?, xml:base? sel:when+, sel:otherwise Block.class
when xml:id?, expr (text | Text.class | Phrase.class)+ sel:select
when xml:id?, expr Block.class+ sel:select
otherwise xml:id? (text | Text.class | Phrase.class)+ sel:select
otherwise xml:id? Block.class+ sel:select
The Content Selection Feature: Attribute overview
Name Default values Default usage context
expr ConditionalExpression sel:when and sel:when
selid NCName global attribute
The Content Selection Feature - Patterns
Name Definition Content
ConditionalExpression A conditional expression, as defined in Conditional Expression
The select element (Phrase)

Container for content selection declarations in a Phrase context.

The select element (Phrase)
Local name select
Namespace http://www.daisy.org/ns/z3998/authoring/features/select/
Default usage context Phrase.class
Default attribute model xml:id?, xml:base?
Content model sel:when+, sel:otherwise
Content model alterability This content model is fixed, and must not be altered when activating this module.
Optionality This element must not be omitted when activating this module.
The select element (Block)

Container for content selection declarations in a Block context.

The select element (Block)
Local name select
Namespace http://www.daisy.org/ns/z3998/authoring/features/select/
Default usage context Block.class
Default attribute model xml:id?, xml:base?
Content model sel:when+, sel:otherwise
Content model alterability This content model is fixed, and must not be altered when activating this module.
Optionality This element must not be omitted when activating this module.
The when element (Phrase)

Container for a content fragment, associated with a selection condition.

The when element (Phrase)
Local name when
Namespace http://www.daisy.org/ns/z3998/authoring/features/select/
Usage context sel:select
Usage context alterability This usage context is fixed, and must not be altered when activating this module.
Default attribute model xml:id?, expr
Default content model (text | Text.class | Phrase.class)+
Optionality This element must not be omitted when activating this module.
The when element (Block)

Container for a content fragment, associated with a selection condition.

The when element (Block)
Local name when
Namespace http://www.daisy.org/ns/z3998/authoring/features/select/
Usage context sel:select
Usage context alterability This usage context is fixed, and must not be altered when activating this module.
Default attribute model xml:id?, expr
Default content model Block.class+
Optionality This element must not be omitted when activating this module.
The otherwise element (Phrase)

Container for a content fragment to be selected if none of the preceding sel:when conditions evaluated to true.

The otherwise element (Phrase)
Local name otherwise
Namespace http://www.daisy.org/ns/z3998/authoring/features/select/
Usage context sel:select
Usage context alterability This usage context is fixed, and must not be altered when activating this module.
Default attribute model xml:id?
Default content model (text | Text.class | Phrase.class)+
Optionality This element must not be omitted when activating this module.

The following model restrictions apply to this element:

  • The sel:otherwise element must not have sel:select descendants.

The otherwise element (Block)

Container for a content fragment to be selected if none of the preceding sel:when conditions evaluated to true.

The otherwise element (Block)
Local name otherwise
Namespace http://www.daisy.org/ns/z3998/authoring/features/select/
Usage context sel:select
Usage context alterability This usage context is fixed, and must not be altered when activating this module.
Default attribute model xml:id?
Default content model Block.class+
Optionality This element must not be omitted when activating this module.
The expr attribute

The expr attribute contains a conditional expression.

Refer to the Content Selection Feature for information on syntax and function set association.

The expr attribute
Local name expr
Namespace None
Default usage context sel:when and sel:when
Value(s) ConditionalExpression
Value alterability The defined value(s) or datatype(s) are fixed, and must not be altered when activating this module.
Optionality This attribute may be omitted when activating this module.
The selid attribute

The selid attribute provides a mechanism for including ID values on elements that are repeated in more than one select condition.

The selid allows a single NCNAME as its value.

When processing a select, all selid attributes in the resulting output condition must be converted to xml:id attributes.

The selid attribute
Local name selid
Namespace http://www.daisy.org/ns/z3998/authoring/features/select/
Default usage context global attribute
Value(s) NCName
Value alterability The defined value(s) or datatype(s) are fixed, and must not be altered when activating this module.
Optionality This attribute must not be omitted when activating this module.
The Content Selection Feature - Implementations
Schema Language
z3998-feature-select.rng RelaxNG

Activation of this module depends on the global-classes and Core modules also being activated.

Informative References

Supporting software

Refer to the Z39.98-AI community portal for information on available software tools.

Appendix 1: Listing of modules in the normative schema

The below list represents the modules at the time of version 1.0 of this feature.

The occurrence of the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in documentation fields embedded in these modules are to be interpreted as described in RFC2119.