This specification defines a general manifest format for expressing information about a digital
publication. It uses [schema.org] metadata augmented to include various structural
properties about publications, serialized in [json-ld11], to enable interoperability
between publishing formats while accommodating variances in the information that needs to be
expressed.
Status of This Document
This section describes the status of this document at the time of its publication. Other documents
may supersede this document. A list of current W3C
publications and the latest revision of this technical report can be found in the W3C technical
reports index at https://www.w3.org/TR/.
GitHub Issues are preferred for discussion of
this specification. Alternatively, you can send comments to our mailing list. Please send them to [email protected] (archives).
A W3C Recommendation is a specification that, after
extensive consensus-building, has received the endorsement of the W3C and its Members. W3C recommends the wide deployment of this specification as
a standard for the Web. Future updates to this Recommendation may incorporate new features.
This specification defines a general manifest format to describe publications. It is designed to be
adaptable to the needs of specific areas of publishing, such as audiobook production, by specifying
a modular approach for creating specializations.
This specification is also intended to facilitate different user agent architectures. While it is
expected that traditional Web user agents (browsers) will be able to consume a publication manifest,
this should not limit the capabilities of any other possible type of user agent (e.g., applications,
whether standalone or running within a user agent, or even publications that include their own user
interface).
This specification does not define how user agents are expected to render publications that use the
manifest format.
1.2 Manifest Format
This section is non-normative.
A digital publication is described by its manifest, which provides a set of properties expressed using a specific shape of
JSON-LD [json-ld11] (a variant of JSON [ecma-404] for linked data).
The manifest is what enables user agents to understand the bounds of digital
publication and the connection between its resources. It includes metadata that describes
the digital publication, as a publication has an identity and nature beyond its constituent
resources. The manifest also provides a list of resources that belong
to the digital publication and a default reading order, which
is how it connects resources into a single contiguous work.
The properties of the manifest describe the basic information a user agent requires to process and
render a publication. For ease of understanding, these properties are categorized as follows:
Resource categorization properties describe or identify common sets of resources, such as the
resource list and default
reading order. These properties refer to one or more resources, such as HTML
documents, images, scripts, and metadata records.
The manifest also identifies key resources of a digital publication using link relations. These
relations are defined in the rel property of LinkedResource objects (i.e.,
the JSON objects that represent each resource in the default reading order, resource list, and links
sections).
The types of resources these relations identify are categorized as follows:
This specification defines the publication manifest as a specific "shape" of [json-ld11].
This means that the manifest SHOULD be expressed using only the syntactic
constructions defined in this specification, as opposed to all the possibilities offered by the
JSON-LD syntax.
The publication manifest also has several authoring flexibilities and compact authoring expressions.
For example, it is not always required that object types be explicitly authored, as these are
automatically generated during processing when missing (see § 4.2.4 Explicit and Implied Objects for more
information). An internal representation of the manifest data is
defined separately; see § A. Internal Representation Data Model for further details.
Consequently, a user agent does not have to be a full JSON-LD processor. User agents only need to be
able to read the manifest's specific shape and internalize the data.
1.4 Relationship to Schema.org
This section is non-normative.
Manifest properties, in particular those categorized as descriptive
properties, are primarily drawn from Schema.org and its hosted extensions [schema.org].
Consequently, these properties inherit their syntax and semantics from Schema.org, making manifest
authoring compatible with Schema.org authoring.
When a manifest item corresponds to a Schema.org property, its property definition identifies its mapping and includes the defining type (e.g., CreativeWork or Book) in parentheses.
Schema.org additionally includes a many properties that, though relevant for publishing, are not
mentioned in this specification. These properties can be used in a manifest as this document defines
only the minimal set of manifest items (see § 4.7.3.2 Additional Manifest Properties).
When using additional Schema.org properties, ensure that they are valid for the type of publication specified in the manifest. Properties are
often available in many Schema.org types, as a result of the inheritance model used by the
vocabulary, but not all properties are available for all types. For more detailed information about
which types accept which properties, refer to [schema.org].
This specification depends on the Infra Standard [infra].
Bounds
A digital publication consists of a finite set of
resources that represent its content. This extent is known as its bounds and is defined within
its manifest as described in § 5. Publication Resources.
Digital Publication
A digital publication is any publication authored in a format that uses a profile of the manifest.
Internal Representation
The internal representation of a manifest is the data structure created by user agents when they
process the manifest and remove all possible ambiguities
and incorporate any missing values that can be inferred from another source.
It is possible for the information expressed in the manifest to be the equivalent of the internal
representation created by user agents if there are no ambiguities or missing information.
Profiles are publication formats (e.g., audiobooks) that use the manifest format
defined in this specification to describe their bounds and content. These formats can
extend the core definition in this specification with profile-specific terms and/or new
requirements.
Although profiles can differ in their structural and content requirements, such variances are
restricted to maintain a high degree of predictability between formats. (See § 8. Modular
Extensions.)
3. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in
this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST
NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD, and SHOULD
NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and
only when, they appear in all capitals, as shown here.
All algorithm explanations are informative.
4. Publication Manifest
4.1 Requirements
The following properties MUST be set in the manifest:
The priority of all other properties and resource relations is OPTIONAL, but MAY
be modified by implementations of the manifest format.
Note
Some properties are implicitly required, as they are compiled from alternative
information when not explicitly authored. See § A. Internal Representation Data Model
for more information.
4.2 Value Categories
This section describes the categories of values that can be used with properties of the publication
manifest.
4.2.1 Literals
When a manifest property expects a literal text string — one
that is not language-dependent, such as a code value or date — as its value, the value MUST be expressed as a [json] string.
When a manifest property expects a number as its value, the
value MUST be expressed as a [json] number.
4.2.3 Booleans
When a manifest property expects a boolean as its value, the
value MUST be expressed as an [ecmascript] Boolean value
(true or false).
4.2.4 Explicit and Implied
Objects
Various manifest properties are expected to be expressed as [json] objects. Although the use of explicit objects is usually advised, the following sections
identify cases where it is also acceptable to use string values. These strings are automatically
translated into objects during processing of the manifest by
a user agent (the exact mapping of text values to objects is included in each definition).
4.2.4.1 Localizable Strings
When a manifest property expects a localizable text string
as its value, the value MUST be expressed as one of:
A single string value represents an implied object whose value property is the
string's text and whose language and base direction is determined from other information in
the manifest.
As localizable strings are intended to facilitate multiple language representations of a
value, properties that accept a localizable string always accept an array of these values.
For this reason, although only a single string or object has to be authored, such values are
converted to arrays for consistency of processing.
A LocalizableString is a [json] object consisting of the following properties:
ltr: indicates that the textual value is explicitly directionally set to
left-to-right text.
rtl: indicates that the textual value is explicitly directionally set to
right-to-left text.
A missing base direction value means that that the textual value is explicitly directionally
set to the direction of the first character with a strong directionality, following the
rules of the Unicode Bidirectional Algorithm [bidi].
Note
If the base direction value were not set in the last example, the text would be
displayed, following the Unicode Bidirectional Algorithm [bidi] and due to the
presence of a Latin character starting the string, as:
HTML היא שפת סימון.
However, that would be incorrect. The extra direction value is
necessary to control the display to yield:
HTML היא שפת סימון.
Note that the value field in the example represents the text as it is
stored in memory, hence the discrepancy between it and the two renderings depicted
here. Text editors might also display the JSON value differently (e.g., using the
Unicode Bidirectional Algorithm only).
See also the [string-meta] document for further explanations and examples.
4.2.4.2 Entities
When a manifest property expects an entity (i.e., an
individual or organization responsible for the various aspects of creation), its value MUST be expressed either as:
A single string value represents an instance of an Entity object whose
name property is the string's text and whose type is assumed
to be Person [schema.org].
An Entity is defined as an instance of
either the [schema.org] Person or Organization type with the following minimal property set:
This minimal set of properties is not restrictive. Authors can include any
additional properties defined for the [schema.org] Person or Organization types, as
appropriate. User agents are similarly not limited to interpreting only the preceding
properties.
4.2.4.3 Linked Resources
When a manifest property links to one or more resources, it MUST be
expressed either as:
a [json] string encoding the URL of the resources; or
References to one or more reformulation(s) of the resource in alternative
formats, where the encodingFormat specifies the format of the
reformulation. OPTIONAL.
One or more of:
a string, representing the URL of the resource
reformulation in an alternative format; or
an instance of a LinkedResource object
A string value represents an implied LinkedResource object whose
url property is set to the string value.
Although user agent support for the integrity property is OPTIONAL, user agents that support cryptographic hashing comparisons using this
property MUST do so in accordance with [sri].
This specification only defines the alternate property for selecting from
alternative formats (i.e., based on encodingFormat or by inspecting URLs). ProfilesMAY extend this behaviour to allow selection based on other
criteria. The process for selecting an alternate is described in § B.
Selecting an Alternate Resource.
Note
When defining a LinkedResource object, it is advised to always
specify the media type of the resource using the encodingFormat property.
Doing so allows user agents to more readily determine the usability of the resource.
Example 4: A resource with a SHA-256 hashing of its content.
Example 6: Resource list that includes one link using a relative URL
as a string ('datatypes.svg') and two that display the various properties of the a
LinkedResource object.
When a manifest property expects a type of object not defined in this section, or by a profile, it MUST be expressed
as a [json] object (i.e., the property's value will not be processed to create an object).
By consequence, relative-URL strings in embedded manifests are resolved against the URL of the
document that references the manifest unless the document declares a base URL (i.e., in
a <base> element in its header).
4.2.6 Identifiers
Identifiers are used to refer to a digital publication and the
entities responsible for its creation in a persistent and
unambiguous manner. URLs, URNs, DOIs, ISBNs, and PURLs are all examples of persistent
identifiers frequently used in publishing.
When a manifest property allows one or more value of their
respective type (e.g., literal, object, or URL), these values are expressed as [json] arrays. When
a property value is a single element, however, the array syntax MAY be
omitted.
4.3 Manifest Contexts
A manifestMUST set its JSON-LD context [json-ld11] with
the following two components, in the specified order:
the publication context:
https://www.w3.org/ns/pub-context
Note
Although Schema.org is often referenced using the http URI scheme, the vocabulary is being migrated to use the
secure https scheme as its default. As a result, only the https scheme
is recognized in the publication manifest context.
The publication context document adds features to the properties defined in Schema.org (e.g., the
requirement for the creator property to be order
preserving).
Profiles of this specification MAY require additional context
URLs, but such URLs
MUST be ordered after these two components.
The context can be extended by including additional parameters — such as the global language and direction declarations — in an object following
the publication context.
Each natural language property value in a manifest (e.g., title, creators) has a default natural language, which is the language that it is expressed in (e.g., English,
French, Chinese). It also has a natural base direction in which
it is written — the display direction, either left-to-right or right-to-left.
The digital publication manifest provides the ability to set both these concepts globally as well as on individual items to aid user agents in interpreting and presenting the metadata.
Note
The ability to set the base direction is a JSON-LD 1.1 [json-ld11] feature. In other words, the Publication Manifest has a
dependency on that version of the JSON-LD specification (as opposed to the earlier
1.0 [json-ld10] version).
4.4.1 Global Declarations
The global language and base direction declarations for natural language manifest properties are
set in the context using the language
and direction keywords [json-ld11], respectively. These
values are used to expand simple string values into localizable strings during the processing of the
manifest, as well as to provide a language and the base direction for localizable
strings that omit one.
The value of directionMUST have one of the following values:
"ltr": indicates that the textual values are explicitly directionally set to
left-to-right text.
"rtl": indicates that the textual values are explicitly directionally set to
right-to-left text.
The global language and base direction declaration, when present, MUST
follow the publication context.
Default values are not specified for the global language or base direction.
4.4.2 Item-Specific
Declarations
It is possible to set the language or a base direction locally for any natural language value in
the manifest using a localizable string:
The possible values of the language and direction
keywords [json-ld11] are the same as for the global declaration. Furthermore, both values can also
be the (JSON) value of null, indicating that no explicit language, respectively
direction, is set.
Note
Setting the value of language to null can be useful if a
value (e.g., the name of an organization) is commonly used without any associated language
(e.g., "Google").
A local declaration of the language, respectively the base direction, takes precedence over a global declaration.
Each Schema.org type defines a set of properties that are valid for use with it. To ensure that the
manifest can be validated and processed by Schema.org-aware processors, the manifest SHOULD contain only the properties associated with the selected type.
If properties from more than one type are needed, the manifest MAY include
multiple type declarations.
Example 16: Setting the type property for a publication that combines
properties from Book and VisualArtwork.
Example 18: Setting that a publication is abridged.
{
…
"abridged" : true,
…
}
4.7.1.2 Accessibility
The accessibility properties provide information about the suitability of a digital publication for consumption by users
with different preferred reading modalities. These properties typically supplement an
evaluation against established accessibility criteria, such as those provided in [wcag21].
The following properties are categorized as accessibility properties:
Detailed descriptions of these properties, including the expected values to use
with them, are available at [webschemas-a11y].
Note
A reference to a detailed accessibility
report can also be provided if more information is needed than can be expressed
by these properties.
Example 19: Setting accessibility metadata for a publication that
provides alternative text and long descriptions appropriate for each image, enabling
it to be read in purely textual form.
Ensuring uniqueness of canonical identifiers is outside the scope of this
specification. The actual achievable uniqueness depends on such factors as the
conventions of the identifier scheme used and the degree of control over assignment of
identifiers.
If a canonical identifier is not provided in the manifest, or the value is an invalid URL,
the digital publication does not have a canonical identifier. User agents MUST NOT attempt to construct a canonical identifier from any other
identifiers provided in the manifest.
The specification of the canonical identifier MAY be complemented by
the inclusion of additional types of identifiers using the identifier property [schema.org] and/or its subtypes.
Example 21: Setting the canonical identifier and the address as
URLs.
Use of this property might lead to inconsistent results in user agents. It is
marked as a synonym for author in [schema.org], but there is no guidance
on which takes precedence or how to combine them. It is advised to use only
one or the other, with preference given to the more specific author
property.
The global duration indicates the overall length of a
time-baseddigital publication (e.g., an audiobook or
a book consisting of a series of video clips). It is expressed using the
duration property.
The last modification date is the date when a digital publication was last updated (i.e.,
whenever changes were last made to any of the resources of the publication, including the manifest). It is expressed using the
dateModified property.
The last modification date does not necessarily reflect all changes to a publication (e.g.,
if a digital publication format allows references to third-party content). User agents SHOULD check the last modification date of individual resources to
determine if they have changed and need updating.
Example 26: Setting the last modification date of the
publication.
{
…
"dateModified" : "2015-12-17",
…
}
4.7.1.8 Publication Date
The publication date is the date on which a digital publication was originally
published. It represents a static event in the lifecycle of a publication and allows
subsequent revisions to be identified and compared. It is expressed using the
datePublished property.
The exact moment of publication is intentionally left open to interpretation: it could be
when the publication is first made available or could be a point in time before publication
when the publication is considered final.
Example 27: Setting the creation and modification date of the
publication.
A digital publication has at least one
natural language, which is the language that the content is expressed in (e.g., English,
French, Chinese). The manifest includes the following property to set this concept, which
can influence, for example, the behavior of a user agent (e.g., to preload a dictionary or
text-to-speech engine).
If a user agent requires the publication language and it is not available in the manifest, or
the obtained value is not well-formed [bcp47], the user agent MAY attempt to determine the publication language when generating its internal representation. This
specification does not mandate how such a language tag is created. The user agent might:
use the first language declaration found in a resource in the default reading order; or
calculate the language using an algorithm of its own design.
If a user agent requires a primary language for the publication and more than one language is
specified, the first entry in the inLanguage array MUST be recognized as the primary.
Note
It is important to differentiate the language of the publication from
the language of the individual resources that compose it. If such resources are, for
example, in HTML, the language needs to be set in those resources, too. The language of
the publication is not inherited.
4.7.1.10 Reading
Progression Direction
The reading progression direction establishes the
reading direction from one resource to the next within a digital publication. It is used to adapt such publication-level interactions as
menu position, touch gestures, swap direction, and tap zones for next and previous page. The
reading progression is expressed using the readingDirection property.
The default value is ltr. If the readingProgression is not set,
user agents MUST use the default value when generating their internal representation.
This property has no effect on the rendering of the individual primary resources; it
is only relevant for the progression direction from one resource to the other.
Example 28: Setting the reading progression explicitly to ltr
(left-to-right).
{
…
"readingProgression" : "ltr",
…
}
4.7.1.11 Title
The title provides the human-readable name of a digital publication. It is expressed using the name property.
If a title is not included in the manifest, the user agent MUST create one. The process for obtaining the title is defined in
§ 7.4.3 Add
Default Values.
Note
A user agent is not expected to produce a meaningful title [wcag21] for a
publication when one is not specified.
Example 29: Setting the title of a book explicitly.
It is not necessary to include a reference to the manifest in any of these
lists.
4.7.2.1 Default Reading Order
The default reading order is a specific progression
through a set of digital publication
resources. A user might follow alternative pathways through the content, but in the absence
of such interaction the default reading order defines the expected progression from one
resource to the next.
The default reading order is expressed using the readingOrder property.
A single string value represents an instance of a LinkedResource object whose
url property is the string's text.
The order of items is significant.
The URLs expressed in the reading order MAY include fragment identifiers, although profiles of
this specification MAY restrict both their use as well as what
schemes and features are supported. Fragment identifiers are to be interpreted as defined by
their respective specifications (e.g., the start location to move the user to, or the range
of content to render before moving to the next item in the reading order).
Resources SHOULD NOT be listed more than once in the reading order,
as this can lead to unexpected results in user agents (e.g., links to the resource might not
resolve to the right instance in the reading order).
The resource list enumerates any additional resources used
in the processing or rendering of a digital publication
that are not already listed in the default reading order.
It is expressed using the resources property.
A single string value represents an instance of a LinkedResource object whose
url property is the string's text.
The order of items is not significant.
To avoid conflicting information about a resource, a particular resource's URLSHOULD NOT be repeated within the resource list.
The URLs expressed in the resource list SHOULD NOT include fragment identifiers.
The completeness of the resource list can affect the usability of a digital publication in
certain reading scenarios (e.g., the ability to read it offline). For this reason, it is
strongly advised to provide a comprehensive list of all of the publication's constituent
resources beyond those listed in the default reading order.
In some cases, a comprehensive list of these resources might not be easily achieved (e.g.,
third-party scripts that reference resources from deep within their source), but a user
agent SHOULD still be able to render a publication even if some of
these resources are not identified as belonging to the publication (e.g., if it is taken
offline without them).
Example 32: Expressing the list of resources via a combination of
simple URL strings and LinkedResource objects.
The Links list is used to provide a list of resources that are
not required for the processing and rendering of a digital publication (i.e., the content of
the publication remains unaffected even if these resources are not available). Links are
expressed using the links property.
A single string value represents an instance of a LinkedResource object whose
url property is the string's text.
The order of items is not significant.
It is RECOMMENDED to use LinkedResource objects with
their rel values set.
Linked resources are typically made available to user agents to augment or enhance the
processing or rendering, such as:
a privacy policy or license that the user agent can offer a link to from a shelf;
a metadata record that the user agent can use to discover and display more information
about the publication; or
a dictionary of terms the user agent can process to provide enhanced language help.
Links can also be used to identify resources used in the online rendering of a publication,
but that are not essential to include when the publication is taken offline or packaged
(e.g., to minimize the size). These include:
large font files that enhance the appearance of the publication but are not vital to its
display (i.e., a fallback font will suffice); or
third-party scripts that are not intended for use when a publication is taken offline or
packaged (e.g., tracking scripts).
The links list SHOULD include resources necessary to
render a linked resource (e.g., scripts, images, style sheets).
User agents MAY ignore linked resources and are not required to take
them offline with a publication. These resources SHOULD NOT be
included when packaging a publication.
4.7.3 Extensibility
The manifest is designed to provide a basic set of properties for use by user agents in
presenting and rendering a digital publication, but
MAY be extended in the following ways:
This specification does not define how such additional properties are compiled, stored or exposed
by user agents in their internal representation
of the manifest. A user agent MAY ignore some or all extended
properties.
4.7.3.1 Linked records
The manifest MAY be extended through links to metadata records, such
as an ONIX [onix] or BibTeX [bibtex], using a LinkedResource object, where:
the rel property of the
LinkedResource includes a relevant identifier (e.g., if the linked
record contains descriptive metadata, the describedby identifier [iana-link-relations] can be used);
the value of the encodingFormat identifies the MIME media
type [rfc2046] defined for that particular type of record, if
applicable.
Linked records are included in the resource list when they are
part of the publication (i.e., are needed for more than just manifest extensibility).
Otherwise, they are included in the links list.
Example 33: Linking to an external ONIX for Books metadata
record.
The application/onix+xml MIME type has not yet been registered by
IANA at the time of writing this document and is included in the example for
illustrative purposes only.
4.7.3.2 Additional
Manifest Properties
Additional properties MAY be included directly in the manifest using
public schemes like [schema.org] or [dcterms]. Proprietary terms MAY be used, but it is
RECOMMENDED that such terms be included using Compact IRIs [json-ld11], with prefixes defined as part of the context.
Note
Proper use of prefixes and compact IRIs is necessary to use a manifest with a
full JSON-LD processor, but is not a requirement for the processing algorithm defined by this specification. Validation of prefixed
terms has to be carried out separately if full JSON-LD processing is expected.
Example 34: Extending the basic data set using a vocabulary prefix
declaration.
The Schema.org context file
[schema.org] defines several prefixes for commonly used
vocabularies, such as the Dublin Core Terms (dcterms) [dcterms] and Element Set (dc) [dc11], the FOAF
vocabulary (foaf) [foaf], and the Bibliographic Ontology (bibo) [bibo]. Properties from these
vocabularies can be used without their prefixes having to be declared.
Example 35: Extending the basic data using the Schema.org
'copyrightYear' and 'copyrightHolder' terms.
The cover is a resource that user agents can use to present a digital publication (e.g., in a library or
bookshelf, or when initially loading the publication).
The cover is identified by the cover link relation.
The link to the cover MUST NOT be specified in the links list.
Editor's note
The cover term is not currently registered in the IANA link
relations, but the Working Group expects to add it.
If the cover is an image (whether embedded in an HTML resource or not), it is strongly
advised to follow Success Criterion
1.1.1 [wcag21] for the
provision of alternative text and extended descriptions. For image formats that do not
provide the ability to embed this information, the name and description properties of LinkedResource can be used to provide alternative
text and extended descriptions, respectively. In these cases, the name property
SHOULD always be set — the property can be left empty for
decorative images.
Example 38: Identifying a cover image. Alternative text and a
description are provided in the name and description properties,
respectively.
{
…
"resources" : [
{
"type" : "LinkedResource",
"url" : "whale-image.jpg",
"encodingFormat" : "image/jpeg",
"rel" : "cover",
"name" : "Moby Dick attacking hunters",
"description" : "A white whale is seen surfacing from the water to attack a small whaling boat"
},
…
],
…
}
Example
39: A decorative cover. The name property is left
empty.
If a user agent requires alternative text for a cover image to make an interface accessible,
and the name property is not specified, it MAY attempt
to construct the alternative text from the publication metadata. This specification does not
mandate how such alternative text is created. One method is to construct the alternative
text as a string that identifies that the image as the cover, followed by the publication title.
Only one resource MAY be identified as the cover, but additional
covers MAY specified using the alternate property (e.g., to provide alternative dimensions or
resolution).
Example 40: Providing a cover image in JPEG and SVG formats.
The page list is a navigational aid that contains a list of static page demarcation points
within a digital publication.
The page list is identified by the pagelist link relation.
Editor's note
The pagelist term is not currently registered in the IANA link
relations but the Working Group expects to add it.
Only one resource MAY be identified as containing a page list. If
multiple instances are specified, user agents MUST use the first
instance encountered, with precedence given to the reading
order.
The link to the page list MUST NOT be specified in the links list.
Example
41: Identifying the resource that contains the page
list.
The table of contents is a navigational aid that provides links to the major structural
sections of a digital publication.
The resource that contains the table of
contents is identified by the contents link relation [iana-link-relations]. The table of contents proper
is the first element inside that resource with the role value
doc-toc, as defined in § C.2 HTML Structure.
Only one resource MAY be identified as containing the table of
contents. If multiple instances are specified, user agents MUST use
the first instance encountered, with precedence given to resources in the reading order.
Profiles of this specification MAY define how to locate a
resource containing the table of contents when no resource is identified by the
contents relation.
The link to the table of contents MUST NOT be specified in the links list.
An accessibility report provides information about the suitability of a digital publication for consumption by
users with varying preferred reading modalities. These reports typically identify the result
of an evaluation against established accessibility criteria, such as those provided in
[wcag21], and are
an important source of information in determining the usability of a publication.
An accessibility report is identified using the accessibility-report link
relation.
Editor's note
The accessibility-report term is not currently registered in the
IANA link relations but the Working Group expects to add it.
It is helpful to include the report as a resource of the publication so that it is available,
for example, when a publication is read offline.
Note
Providing the accessibility report in a human-readable format, such as HTML
[html], helps ensure that it can be accessed and
understood by users. Augmenting the report with machine-processable metadata, such as
provided in Schema.org [schema.org], will
additionally aid in machine processing.
Example 43: Setting a link to an accessibility report.
Not all digital publications will be available to
all users (e.g., they might be restricted to registered users of a site). In such cases, the
publisher might wish to provide a preview of the content to entice users to access the full
version.
A preview is identified using the
preview link relation [iana-link-relations].
Previews MAY be located externally or included as resources of
digital publications.
Example 44: Identifying a preview as an audio resource of a digital
publication.
Users often have the legal right to know and control what information is collected about
them, how such information is stored and for how long, whether it is personally
identifiable, and how it can be expunged. Including a statement that addresses such privacy
concerns is consequently an important part of publishing digital publications. Even if no information is collected, such a declaration
increases the trust users have in the content.
A link to a privacy policy can be included in the manifest for this purpose. It is helpful to
include the privacy policy as a resource of the publication so that it is available, for
example, when a publication is read offline.
A privacy policy is
identified using the privacy-policy link relation [iana-link-relations].
Example
46: Identifying a privacy policy via an external link.
If additional relations beyond those defined in this specification need to be expressed, the rel property can be extended in one of the
following ways:
All other resources are outside the bounds of the digital publication (e.g., resources listed in the links section and hyperlinks in the content to external resources on the
Web).
This specification does not place any restrictions on publication resources, but profiles of this
specification MAY restrict both the content type and location of resources.
User agents MAY opt to process and render resources differently depending on
whether they are within the bounds of a digital publication (e.g., exclude external resources from an
offline or packaged version of a publication).
6. Manifest Discovery
6.1 Linking
Links to the manifest MUST take one or both of the following forms:
An HTTP Link header field [rfc5988] with its
rel parameter set to the value "publication".
Digital publication formats MAY define alternative methods of discovering a manifest that do no involve linking to, or
embedding, a manifest (e.g., that manifest could be discovered using a restricted name and/or
location). This specification does not add any restrictions on such methods.
7. Processing a Manifest
This section depends on the Infra Standard [infra].
7.1 Introduction
This section is non-normative.
Although a digital publication's manifest is authored as
[json-ld11], the steps for processing a manifest described in this section detail
how a user agent transforms the manifest into its internal
representation of the data. The algorithm describes the process using the terminology and
data types defined in [infra], and, if successful results in an [infra] map of the data
being returned.
Note
An actual implementation of this algorithm will use the corresponding constructs and
data types of whatever language is used.
validation
error — a non-terminating error that occurs when the value of a key does match its expected input.
fatal error — a terminating
error that results, for example, when a manifest cannot be processed or does not match critical
validity constraints.
User agents SHOULD expose both validation and fatal errors, but this
specification does not prescribe the way this is done.
For validation errors, user agents SHOULD differentiate the severity of the
error (i.e., whether a required or recommended practice has been violated).
7.3 Processing Contexts
Some steps in the processing algorithm depend on the expected value
category of a term, so the context in which a term is used can affect processing (e.g., url expects an Array of URLs only when the direct property of the Publication
Manifest). To differentiate these uses, a context is provided to certain
function calls. This context is set to the type of object that initiates the processing call.
The default list of recognized
types includes Person, Organization and
LinkedResource. ProfilesMAY extend this list to include additional object types.
If a context is not provided to a function, the term being processed is considered part of the global
context (i.e., it is a direct child of the manifest).
Note
When extending the list of recognized types, the normalize
data function might also need to be extended to ensure that all objects have their type
specified (e.g., when string values are automatically expanded to objects).
7.4 Generate the Internal
Representation
This algorithm takes the following arguments:
text: a UTF-8 string representing the manifest.
base: a URL string that represents the base URL for the manifest.
This algorithm does not describe how the manifest is discovered and obtained. The steps
by which to do so are defined by each digital publication
format.
To generate the internal representation, run the following
steps:
Publication manifests have to be expressed as JSON objects, not arrays. After converting
the manifest to [infra] types, an additional check is made that
the resulting structure is a map.
(§ 4.3 Manifest
Contexts) If manifest["@context"] is not set to a list, or the first and second items in
manifest["@context"] are not the string values
"https://schema.org" and "https://www.w3.org/ns/pub-context",
in this order, fatal error, return failure.
Explanation
If the context URLs are not set as
expected, the JSON data does not represent a publication manifest.
(§ 4.6 Profile
Conformance) Let processed["profile"] be the profile the
manifest conforms to. Set processed["profile"] as follows:
If manifest["conformsTo"] is not set, or does not include a profile the
user agent recognizes as capable of processing and/or rendering, the user agent SHOULD inspect the media type(s) of the resources in the
reading order to determine if the publication matches a profile it is capable of
processing or rendering. If so, validation error,
set processed["profile"] to the matching profile. Otherwise, fatal error, return failure.
Otherwise, set processed["profile"] to the first URL in
manifest["conformsTo"] the user agent is capable of processing and/or
rendering.
Note
The value of manifest["conformsTo"] could be a string or a list at this step in the process.
Explanation
The profile the publication conforms to determines any additional extension steps that
have to be performed during processing. These steps are defined by their respective
specifications.
The new term profile is created because conformsTo is not
restricted to profile identifiers (i.e., the new term provides a persistent identifier
of the profile within the internal representation).
(§ 4.4.1
Global Declarations) Let lang be the global language and
dir be the global direction obtained from this step. Set each initially to an
empty string.
For eachcontext of manifest["@context"], moving from the last item to the first, if
context is a map:
if lang is an empty string and context["language"] is defined, set lang to
context["language"];
if dir is an empty string
and context["direction"] is defined, set dir to
context["direction"];
if neither lang nor dir is an empty string, then break.
If dir is neither an empty string nor one of the values "ltr" or "rtl", validation error, set dir to an
empty string.
Explanation
The global language and direction declarations obtained here are used to set the language
and base direction, respectively, for localizable strings without a declaration.
The iterator moves backwards through @context as the last language and
direction declarations override any earlier ones.
(§ 4.3 Manifest
Contexts) If a profile requires additional validation of the manifest
context, those steps are performed here.
Explanation
This extension step allows verification of any information a profile requires be present
in the manifest context (e.g., additional context URLs or parameters). These steps have to be
performed at this point, as @context terms are removed as part of the data normalization in the next step. A more general
step for processing profile data is provided at a later
step.
For eachterm → value of manifest, set processed[term] to
the result, when successful, of calling normalize data given
term, value, lang, dir and base.
If failure is returned, do not add term to processed.
Explanation
The data normalization steps standardize the incoming manifest data to remove any
authoring conveniences, such as the ability to use strings where objects or arrays are
expected. The resulting processed data are added to the processed variable
and are operated on in subsequent steps.
Set processed to the result of running data
validation given processed.
Explanation
The data validation checks ensure that the incoming data matches its expected value
categories. Any restrictions on the expected values are also enforced at this step, and
any invalid data is removed from the final representation.
If a profile specifies additional processing functions that
need to be run, those steps are executed at this point.
Set processed to the result of running add
default values, when successful, given processed and document,
when specified. Otherwise, terminate processing, return failure.
Explanation
This step checks if any information missing from the manifest can be obtained from the
HTML document that links to the document, or from other sources.
The data normalization steps are performed on the copy of the incoming value held in
the normalized variable defined in this step. This variable is returned
at the end of a successful normalization process.
@context provides information for the initial processing of the manifest,
but is not retained in the internal data representation. Returning a failure signals
to remove the term.
(§ 4.2.7 Arrays)
If, depending on context, term expects an array and value is not a list, set normalized to
the list:
« value ».
Explanation
Various terms require their values to be arrays, but, for the sake of convenience,
authors are allowed to use a single value instead of a one element array. For
example,
otherwise, if entity["type"] is not set, set it to the list:
« "Person" ». If entity["type"] is set but
does not include the value Person or Organization, append the value
Person to the list.
Explanation
Creators (authors, editors, etc.), are expected to be explicitly defined as an
object, but, for the sake of convenience, only their name has to be specified in the
manifest. For example:
If item["language"] is not set, set it to the value of
lang when lang is set and is not an empty string.
Otherwise, if item["language"] is null, removeitem["language"].
If item["direction"] is not set, set it to the value of
dir when dir is set and is not an empty string.
Otherwise, if item["direction"] is null, removeitem["direction"].
Explanation
Natural language text values are expected to be explicitly defined as localizable
string objects, but, for the sake of convenience, can be simple strings in the
manifest. For example, if no language information has been provided via the global language declaration then:
otherwise, if resource is not a map, validation error, remove
resource from normalized.
otherwise, if resource["type"] is not set, set it to the list:
« "LinkedResource" ». If resource["type"]
is set but does not include the value LinkedResource, append that value to
the list.
Explanation
Resource links are expected to be explicitly designed as an object of type
LinkedResource, but, for the sake of convenience, only their
absolute or relative URL has to be specified in the manifest. For example,
if normalized is a string, set normalized to the result of running convert to absolute URL, when
successful, given normalized. If failure is returned, return
failure.
otherwise, if normalized is a list, for eachitem of normalized, set item to the result of
running convert to
absolute URL, when successful, given normalized. If failure
is returned, removeitem from normalized.
(§ 8. Modular
Extensions, extension point) If a profile defines processing
steps for profile-specific terms, those steps are executed at this point.
Recursively check normalized as follows to ensure that all properties get
normalized:
if normalized is a list, for
eachitem of normalized that is a map:
if item["type"] is set and includes a recognized
type, for
eachkey → keyValue of item, set
key to the result of running normalize data, when successful,
given key, keyValue, lang,
dir, base and using item["type"] as
the context. If failure is returned, removekey from item.
if normalized["type"] is set and includes a recognized
type, for
eachkey → keyValue of normalized, set
key to the result of running normalize data, when successful,
given key, keyValue, lang,
dir, base and using
normalized["type"] as the context. If failure is
returned, removekey from normalized.
otherwise, do nothing.
otherwise, do nothing.
Explanation
To ensure that all the properties in the manifest get processed, this step
recursively checks normalized for additional map entries to process. If
normalized is a list, each item is inspected to determine if it is a
map that can be processed.
If a failure is returned, the item is removed from the map.
return normalized.
7.4.1.1 Convert to Absolute
URL
To convert to absolute URL
url, with a base URL base, run the following steps:
If url or base is not a string, or is an empty string,
validation error, return failure.
Explanation
This step checks that both url and base are non-empty
strings before attempting to use them.
Set url to the result of running the URL
parser [url], when successful, with
url as input and base as the base URL. If failure is
returned, validation error, return failure.
Explanation
This step calls the URL parser function on the url to be processed. If the url is
not an absolute URL, the parser converts it to one using the base URL.
If parsing returns a failure, a failure is returned to the caller to indicate to
remove the URL.
Return url.
7.4.2 Data Validation
To perform data validation on mapdata, run the following steps:
For eachterm → value of data, set term to the result
of running the global data checks,
when successful, given term and value. If failure is returned,
remove data[term].
Explanation
This step passes each entry to a set of global validation checks that need to be run
on the value and recursively on any properties within the value.
A failure is returned if the property is invalid and has to be removed.
If a profile specifies data validation checks, those
steps are executed at this point.
Explanation
Profile validation steps are prioritized over the default steps so that if profiles
have, for example, different default values to apply, those values get applied.
(§ 4.7.1.2
Accessibility) If data["accessModeSufficient"] is set, for eachitem of data["accessModeSufficient"], if item["type"]
is not set or does not contain
"ItemList", removeitem from data["accessModeSufficient"].
If readingOrder is set, let readingOrderURLs be the result
of running get unique URLs given
readingOrder. Otherwise, let readingOrderURLs be an
empty ordered set.
If resources is set, let resourcesURLs be the result of
running get unique URLs given
resources. Otherwise, let resourcesURLs be an empty ordered set.
Set data['uniqueResources'] to the union of
readingOrderURLs and resourceURLs.
Explanation
This step gets the list of unique URLs
within the reading order and the resource list. It then sets
data['uniqueResources'] the union of these two sets, which represents
the complete list of unique resources within the bounds of the publication.
This step also warns if either the readingOrder or resources
contains duplicate resource declarations. The validation errors are emitted as part
of obtaining the unique URLs from
each list.
if link["rel"]contains any of the
case-insensitive values "contents", "pagelist" or
"cover", validation
error, removelink from data["links"].
Explanation
After obtaining the list of unique publication resources in the previous step, the
links property is checked to ensure that any linked resources are not also listed as
publication resources.
If the link does not specify a rel value, a warning is raised. If its
rel property specifies a structural resource, the link is removed,
as structural resources have to be within the publication bounds.
If the cover(s) have an encodingFormatentry that specifies an
image media type (image/*), and do not have a nameentry, validation error.
Explanation
This checks the resources specified in the reading order and resource list to verify
that only one instance of a table of content, page list and cover have been
specified.
For covers, it also checks that a name has been set on image-based formats for
accessibility purposes.
For eachterm → value of data, if running remove empty arrays given the variables
term and value returns failure, removedata["term"].
Explanation
As the processing of the manifest involves removing invalid values at various stages,
the final data structure might end up with some lists that not no longer contain any
values. This step iterates back over the data and removes any such empty lists.
Return data.
7.4.2.1 Global Data Checks
To process the global data checks on a property
term's value with an optional contextcontext, run these steps:
This step verifies that the value of the term matches the expected category
required for the term. For example, the abridged term requires a boolean value,
so any other value used with the term will result in a failure.
If a failure occurs calling the function, this step also returns a failure so
that the property is removed from the final data set.
Terms without a known value category are not processed, so the incoming value is
returned.
Recursively descend into value as follows to check any sub-properties
first:
if value["type"] includes a recognized type, for eachkey → keyValue of value, set
value[key] to the result of running global data checks, when successful, given key,
keyValue and using value["type"] as the
context. If failure is returned, removevalue[key].
otherwise, do nothing.
otherwise, if value is a list, for eachitem of value, if item is a map:
if item["type"] includes a recognized type, for eachkey → keyValue of item, set
item[key] to the result of running global data checks, when successful, given key,
keyValue and using item["type"] as the
context. If failure is returned, removeitem[key].
otherwise, do nothing.
otherwise, do nothing.
Explanation
To ensure that all the properties in the manifest get processed, this step
recursively checks each entry for additional map entries to process. If the
value is a list, each item is inspected to determine if it is a map that can be
processed.
Its placement also ensures that all subproperties are checked first, so that the
higher-level checks later in the step are tested after any invalid values are
removed.
if item["direction"] is set and its value is not one of
"ltr" or "rtl", validation error, removeitem["direction"].
Explanation
This step checks that localizable strings have values, that their language
declarations are well formed, and that their direction declarations have either
the value "ltr" or "rtl".
if item does not match the expected value category of the
array, validation error, removeitem from value, then continue.
if item is a map, for eachkey → keyValue of item, if
key has an expected value category, set
key to the result of running verify value category given key,
keyValue, and using item["type"] as the
context. If the result of processing item is an empty map, validation error, removeitem from value.
If the result of processing value is an empty array, validation error, return
failure.
Otherwise, if, depending on the context, term expects a map:
otherwise, for eachkey → keyValue of value, if key
has an expected value category, set key to the result of running
verify
value category given key, keyValue and using
value["type"] as the context. If the result of processing
value is an empty map, validation error, return
failure.
Note
This step currently only exists for use by profiles. The properties defined in this specification all accept arrays of objects.
Otherwise, if, depending on the context, value does not match
the expected value category of term, validation error, return failure.
Return value.
Explanation
This function checks that the value of the term being processed matches its expected
value category. The function is recursively called when the value is a list or map to
ensure that all properties in the manifest get checked.
7.4.2.3 Get Unique URLs
To get unique URLs from resources, run the following steps:
This function takes a list of LinkedResource objects — from either the
reading order or resource list — and returns the set of unique URLs. If duplicates are encountered,
warnings are issued.
7.4.2.4 Remove Empty Arrays
To remove empty arrays from a property
term's value, run these steps:
Otherwise, if value is a map, for eachkey → keyValue of value, if running remove empty arrays given
key and keyValue returns failure, removevalue[key].
Explanation
This function checks that the value of the term being processed is not an empty list. A
term that initially has a list can lose entries as it gets processed (i.e., when the
list items are invalid).
7.4.3 Add Default Values
To add default values for missing properties in mapdata with an optional HTML Document
(DOM) Node [html] document, run the following steps:
Let title be an empty map. Set its values as
follows:
if document is set, if the title element [html] of document is set and is not
empty, set title["value"] to the text content of the
title element.
Set title["language"] to the language [html], if
available, and title["direction"] to the base direction [html] if that value is available and its value is
either "ltr" or "rtl".
otherwise, validation error, generate a value for
title["value"] (see the separate note for details). Set title["language"]
and title["direction"] as appropriate for the generated
title.
If the Digital Publication consists only of the referencing document, the default
reading order can be omitted; it will consist, automatically, of that single
resource.
If a profile specifies default values the user agent has
to generate, those steps are executed at this point.
If the page that links to the manifest is not listed as a unique resource of the
publication after processing core and extension default value rules, an error is
raised as it has to be a publication resource.
Return data.
8. Modular Extensions
The manifest format defined in this specification is designed to be implemented and extended by
publishing communities in the production of new profiles (e.g., audiobooks and scholarly
publications). The flexibility the manifest format offers allows it to be tailored to each community's
specific needs while also providing a common base for user agents that need to process the profiles
(i.e., minimizing the differences between each profile and simplifying interoperability).
For a profile to be compatible with this specification, the following conditions MUST be met:
It MUST adhere to the requirements for constructing a manifest as defined
in § 4. Publication
Manifest.
It MUST define a unique conformance URL and require that conforming
publications include this URL in their conformsTo
property.
One or both linking methodsMUST be used in the discovery of the manifest.
The generic processing steps described in § 7. Processing a ManifestMUST remain valid for the extended manifest. To achieve this, and if new
terms are added to the general manifest, then:
The term SHOULD be categorized, if applicable, to one or more of
the general term categories used in the algorithm (e.g., array or
localizable string). This means the relevant
processing steps will be automatically executed for those terms
If necessary, the profile MAY define its own processing step(s), to
be executed at the designated extension points within the processing algorithm. Such extra steps MUST NOT invalidate
the results of any of the steps defined for the processing
algorithm in general.
Editor's note
Adding an example of a term added by, e.g., the audiobook profile would be a good idea,
when available.
Some additional general considerations for profiles include:
The location of resources is not defined at the manifest level, so profiles that allow references to
remotely hosted resources will need to be concerned with Web security principles (e.g., cross-origin
resource sharing).
The manifest allows personally identifiable information about a digital publication's creator(s)
(e.g., names, identifying URLs) to be included, so
authoring tools could expose unexpected information if explicit author approval of metadata is not
required.
More specific security and privacy considerations are left to each profile to detail, as these will vary
depending on the nature of the digital publication format.
A. Internal Representation Data
Model
This section is non-normative.
The manifest includes several authoring conveniences, such as default values, the ability to use strings
where objects would normally be required, and the automatic compilation of information from other
sources (e.g., for the title and reading
order). The processing of the manifest normalizes these
conveniences and results in a consistent data set for user agents (the internal representation), but this set is not easily
visualized from the processing algorithm.
This appendix provides an informative abstract data model using [WebIDL] that describes the
resulting data structure. This definition expresses the expected names, datatypes, and possible
restrictions for each member of the manifest after processing.
Note
The choice of WebIDL is only for illustrative purposes. This specification does not define
an API for exposing the manifest data.
if alternate["encodingFormat"] is set and the user agent supports the
specified media type, append to
possibleAlternates.
otherwise, if a profile defines additional selection criteria,
evaluate alternate against them in this extension step.
otherwise, optionally inspect alternate["url"] for clues about the media type.
If the resource appears to be supported, appendalternate to possibleAlternates.
If possibleAlternates is an empty list, return failure.
Otherwise, if the size of
possibleAlternates is 1, return the resource from
possibleAlternates.
Otherwise, return a resource from possibleAlternates as determined by the user
agent.
Explanation
This function iterates the alternative formats for a resource and compiles a list of possibilities.
If more than one possibility is found, the user agent determines how to prioritize and select the
best alternative.
User agents are not required to add alternatives to the list of possibilities if they do not specify
an explicit media type.
C. Machine-Processable Table of
Contents
C.1 Introduction
This section is non-normative.
To facilitate navigation within pages and across sites, HTML uses the nav
element [html] to express lists of links. Although generic in nature
by default, the purpose of a nav element can be more specifically identified by use of
the role
attribute [html]. In particular, the doc-toc role from
the [dpub-aria-1.0] vocabulary
identifies the nav element as the digital
publication's table of contents.
Including an identifiable table of contents is an accessible way to produce any digital publication, but due to the flexibility of
HTML markup, it also presents challenges for user agents trying to extract a meaningful hierarchy of
links (e.g., to provide a custom view available from any page). To avoid duplicating the tables of
contents for different uses, this section defines a syntax that is both human friendly and commonly
used while still providing enough structure for user agent extraction.
Authors have a choice of lists (ordered or unordered) to construct their table of contents. By
tagging each link within these lists in anchor tags (a elements), user agents can easily differentiate the information they
need from any peripheral content (asides) or stylistic tagging that has also been added. The table
of contents can consist of both active links (with an href attribute) and inactive
links (excluding the href attribute), providing additional flexibility in how the table
of contents is constructed (e.g., to omit links to certain headings or only link to certain content
in a preview).
Note, however, that user agents are not required to preserve the presentational
aspects of the table of contents (i.e., the user agent is typically extracting the information in
order to present it in a common way across all publications). User agents are only expected to
retain the text content of the link elements, for example, so text styling, inline images and other
non-text content might be lost. Similarly, list styling and even how many levels deep of linking to
display are at the discretion of the user agent. For this reason, linking to the presentational
table of contents so that users are not limited to the machine-processed one is advised.
C.2 HTML Structure
The table of contents is expressed via an [html] element (typically a nav
element). This element MUST be identified by the role
attribute [html] value "doc-toc" [dpub-aria-1.0], and MUST be the first element in the document in document tree order [dom]
with that role value. The element MAY be hidden from
users.
Although the content model of the nav element is not restricted, user agents will only
be able to extract a usable table of contents when the following markup guidelines are followed:
Table of Contents Title
Although a title for the table of contents is optional, to avoid having a user agent generate
a placeholder title when one is needed, it is advised to add one. Titles are specified using
any of the [html] h1 through h6 elements. Note that only the first such
element is recognized as the title. If a heading element is not found before the list of links, user agents will assume that one has not been
specified.
List of Links
The first [html] ol or ul list element encountered in the nav element is
assumed to contain the list that defines the links into the content. This list will be found
even if it is nested inside of div elements, for example, as the algorithm ignores elements that are not relevant to its
processing. The list cannot occur inside of any skipped
elements, however, since their internal contents are not evaluated.
If the nav element does not contain one of these elements, then user agents will
not register the digital publication as containing a usable table of contents (e.g., a
machine-rendered option will not be available).
Branches
If the table of contents is considered as a tree of links, then each list item (li element) inside of the list of
links represents one branch. Each of these branches has to have a name and optional
destination in order to be presented to users, and this information is obtained from the
first a element found within the list item, wherever it is nested (again, excluding any
a elements inside of skipped
elements.)
The link destination for the branch is obtained from the a element's
href attribute, when specified. This attribute can be omitted if a link is
not available (e.g., in a preview) or not relevant (e.g., a grouping header). When providing
a link into the content, it is also possible to specify the relation of the linked document
(in a rel attribute) and the media type of the linked resource (in a
type attribute).
After finding the a element that labels the branch, user agents will continue to
inspect the markup for another list element (i.e., sub-branches). If a list is found, it is
similarly processed to extract its links, and so on, until there are no more nested branches
left to process.
Skipped Elements
A small set of elements are ignored when the parsing table of contents to avoid
misinterpretation. These are the [html] sectioning
content elements and sectioning
root elements. The reason they are ignored is because they can define their own
outlines (i.e., they can represent embedded content that is self-contained and not
necessarily related to the structure of content links).
Any element that has its hidden attribute set is also skipped, since hidden elements are
not intended to be directly accessed by users.
Although these elements can be included in the nav element, care has to be taken
not to embed important content within them (e.g., do not wrap a section element
around the list item that contains all the links into the content).
Ignored Elements
All elements that are not relevant to extracting the table of contents, and are not skipped, are ignored. Unlike skipped elements, ignoring
means that user agents will continue to search inside them for relevant content, allowing
greater flexibility in terms of the tagging that can be used.
C.2.1 Examples
This section is non-normative.
C.3 User Agent Processing
This section depends on the Infra Standard [infra].
This section defines an algorithm for extracting a table of contents from a nav element.
It is defined in terms of a walk over the nodes of a DOM tree, in tree order [dom],
with each node being visited when it is entered and when it is exited during the
walk. Each time a node is visited, it can be seen as triggering an enter or exit
event. In some steps, user agents are provided a choice in how to process the content to provide
flexibility for different presentation models.
Note
This algorithm is not defined in purely event driven terms, as inspecting all descendant
nodes is not always necessary to obtain the needed information from the DOM. In some cases, an
element, and all its descendants, is skipped immediately after it is processed on
enter. An event approach could be applied but would require modifying the algorithm to
process/ignore the skipped nodes.
Note
User agents can process and internalize the resulting structure using any language that
can represent the final form of the data.
For the purposes of this algorithm, a list element is defined as
either an [html] ol or ul element.
The following algorithm MUST be applied to a walk of a DOM subtree rooted at
the first element in document order with the role attribute value doc-toc,
regardless of whether the element has been declaratively hidden [html] or styled by CSS not to be visible:
Note
The rules for locating the resource containing the table of contents element are defined
in § 4.8.1.3 Table of
Contents.
If a table of contents element is not found, the publication does not have a table of contents that
can be used for machine rendering purposes.
Let toc be the map«[ "name" → "", "entries" → « » ]» representing the table of contents.
Explanation
This step initializes the map that will store the title and the branches of the table of
contents. In this map:
toc["name"] represents the title of the table of contents.
toc["entries"] represents the branches of the table of contents.
Initialize the stackbranches to hold branches of the table of contents as they are created.
Explanation
The stack is used to hold branches that are not yet complete. As a new sub-branch is
encountered, the parent gets pushed onto the stack so it can be retrieved later.
current_toc_node is used to hold the map that represents the branch of the
table of contents that is currently being processed.
Walk over the DOM in tree
order [dom], starting with the element the table of
contents is being built from, and trigger the first relevant step below for each element as
the walk enters and exits it.
If branches is empty, and toc["name"] is an empty string, set
toc["name"] to one of the following:
the descendant content of the element (to preserve any HTML tags);
the text string obtained from the descendant content (e.g., by
calculating the accessible name [accname-1.1] of the element).
If the resulting value of toc["name"] is an empty string (e.g., after
removing any presentational elements and trimming all leading and trailing
whitespace), set toc["name"] either to a placeholder value or to
null.
Skip further processing of the element and continue to the next.
Explanation
This step identifies the heading for the table of contents. A heading is only
processed if the value of toc["name"] is an empty string (i.e., no
headings have yet been encountered).
Whether a user agent sets name to the descendant content of the
heading element, or generates a text string from it, depends on whether it will
re-use any descendant tagging in the presentation (e.g., to retain images,
MathML, ruby and other content that does not translate to text easily).
Example 69: Visualization of the toc object with a
heading.
«[
"name" → "Contents",
"entries" → « »
]»
If name is not an empty string, or is null, then a
previous heading has already been encountered or content has been encountered
that indicates the nav element does not have a heading (e.g., a
list has already been processed, since the heading would not follow the list of
links).
Example 70: Visualization of the toc object without a
heading.
«[
"name" → null,
"entries" → « »
]»
If a heading is not specified, the user agent can provide its own for later
use.
If current_toc_node["entries"] is null or a non-empty
list, skip further
processing of the element and continue to the next.
Otherwise, pushcurrent_toc_node onto branches and then set
current_toc_node to null.
Otherwise, if branches is empty:
If toc["entries"] is null or a non-empty
list, skip further
processing of the element and continue to the next.
Otherwise, do nothing.
Explanation
This algorithm does not process multiple lists in a single branch or at the root
of the nav element, so if a list has already been encountered (the
entries property contains one or more branches or is set to null), this list is
skipped.
If a list is encountered and the table of contents (toc) still does
not have a name (i.e., no heading element has been encountered), the table of
contents is assumed to not have a heading (i.e., the heading for the table of
contents cannot appear after the first list of entries). The value of the
name property is changed from an empty string to null as no further headings
encountered apply, either.
If branches is not empty, pop the top map from
branches and set current_toc_node to it.
Otherwise, if toc.entries contains an empty list, set it to null.
Explanation
This step resets current_toc_node back to the parent object after all
of its child branches have been processed.
If there are no branches in the stack, the toc.entries is set to null
if it doesn't contain any items (to avoid processing any further lists at the
root level).
When entering a list item element, set current_toc_node to the following map:
Each list item represents a possible new branch in the table of contents, so
whenever one is encountered a new blank object is created in
current_toc_node.
This object gets populated with information as a descendant a
element and list are encountered.
If current_toc_node["entries"] contains an empty list, set it to null.
If current_toc_node["name"] is null or an empty
string:
if current_toc_node["entries"] is not null, set
current_toc_node["name"] to a placeholder value or null;
otherwise, set current_toc_node to null and exit this
processing step.
If branches is not empty, appendcurrent_toc_node to the entries property of the map at the top of
branches. Otherwise, appendcurrent_toc_node to toc["entries"].
Exiting a list item indicates that processing of the current branch is complete.
Before adding this branch to its parent's entries array, the branch
needs to be tested to see if it has a name and/or any sub-branches. If it does
not have a name but has sub-branches, the branch is kept. The user agent can
either supply a placeholder value of its own creation or set the value to null.
If it does not have a name or any branches, it is invalid and is discarded.
To determine where to merge the branch, the stack is checked. If there are no
items in the stack, it is added into the entries property of the root
toc object (i.e., it is a top-level branch). Otherwise, it gets
added into the entries property of the object immediately preceding
it in the stack.
As a final step, current_toc_node is reset back to
null.
When entering an anchor element and current_toc_node is not null:
Run these steps:
If current_toc_node["name"] is not null, do nothing.
Otherwise:
Set current_toc_node["name"] to one of the following:
the descendant content of the anchor element (to preserve any
HTML tags);
the text string obtained from the descendant content (e.g., by
calculating the accessible name [accname-1.1] of the element).
If the element has an href attribute and the URL in the
attribute resolves to a resource in uniqueResources, set current_toc_node["url"] to the
value.
If the element has a type attribute, and the value of the
attribute is not an empty string after trimming leading and trailing
white space, set current_toc_node["type"] to the trimmed
value.
If the element has a rel attribute, and the value of the
attribute is not an empty string after trimming leading and trailing
white space, split the trimmed value on whitespace and set
current_toc_node["rel"] to the resulting list of tokens.
Skip further processing of the element and continue to the next.
Explanation
This step processes anchor tags to obtain values for the name and
url properties of a branch.
If the name of the current branch is already defined, then processing of this
element is terminated (i.e., to avoid processing multiple links for a single
branch).
Whether a user agent sets the name of the entry to the descendant
content of the a element, or generates a text string from it,
depends on whether it will re-use any descendant tagging in the presentation
(e.g., to retain images, MathML, ruby and other content that does not translate
to text easily).
In addition to having an href attribute specified, it is necessary
that it resolve to a resource that belongs to the digital publication to meet
the requirements of this specification. If not, the branch is retained but the
entry will not be linkable.
Additional information about the target of the link — the type of resource and
its relation — is also retained.
Example
72: Visualization of a link to an SVG
image.
«[
"name" → "In the Beginning",
"url" → "http://example.com/page1.svg",
"type" → "image/svg",
"rel" → null,
"entries" → « »
]»
Skip further processing of the element and continue to the next.
Explanation
As sectioning and sectioning root elements can define their own outlines,
descending into them poses problems for generating the table of contents (i.e.,
they may contain content that is not directly related). As a result, they are
skipped over when encountered to prevent their child content from being
processed.
Otherwise: do nothing.
Explanation
For all other elements, this step allows their descendant elements to continue to
be processed.
After completing the DOM walk, if toc["entries"] contains a non-empty list, return toc. Otherwise,
return null.
Explanation
If the entries array in the root toc object does not contain any
branches (either because no list was found in the nav element or the list
did not contain any conforming list items), then the algorithm did not produce a usable
table of contents.
14-Sept-2020: Several minor fixes to correct variable names in the processing algorithm. See pull
requests 232, 233 and 234.
4-Sept-2020: Updated the reference to ISO 8601:2004 to the revised ISO 8601-1:2019. See issue 65 (Audiobooks tracker).
27-July-2020: Updated the reference schema URL to a W3C address. See issue
226.
30-Apr-2020: Noted the issue with the author and creator properties being synonyms in schema.org.
See issue
203.
16-Apr-2020: Changed the recommendation that a privacy policy and accessibility report be resources
of a publication to best practice to match with the examples where these are listed as links. Adding
as links should not generate warnings. See issue 207.
15-Apr-2020: Removed the bullet from the LocalizableString definition allowing an array of values,
as this creates an invalid nesting of arrays when paired with the value categories. See issue 205.
12-Feb-2020: The prose requirements for the resource that links to the manifest to be a publication
resource and to be automatically added to the reading order (when one is not present) were restored
to align with the algorithm steps. An additional check was also included in the algorithm to warn if
the linking resource is not a publication resource. See issue 198.
12-Feb-2020: The table of contents algorithm was fixed to capture branches without a title, not just
those without any text content. See issue
195.
07-Feb-2020: Clarified that rel values are case insensitive and must be compared as such. See issue 196.
04-Feb-2020: The note about registering the publication rel value has been removed as it is now
officially registered with IANA. See pull
request 194.
28-Jan-2020: Reverted to using only role=doc-toc to identify the table of contents due to problems
with using fragments identifiers. See issue
176.
28-Jan-2020: Clarified that visual hiding does not affect the selection of the table of contents.
See issue 176.
28-Jan-2020: Added an extension point for profiles to add processing requirements for the context.
See issue 186.
27-Jan-2020: The table of contents processing algorithm has been updated to fix several bugs and
editorial issues in the expected outcomes. See issue 177 and issue 179, as well as pull request 180 and pull request 182 for more details.
For a complete list of issues addressed, refer to the GitHub tracker.
E. IANA considerations
This section is non-normative.
E.1 Link relation type
registration
Relation Name:
publication
Description:
Links to a publication manifest. A manifest represents structured information
about a publication, such as informative metadata, a list of resources, and a default reading
order.
The following is a manifest for an example article profile. The article consists only of the document
the manifest is embedded in. The title and reading order are omitted from the manifest, as these
properties are automatically generated during processing from the
title and URL of the containing document, respectively.
The editors would like to thank the members of the Publishing Working Group for their contributions to
this specification:
Greg Albers (J. Paul Getty Trust)
Franco Alvarado (Macmillan Learning)
Boris Anthony (The Rebus Foundation)
Luc Audrain (Hachette Livre)
Baldur Bjarnason (The Rebus Foundation)
Laura Brady (W3C Invited Expert)
Steve Breault (Scenarex Inc.)
Don Brutzman (Web3D Consortium)
Kaylin Bugbee (Earth Science Data Systems Program)
Yu-Wei Chang (Taiwan Digital Publishing Forum)
Fred Chasen (W3C Invited Expert)
Timothy Cole (University of Illinois at Urbana-Champaign)
Simon Collinson (Rakuten, Inc.)
Rachel Comerford (Macmillan Learning)
Garth Conboy (Google, Inc., chair)
Juan Corona (Evident Point Software)
Christopher Cosner (Stanford University)
Dave Cramer (Hachette Livre)
Greg Davis (Pearson plc)
Romain Deltour (DAISY Consortium)
Marisa DeMeglio (DAISY Consortium)
Vagner Diniz (NIC.br - Brazilian Network Information Center)
Kenneth Dougherty (Pearson plc)
Brady Duga (Google, Inc.)
Ben Dugas (Rakuten, Inc.)
Roger Espinosa (University of Michigan)
Reinaldo Ferraz (NIC.br - Brazilian Network Information Center)
Teenya Franklin (Pearson plc)
Jun Gamo (Voyager Japan, Inc.)
Michael Goodman (Wiley)
Markku Hakkinen (Educational Testing Service)
Katie Haritos-Shea (Knowbility)
Geoff Jukes (Blackstone Audio, Inc.)
Deborah Kaplan (W3C Invited Expert)
Bill Kasdorf (Book Industry Study Group)
George Kerscher (DAISY Consortium)
Yuri Khramov (Evident Point Software)
Masakazu Kitahara (Voyager Japan, Inc.)
Toshiaki Koike (Voyager Japan, Inc.)
Charles LaPierre (Benetech)
Mustapha Lazrek (Microsoft Corporation)
Laurent Le Meur (EDRLab)
Vladimir Levantovsky (Monotype)
Mia Lipner (Pearson plc)
Phil Madans (Hachette Livre)
Christopher Maden (University of Illinois at Urbana-Champaign)
Dmitry Markushevich (Evident Point Software)
Keith McFarland (Blackstone Audio, Inc.)
Jonathan McGlone (University of Michigan)
Hugh McGuire (The Rebus Foundation)
Nellie McKesson (W3C Invited Expert)
Selma Morais (NIC.br - Brazilian Network Information Center)
Jasmine Mulliken (Stanford University)
Cristina Mussinelli (Fondazione LIA)
Christos Nikolakakos (Wiley)
Gregorio Pellegrino (Fondazione LIA)
Fernando Pinto da Silva (EDRLab)
Nicholas Polys (Web3D Consortium)
Chris Powell (University of Michigan)
Jeff Printy (Macmillan Learning)
Ryan Pugatch (Hachette Livre)
Joshua Pyle (Wiley)
Wendy Reid (Rakuten, Inc., chair)
Florian Rivoal (W3C Invited Expert)
Leonard Rosenthol (Adobe)
Robert Sanderson (J. Paul Getty Trust)
Jodi Schneider (University of Illinois at Urbana-Champaign)
Ben Schroeter (Pearson plc)
Tzviya Siegman (Wiley, chair)
Avneesh Singh (DAISY Consortium)
Adam Sisco (Earth Science Data Systems Program)
David Stroup (Pearson plc)
Mateus Teixeira (W. W. Norton & Company)
Jonathan Thurston (Pearson plc)
Yukio Tomikura (Kodansha, Publishers, Ltd.)
Ben Walters (Microsoft Corporation)
Daniel Weck (EDRLab, DAISY Consortium)
John Weise (University of Michigan)
Jason White (Educational Testing Service)
Richard Wright (EDRLab)
Jeff Xu (Rakuten, Inc.)
Evan Yamanishi (W. W. Norton & Company)
Maurice York (University of Michigan)
Junichi Yoshii (Kodansha, Publishers, Ltd.)
Benjamin Young (Wiley)
Mohamed ZERGAOUI (INNOVIMAX)
The Working Group would also like to thank the members of the Digital Publishing Interest Group for all the hard work they did paving the road for this
specification.