From c39521aad17244973714e9a5ed6c5f2a7cb126cc Mon Sep 17 00:00:00 2001
From: MattGarrish What is a Web Publication
A Web Publication is defined by a set of items known as its information - set (infoset). The infoset is both abstract and concrete. It is abstract in the sense that it represents a - set of information that a user agent has to compile about the Web Publication, but it also becomes - concrete when the user agent creates an internal representation of that information.
- -A manifest, on the other hand, is a serialization of an infoset created by the author of a Web Publication. The manifest is - expressed using the JSON-LD [[json-ld]] format — a variant of JSON [[ecma-404]] for - expressing linked data. The manifest can be created as a standalone resource or it can be embedded - within an HTML document.
- -Although the infoset is primarily compiled from a Web - Publication's manifest, some information is obtained outside the manifest. The table of - contents, for example, may be referenced from the manifest but is serialized in an HTML - document.
- -This specification describes the requirements for creating both the infoset and manifest. This - section, in particular, details how to create a manifest, and the next - lists the various properties common to infosets and manifests.
-Although a Web Publication manifest is authored as [[json-ld]], user agents process this - information into an internal data structure representing the infoset in order to utilize - the properties. The exact manner in which this processing occurs, and how the data is used - internally, is user agent-dependent.
+Although a Web Publication manifest is authored as [[json-ld]], user agents process this + information into an internal data structure in order to utilize the properties. The exact + manner in which this processing occurs, and how the data is used internally, is user + agent-dependent.
-To ensure interoperability when exposing the infoset items, this specification defines an - abstract representation of the data structures using the Web Interface Definition Language - (WebIDL) [[webidl-1]] which expresses the expected name, datatype, and possible restrictions for - each member of the manifest expressed in the infoset. (A WebIDL representation can be mapped - onto ECMAScript, C, or other programming languages.)
-To ensure interoperability when exposing the items, this specification defines an abstract + representation of the data structures using the Web Interface Definition Language (WebIDL) + [[webidl-1]] which expresses the expected name, datatype, and possible restrictions for each + member of the manifest. (A WebIDL representation can be mapped onto ECMAScript, C, or other + programming languages.)
+WebPublicationManifest
DictionaryWebPublicationManifest
Dictionary+dictionary WebPublicationManifest { };-The
+WebPublicationManifest
dictionary is the [[!webidl-1]] representation of the - collection of Web Publication manifest properties. WebIDL definitions are also included at the - beginning of each property that belongs to the dictionary — these represent the members of - theWebPublicationManifest
dictionary.The
-WebPublicationManifest
dictionary is the [[!webidl-1]] representation of the + collection of Web Publication manifest properties. WebIDL definitions are also included at + the beginning of each property that belongs to the dictionary — these represent the + members of theWebPublicationManifest
dictionary.Refer to for a complete listing of the -
+WebPublicationManifest
dictionary.Refer to for a complete listing of the +
+WebPublicationManifest
dictionary.
A Web Publication Manifest MUST start by setting the JSON-LD context [[!json-ld]]. The context +
A Web Publication Manifest MUST start by setting the JSON-LD context [[!json-ld]]. The context has the following two major components:
PublicationLink
Definition The Web Publication Manifest MUST include a Publication Type using the The Web Publication Manifest MUST include a Publication Type using the
type
term [[!json-ld]]. The
type MAY be mapped onto the CreativeWork
type [[!schema.org]].
Schema.org also includes a number of more specific types, all subtypes of +
Schema.org also includes a number of more specific types, all subtypes of
CreativeWork
, such as Article
, Book
, TechArticle
, or Course
. These MAY be used instead of (or
- in addition to) CreativeWork
.
CreativeWork
.
{ @@ -578,9 +585,9 @@Properties
href="#wp-properties">.Although authors only have to understand the serialization requirements for manifest - terms, they are encouraged to read through the infoset definitions for each property, as well. - The infoset definitions describe, in some cases, how items are compiled in the absence of - explicit information in the manifest.
+ terms, they are encouraged to read through the full definitions for each property. The + definitions describe, in some cases, how items are compiled in the absence of explicit + information in the manifest.
The base URL for relative URLs is determined as follows:
@@ -598,7 +605,7 @@xml:base
attribute [[html]]).
When opting to embed the manifest, it MUST be included in the primary entry page using the script
element [[!html]]. The type
attribute of this
- element MUST be set to application/ld+json
.
When opting to embed the manifest, it MUST be included in the primary entry page using the script
element [[!html]]. The type
attribute of this
+ element MUST be set to application/ld+json
.
Additionally, the script
element MUST include a unique identifier in an id
- attribute [[!html]]. This identifier ensures that the manifest can be
- referenced.
Additionally, the script
element MUST include a unique identifier in an
+ id
attribute [[!html]]. This identifier ensures that the manifest can be referenced.
+<script id="example_manifest" type="application/ld+json"> { … } </script>-
With the exception of the primary entry page, linking a resource to its Web Publication - manifest is OPTIONAL. Including a link is encouraged whenever possible, however, as it allows user - agents to immediately ascertain that a resource belongs to a Web Publication, regardless of how the - user reaches the resource.
+With the exception of the primary entry page, linking a resource to its Web Publication + manifest is OPTIONAL. Including a link is encouraged whenever possible, however, as it allows + user agents to immediately ascertain that a resource belongs to a Web Publication, regardless of + how the user reaches the resource.
-Links to a Web Publication manifest MUST take one or both of the following forms:
+Links to a Web Publication 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
".
Link: <https://example.com/webpub/manifest>; rel=publication-
A link
element [[!html]] with its rel
attribute set to the
- value "publication
".
<link href="https://example.com/webpub/manifest" rel="publication"/>-
An HTTP Link
header field [[!rfc5988]] with its rel
+ parameter set to the value "publication
".
Link: <https://example.com/webpub/manifest>; rel=publication+
A link
element [[!html]] with its rel
attribute set to the
+ value "publication
".
<link href="https://example.com/webpub/manifest" rel="publication"/>+
When a manifest is embedded within an HTML document, the link MUST include a fragment identifier that
- references the script
element that contains the manifest (see ).
When a manifest is embedded within an HTML document, the link MUST include a fragment identifier
+ that references the script
element that contains the manifest (see ).
+<link href="#example_manifest" rel="publication"> … <script id="example_manifest" type="application/ld+json"> @@ -669,18 +675,20 @@-Linking to a Manifest
</script>The exact value of
+rel
is still to be agreed upon and - should be registered by IANA.The exact value of
-rel
is still to be agreed upon + and should be registered by IANA.The following details might be moved to the lifecycle section in a future draft.
+The following details might be moved to the lifecycle section in a future + draft.
-When a resource links to multiple manifests, a user agent MAY choose to present one or more - alternatives to the end user, or choose a single alternative on its own. The user agent MAY choose - to present any manifest based upon information that it possesses, even one that is not explicitly - listed as a parent (e.g., based upon information it calculates or acquires out of band). In the - absence of a preference by user agent implementers, selection of the first manifest listed is - suggested as a default.
+When a resource links to multiple manifests, a user agent MAY choose to present one or more + alternatives to the end user, or choose a single alternative on its own. The user agent MAY + choose to present any manifest based upon information that it possesses, even one that is not + explicitly listed as a parent (e.g., based upon information it calculates or acquires out of + band). In the absence of a preference by user agent implementers, selection of the first + manifest listed is suggested as a default.
+
The primary entry page is the only resource in which a manifest MAY be embedded. To ensure discovery of the manifest, the primary entry page MUST provide a link to the manifest, regardless of whether the manifest is embedded - within the page or external to it.
+ href="#manifest-linking">link to the manifest, regardless of whether the manifest is + embedded within the page or external to it.The address of the primary entry page is also the canonical identifier for the Web Publication (i.e., it serves as the unique identifier for the Web Publication).
@@ -753,23 +761,22 @@The table of contents provides a hierarchical list of links that reflects the structural outline of the major sections of the Web Publication.
- The table of contents is expressed via an HTML element (typically a nav
+
The table of contents is expressed via an HTML element (typically a nav
element [[!html]]) in one of the resources. 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 with
that role
value in document
- tree order [[!dom]].
If the table of contents is not located in the primary entry - page, the manifest SHOULD identify the resource - that contains the structure.
+ page, the manifest SHOULD identify the resource that + contains the structure.There are no requirements on the table of contents itself, except that, when specified, it MUST include a link to at least one resource.
Refer to the table of contents property definition for more - information on how to identify in the infoset and manifest which resource contains the table of - contents.
+ information on how to identify which resource contains the table of contents.Do we need a more detailed definition for the HTML TOC format?
@@ -778,27 +785,27 @@The page list is a list of links that provides navigation to static page demarcation points within +
The page list is a list of links that provides navigation to static page demarcation points within the content. These locations allow users, for example, to coordinate access into the content. The exact nature of these locations is left to content creators to define. They usually correspond to pages of a print document which is the source of the digital publication, but might be a purely - digital creation added for the sake of easing navigation.
+ digital creation added for the sake of easing navigation. - The page list is expressed via an HTML element (typically a nav
element [[!html]])
+
The page list is expressed via an HTML element (typically a nav
element [[!html]])
in one of the resources. This element MUST be identified by the
role
attribute [[!html]] value
"doc-pagelist
" [[!dpub-aria-1.0]], and MUST be the first element in the document
with that role
value document
- tree order [[!dom]].
If the page list is not located in the primary entry page, the - manifest SHOULD identify the resource that contains the structure.
+If the page list is not located in the primary entry page, the + manifest SHOULD identify the resource that contains the structure.
-There are no requirements on the page list itself, except that, when specified, it MUST include a - link to at least one resource.
+There are no requirements on the page list itself, except that, when specified, it MUST include a + link to at least one resource.
- Refer to the pagelist
property definition for more information
- on how to identify in the infoset and manifest which resource contains the page list.
Refer to the pagelist
property definition for more information
+ on how to identify which resource contains the page list.
Both the Web Publication infoset and manifest are defined by a common set of properties that describe - the basic information a user agent requires to process and render a Web Publication. These - properties are categorized as followed:
+The Web Publication manifest is defined by a set of properties that describe the basic information a + user agent requires to process and render a Web Publication. These properties are categorized as + followed:
The categorization of properties is done to simplify comprehension of their purpose; the groupings have no relevance outside this specification (i.e., the groupings do not exist in the - infoset or manifest).
+ manifest).Schema.org additionally includes a large number of properties that, though relevant for publishing, are not mentioned in this specification — Web Publication authors can use any - of these properties. This document defines only the minimal set of infoset items.
+ of these properties. This document defines only the minimal set of manifest items.There are discussion on whether a best practices document would be created, referring - to more schema.org terms. If so, it should be linked from here.
+ to more schema.org terms. If so, it should be linked from here.The requirements for the expression of Web Publication properties are defined by the infoset as follows:
+The requirements for the expression of Web Publication properties are defined as follows:
As the infoset properties do not all have to be serialized in the manifest, the requirements for the - manifest will differ in some cases. Refer to each property's definition to determine whether it is - required in the manifest or can be compiled from other information.
+These properties do not all have to be serialized in the manifest. Refer to each property's + definition to determine whether it is required in the manifest or can be compiled from other + information.
The way that properties are expressed in the manifest and infoset often differs from how they are - referred to using natural language. The following table provides a mapping between property names - and the sections where they are explained to help clarify the differing nomenclature:
+The way that properties are expressed in the manifest often differs from how they are referred to + using natural language. The following table provides a mapping between property names and the + sections where they are explained to help clarify the differing nomenclature:
Term | -Description | -Required Value | -[[!schema.org]] Mapping | -
---|---|---|---|
- accessMode
- |
- The human sensory perceptual system or cognitive faculty through which a person - may process or perceive information. | -One or more text(s). Expected values. | -
- accessMode (CreativeWork) |
-
- accessModeSufficient
- |
- A list of single or combined accessModes that are sufficient to understand all - the intellectual content of a resource. | -One or more ItemList. Expected values. | -
- accessModeSufficient (CreativeWork) |
-
- accessibilityAPI
- |
- Indicates that the resource is compatible with the referenced accessibility - APIs. | -One or more text(s).Expected values. | -
- accessibilityAPI
- (CreativeWork) |
-
- accessibilityControl
- |
- Identifies input methods that are sufficient to fully control the described - resource. | -One or more text(s). Expected values. | -
- accessibilityControl (CreativeWork) |
-
- accessibilityFeature
- |
- Content features of the resource, such as accessible media, alternatives and - supported enhancements for accessibility. | -One or more text(s). Expected values. | -
- accessibilityFeature (CreativeWork) |
-
- accessibilityHazard
- |
- A characteristic of the described resource that is physiologically dangerous to - some users. | -One or more text(s).Expected values. | -
- accessibilityHazard (CreativeWork) |
-
- accessibilitySummary
- |
- A human-readable summary of specific accessibility features or deficiencies, - consistent with the other accessibility metadata but expressing subtleties such - as “short descriptions are present but long descriptions will be needed for - non-visual users” or “short descriptions are present and no long descriptions - are needed.” | -Text. | -
- accessibilitySummary (CreativeWork) |
-
Note that the author MAY also provide a reference to a more detailed Accessibility Report, beyond the accessibility - information expressed by these properties.
+The following properties are categorized as accessibility properties:
+ +Term | +Description | +Required Value | +[[!schema.org]] Mapping | +
---|---|---|---|
+ accessMode
+ |
+ The human sensory perceptual system or cognitive faculty through which a person may + process or perceive information. | +One or more text(s). Expected values. | +
+ accessMode (CreativeWork) |
+
+ accessModeSufficient
+ |
+ A list of single or combined accessModes that are sufficient to understand all the + intellectual content of a resource. | +One or more ItemList. Expected values. | +
+ accessModeSufficient (CreativeWork) |
+
+ accessibilityAPI
+ |
+ Indicates that the resource is compatible with the referenced accessibility APIs. | +One or more text(s).Expected values. | +
+ accessibilityAPI (CreativeWork) |
+
+ accessibilityControl
+ |
+ Identifies input methods that are sufficient to fully control the described + resource. | +One or more text(s). Expected values. | +
+ accessibilityControl (CreativeWork) |
+
+ accessibilityFeature
+ |
+ Content features of the resource, such as accessible media, alternatives and + supported enhancements for accessibility. | +One or more text(s). Expected values. | +
+ accessibilityFeature (CreativeWork) |
+
+ accessibilityHazard
+ |
+ A characteristic of the described resource that is physiologically dangerous to + some users. | +One or more text(s).Expected values. | +
+ accessibilityHazard (CreativeWork) |
+
+ accessibilitySummary
+ |
+ A human-readable summary of specific accessibility features or deficiencies, + consistent with the other accessibility metadata but expressing subtleties such as + “short descriptions are present but long descriptions will be needed for non-visual + users” or “short descriptions are present and no long descriptions are needed.” | +Text. | +
+ accessibilitySummary (CreativeWork) |
+
Detailed descriptions of these properties are available on the WebSchemas Wiki site.
+ +Values SHOULD be drawn from the preferred + vocabulary for each accessibility property, but user agents MUST NOT omit values from + that are not included in the lists.
+ +The author can also provide a reference to a more detailed Accessibility Report, beyond the accessibility information + expressed by these properties.
-+partial dictionary WebPublicationManifest { sequence<DOMString> accessMode; sequence<DOMString> accessModeSufficient; @@ -1234,7 +1216,7 @@-Manifest Expression
LocalizableString accessibilitySummary; };+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "CreativeWork", @@ -1255,7 +1237,6 @@-Manifest Expression
}
url
property.
- If the address does not resolve to an HTML - document [[!html]], user agents SHOULD NOT provide access to it to users. A Web - Publication MAY have more than one address, but all the addresses MUST resolve to the same - document.
- -The referenced document SHOULD be a resource of the Web Publication. It can be any resource, - including one that is not listed in the default reading order. This document MUST - include a link to the manifest to ensure a bidirectional linking - relationship (i.e., that user agents can also locate the manifest from the document at the - address).
- -If the document is not a Web Publication resource, user agents SHOULD load the first document - in the default reading order when initiating the Web Publication.
- -To improve the usability of Web Publications, particularly in user agents that - do not support Web Publications, authors are encouraged to include navigation aids in the - referenced document that facilitate consumption of the content, (e.g., provide a table of - contents or a link to one).
- -Term | -Description | -Required Value | -[[!schema.org]] Mapping | -
---|---|---|---|
- url
- |
- URL of the primary entry page. | -A URL [[!url]]. | -
- url (Thing) |
-
Term | +Description | +Required Value | +[[!schema.org]] Mapping | +
---|---|---|---|
+ url
+ |
+ URL of the primary entry page. | +A URL [[!url]]. | +
+ url (Thing) |
+
If the address does not resolve to an HTML + document [[!html]], user agents SHOULD NOT provide access to it to users. A Web Publication + MAY have more than one address, but all the addresses MUST resolve to the same document.
+ +The referenced document SHOULD be a resource of the Web Publication. It can be any resource, + including one that is not listed in the default reading order. This document MUST include + a link to the manifest to ensure a bidirectional linking + relationship (i.e., that user agents can also locate the manifest from the document at the + address).
+ +If the document is not a Web Publication resource, user agents SHOULD load the first document in + the default reading order when initiating the Web Publication.
+ +To improve the usability of Web Publications, particularly in user agents that do + not support Web Publications, authors are encouraged to include navigation aids in the + referenced document that facilitate consumption of the content, (e.g., provide a table of + contents or a link to one).
+ ++partial dictionary WebPublicationManifest { required DOMString url; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -1332,7 +1305,6 @@-Manifest Expression
… }
id
property.
+ Term | +Description | +Required Value | +[[!schema.org]] Mapping | +
---|---|---|---|
+ id
+ |
+ Preferred version of the Web Publication. | +A URL [[!url]]. | +(None) | +
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.
@@ -1355,55 +1348,25 @@The canonical identifier MUST be a URL [[!url]].
- -If a URL is not provided in the manifest, or the value is an invalid URL, the Web 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 canonical identifier MUST be a URL [[!url]].
-Is a canonical identifier necessary to call out explicitly in - the infoset, or can it be handled by other - metadata.
-If a URL is not provided in the manifest, or the value is an invalid URL, the Web 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.
-Term | -Description | -Required Value | -[[!schema.org]] Mapping | -
---|---|---|---|
- id
- |
- Preferred version of the Web Publication. | -A URL [[!url]]. | -(None) | -
Is a canonical identifier necessary to call out explicitly, or can + it be handled by other metadata.
-The specification of the canonical identifier MAY be complemented by the inclusion of
- additional types of identifiers for the Web Publication using the identifier
- property [[!schema.org]] and/or its subtypes.
The specification of the canonical identifier MAY be complemented by the inclusion of additional
+ types of identifiers for the Web Publication using the identifier
property [[!schema.org]] and/or its subtypes.
+partial dictionary WebPublicationManifest { DOMString id; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "TechArticle", @@ -1414,7 +1377,7 @@-Manifest Expression
}+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -1425,13 +1388,12 @@-Manifest Expression
}
A creator is an individual or entity responsible for the creation of the Web
+ A creator is an individual or entity responsible for the creation of the Web
Publication. Creators are represented in one of the following two ways: The following properties are categorized as creators: When compiling each set of creator information from a
- [[!schema.org]] Note that user agents MAY interpret a wider range of creator properties defined by schema.org
- than the ones in the preceding list. The infoset MAY include more than one of each type of creator. When compiling each set of creator information from a
+ [[!schema.org]] Note that user agents MAY interpret a wider range of creator properties defined by schema.org
+ than the ones in the preceding list. The manifest MAY include more than one of each type of creator.
@@ -1447,215 +1409,188 @@
Creators
-
-
- artist
author
contributor
creator
editor
illustrator
inker
letterer
penciler
publisher
readBy
translator
Infoset Requirements
-
- Person
or Organization
type, user agents
- MUST retain the following information when available:
-
-
- Manifest Expression
-
-
-
-
+
-
-
-
- Term
- Description
- Required Value
- [[!schema.org]] Mapping
-
-
-
-
- artist
- The primary artist for the publication, in a medium other than pencils or
- digital line art.
- One or more
- Person
.
-
- artist
(VisualArtwork)
-
-
-
- author
- The author of the publication.
- One or more
- Person
and/or
- Organization
.
-
- author
(CreativeWork)
-
-
-
- colorist
- The individual who adds color to inked drawings.
- One or more
- Person
.
-
- colorist
(VisualArtwork)
-
-
-
- contributor
- Contributor whose role does not fit to one of the other roles in this
- table.
- One or more
- Person
and/or
- Organization
.
-
- contributor
(CreativeWork)
-
-
-
- creator
- The creator of the publication.
- One or more
- Person
and/or
- Organization
.
-
- creator
(CreativeWork)
-
-
-
- editor
- The editor of the publication.
- One or more
- Person
.
-
- editor
(CreativeWork)
-
-
-
- illustrator
- The illustrator of the publication.
- One or more
- Person
.
-
- illustrator
(Book)
-
-
-
- inker
- The individual who traces over the pencil drawings in ink.
- One or more
- Person
.
-
- inker
(VisualArtwork)
-
-
-
- letterer
- The individual who adds lettering, including speech balloons and sound effects,
- to artwork.
- One or more
- Person
.
-
- letterer
(VisualArtwork)
-
-
-
- penciler
- The individual who draws the primary narrative artwork.
- One or more
- Person
.
-
- penciler
(VisualArtwork)
-
-
-
- publisher
- The publisher of the publication.
- One or more
- Person
and/or
- Organization
.
-
- publisher
(CreativeWork)
-
-
-
- readBy
- A person who reads (performs) the publication (for audiobooks).
- One or more
- Person
.
-
- readBy
(Audiobook)
-
-
-
-
- translator
- The translator of the publication.
- One or more
- Person
and/or
- Organization
.
-
- translator
(CreativeWork)
+
+
+
+
+
+
+
+ Term
+ Description
+ Required Value
+ [[!schema.org]] Mapping
+
+
+
+
+ artist
+ The primary artist for the publication, in a medium other than pencils or digital
+ line art.
+ One or more
+ Person
.
+
+ artist
(VisualArtwork)
+
+
+
+ author
+ The author of the publication.
+ One or more
+ Person
and/or Organization
.
+
+ author
(CreativeWork)
+
+
+
+ colorist
+ The individual who adds color to inked drawings.
+ One or more
+ Person
.
+
+ colorist
(VisualArtwork)
+
+
+
+ contributor
+ Contributor whose role does not fit to one of the other roles in this table.
+ One or more
+ Person
and/or Organization
.
+
+ contributor
(CreativeWork)
+
+
+
+ creator
+ The creator of the publication.
+ One or more
+ Person
and/or Organization
.
+
+ creator
(CreativeWork)
+
+
+
+ editor
+ The editor of the publication.
+ One or more
+ Person
.
+
+ editor
(CreativeWork)
+
+
+
+ illustrator
+ The illustrator of the publication.
+ One or more
+ Person
.
+
+ illustrator
(Book)
+
+
+
+ inker
+ The individual who traces over the pencil drawings in ink.
+ One or more
+ Person
.
+
+ inker
(VisualArtwork)
+
+
+
+ letterer
+ The individual who adds lettering, including speech balloons and sound effects, to
+ artwork.
+ One or more
+ Person
.
+
+ letterer
(VisualArtwork)
+
+
+
+ penciler
+ The individual who draws the primary narrative artwork.
+ One or more
+ Person
.
+
+ penciler
(VisualArtwork)
+
+
+
+ publisher
+ The publisher of the publication.
+ One or more
+ Person
and/or Organization
.
+
+ publisher
(CreativeWork)
+
+
+
+ readBy
+ A person who reads (performs) the publication (for audiobooks).
+ One or more
+ Person
.
+
+ readBy
(Audiobook)
+
+
+
+
+ translator
+ The translator of the publication.
+ One or more
+ Person
and/or Organization
.
+
+ translator
(CreativeWork) Person
or Organization
type, user agents MUST
+ retain the following information when available:
+
+
+
+
partial dictionary WebPublicationManifest {
sequence<CreatorInfo> artist;
sequence<CreatorInfo> author;
@@ -1680,7 +1615,7 @@
- Manifest Expression
DOMString url;
};
+
{
"@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type" : "Book",
@@ -1692,7 +1627,7 @@
- Manifest Expression
}
}
+
{
"@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type" : "TechArticle",
@@ -1725,7 +1660,6 @@
- Manifest Expression
…
}
The Web Publication has a natural language value (e.g., English, French, Chinese), as well as a natural base writing direction (the display direction, either left-to-right or - right-to-left). The infoset has entries to set these - values, which can influence, for example, the behavior of a user agent (e.g., it might place a - pop-up for a table of contents on the right hand side for publications whose natural base - direction is right-to-left).
- -Similarly, each natural language property value in the Web Publication's
- infoset (e.g., title, creators) is
+
+ Similarly, each natural language property value in the Web Publication's manifest (e.g.,
+ title, creators) is localizable [[string-meta]], meaning that the same information is available for
each. As a result, the infoset has entries to set: As a result, the manifest has entries to set: of both the Web Publication ( The infoset MAY contain global language and base
- direction declarations for the Web Publication. The natural language MUST be a tag that
- conforms to [[!bcp47]], while the base language
- direction MUST have one of the following values:
Language and Base Direction
inLanguage
and inDirection
) and the
- natural language properties values of the infoset.Infoset Requirements
-
-
-
+ natural language properties values of the manifest.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;auto
: indicates that the textual values are explicitly
- directionally set to the direction of the first character with a strong
- directionality.
When specified, these properties are also used as defaults for textual values in the infoset.
- -It is important to differentiate the language of the publication from - the language and the base direction of the individual resources that compose it. If such - resources are, for example, in HTML, the language and direction need to be set in those - resources, too. The language and base direction of the publication are not inherited.
- -The global language information MAY be overridden by individual values.
- -When using Web Publication manifests with bidirectional text, user agents SHOULD identify the - base direction of any given natural language value by scanning the text for the first strong - directional character. Once the base direction has been identified, user agents MUST - determine the appropriate rendering and display of natural language values according to the - Unicode Bidirectional Algorithm [[!bidi]]. This could require wrapping additional - control characters or markup around the string prior to display, in order to apply the base - direction. (See .)
- -This section, in particular the features related to text directions, must be - reviewed by I18N experts.
- -If the manifest is embedded in the primary entry page via a
- script
element, and the manifest does not set the global language and/or
- the base direction (see ), the
- lang
and the dir
attributes of the script
element
- are used as the global language and base direction, respectively (see the
- details on handling the lang
and dir
- attributes in [[!html]]).
It is to be discussed whether this last paragraph, i.e., inheriting values from
- script
, should be kept.
If a user agent requires the language and one is not available in the infoset (globally, or specifically for that property), or - the obtained value is invalid, the user agent MAY attempt to determine the language. This - specification does not mandate how such a language tag is created. The user agent might:
-The manifest MAY contain global language and base direction declarations for the Web Publication. + The natural language MUST be a tag that conforms to [[!bcp47]], while the base language direction MUST have one of the following + values:
-No default values are specified for the language or the default base - direction.
+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;auto
: indicates that the textual values are explicitly directionally
+ set to the direction of the first character with a strong directionality.When specified, these properties are also used as defaults for textual values in the + manifest.
+It is important to differentiate the language of the publication from the + language and the base direction of the individual resources that compose it. If such resources + are, for example, in HTML, the language and direction need to be set in those resources, too. + The language and base direction of the publication are not inherited.
-The global language information MAY be overridden by individual values.
-As this infoset item refers to several aspects of setting language and direction, these are - treated separately.
+When using Web Publication manifests with bidirectional text, user agents SHOULD identify the + base direction of any given natural language value by scanning the text for the first strong + directional character. Once the base direction has been identified, user agents MUST determine + the appropriate rendering and display of natural language values according to the Unicode + Bidirectional Algorithm [[!bidi]]. This could require wrapping additional control + characters or markup around the string prior to display, in order to apply the base direction. + (See .)
-This section, in particular the features related to text directions, must be + reviewed by I18N experts.
-Term | -Description | -Required Value | -[[!schema.org]] Mapping | -
---|---|---|---|
- inLanguage
- |
- Default language for the Web Publication as well as the - textual infoset values | -language code as defined in [[!bcp47]] | -
- inLanguage (Property) |
-
- inDirection
- |
- Default base direction for the Web Publication as well as the - textual infoset values | -ltr , rtl , or auto |
- (None) | -
If the manifest is embedded in the primary entry page via a
+ script
element, and the manifest does not set the global language and/or the
+ base direction (see ), the lang
+ and the dir
attributes of the script
element are used as the global
+ language and base direction, respectively (see the details on handling the lang
and dir
attributes in [[!html]]).
If authors intend to use a manifest, or a manifest template, both as
- embedded manifest and as a separate resource, they are strongly encouraged to set these
- properties explicitly to avoid interference of the containing script
- element in case of embedding.
It is to be discussed whether this last paragraph, i.e., inheriting values from
+ script
, should be kept.
-partial dictionary WebPublicationManifest { - DOMString inLanguage; - TextDirection inDirection; +If a user agent requires the language and one is not available in the manifest (globally, or + specifically for that property), or the obtained value is invalid, the user agent MAY attempt to + determine the language. This specification does not mandate how such a language tag is created. + The user agent might:
+ +
No default values are specified for the language or the default base direction.
+ + +Term | +Description | +Required Value | +[[!schema.org]] Mapping | +
---|---|---|---|
+ inLanguage
+ |
+ Default language for the Web Publication as well as the textual + manifest values | +language code as defined in [[!bcp47]] | +
+ inLanguage (Property) |
+
+ inDirection
+ |
+ Default base direction for the Web Publication as well as the + textual manifest values | +ltr , rtl , or auto |
+ (None) | +
If authors intend to use a manifest, or a manifest template, both as embedded
+ manifest and as a separate resource, they are strongly encouraged to set these properties
+ explicitly to avoid interference of the containing script
element in case of
+ embedding.
+partial dictionary WebPublicationManifest { + DOMString inLanguage; + TextDirection inDirection; }; enum TextDirection { @@ -1889,19 +1805,18 @@-Global Language and Direction
"auto" };
It is possible to set the language for any textual value in the manifest. This
- information MUST be set as a localizable string,
- i.e., using the value
and language
terms (instead of a simple
- string) [[!json-ld]]:
It is possible to set the language for any textual value in the manifest. This information
+ MUST be set as a localizable string, i.e., using the
+ value
and language
terms (instead of a simple
+ string) [[!json-ld]]:
+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -1915,17 +1830,16 @@-Item-specific Language
} }The value of the
+language
MUST - be set to a language code as defined in [[!bcp47]].The value of the
-language
MUST be + set to a language code as defined in [[!bcp47]].When used in a context of localizable texts, a simple string value is a shorthand for a - localizable string, with the
+value
set to the string value, and the language set to the - value of theinLanguage
- property, if applicable, and unset otherwise. In other words, the previous example is - equivalent to:When used in a context of localizable texts, a simple string value is a shorthand for a + localizable string, with the
-value
set to the string value, and the language set to the value + of theinLanguage
property, if + applicable, and unset otherwise. In other words, the previous example is equivalent to:+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -1934,21 +1848,20 @@- + -Item-specific Language
"author" : "Marcel Proust", }It is not possible to set the direction explicitly for a value.
+It is not possible to set the direction explicitly for a value.
-Setting the direction for a natural text value is currently not possible in - JSON-LD [[json-ld]]. In case the JSON-LD community, as well as the schema.org - community, introduces such a feature, future versions of this specification may extend - the ability of Web Publication Manifests to include this.
+Setting the direction for a natural text value is currently not possible in + JSON-LD [[json-ld]]. In case the JSON-LD community, as well as the schema.org + community, introduces such a feature, future versions of this specification may extend the + ability of Web Publication Manifests to include this.
-+dictionary LocalizableString { required DOMString value; DOMString language; };-
dateModified
property.
- Term | +Description | +Required Value | +[[!schema.org]] Mapping | +
---|---|---|---|
+ dateModified
+ |
+ Last modification date of the publication. | +A Date or DateTime
+ value [[!schema.org]], both expressed in ISO 8601 Date, or Date Time formats,
+ respectively [[iso8601]]. |
+
+ dateModified (CreativeWork) |
+
The last modification date does not necessarily reflect all changes to the Web Publication (e.g., + third-party content could change without the author being aware). User agents SHOULD check the + last modification date of individual resources to determine if they have changed and need + updating.
-The last modification date does not necessarily reflect all changes to the Web Publication - (e.g., third-party content could change without the author being aware). User agents SHOULD - check the last modification date of individual resources to determine if they have changed - and need updating.
-Term | -Description | -Required Value | -[[!schema.org]] Mapping | -
---|---|---|---|
- dateModified
- |
- Last modification date of the publication. | -A Date or DateTime
- value [[!schema.org]], both expressed in ISO 8601 Date, or Date Time
- formats, respectively [[iso8601]]. |
-
- dateModified (CreativeWork) |
-
+partial dictionary WebPublicationManifest { DOMString dateModified; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "TechArticle", @@ -2015,7 +1921,6 @@-Manifest Expression
}
datePublished
property.
- Term | +Description | +Required Value | +[[!schema.org]] Mapping | +
---|---|---|---|
+ datePublished
+ |
+ Creation date of the publication. | +A Date or DateTime , both expressed in
+ ISO 8601 Date, or Date Time formats, respectively [[!iso8601]]. |
+
+ datePublished (CreativeWork) |
+
The exact moment of publication is intentionally left open to interpretation: it could be when + the Web Publication is first made available online or could be a point in time before + publication when the Web Publication is considered final.
-The exact moment of publication is intentionally left open to interpretation: it could be - when the Web Publication is first made available online or could be a point in time before - publication when the Web Publication is considered final.
-Term | -Description | -Required Value | -[[!schema.org]] Mapping | -
---|---|---|---|
- datePublished
- |
- Creation date of the publication. | -A Date or DateTime , both expressed
- in ISO 8601 Date, or Date Time formats, respectively [[!iso8601]]. |
-
- datePublished (CreativeWork) |
-
+partial dictionary WebPublicationManifest { DOMString datePublished; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "TechArticle", @@ -2079,7 +1977,6 @@-Manifest Expression
… }
readingDirection
property.
- The value of this property may be:
- -ltr
: left-to-right;rtl
: right-to-left.The default value is ltr
.
This infoset item 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.
+Term | +Description | +Required Value | +[[!schema.org]] Mapping | +
---|---|---|---|
+ readingProgression
+ |
+ Reading direction from one resource to the other. | +ltr or rtl |
+ (None) | +
The value of this property MUST be either:
+ +ltr
: left-to-right;rtl
: right-to-left.The reading progression of a Web Publication is used to adapt such - publication level interactions as menu position, swap direction, defining tap zones to lead - the user to the next and previous pages, touch gestures, etc.
-The default value is ltr
.
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.
-Term | -Description | -Required Value | -[[!schema.org]] Mapping | -
---|---|---|---|
- readingProgression
- |
- Reading direction from one resource to the other. | -ltr or rtl |
- (None) | -
The reading progression of a Web Publication is used to adapt such + publication level interactions as menu position, swap direction, defining tap zones to lead the + user to the next and previous pages, touch gestures, etc.
-If the readingProgression
is not set, user agents MUST use the default value is
- ltr
.
If the readingProgression
is not set, user agents MUST use the default value is
+ ltr
.
+partial dictionary WebPublicationManifest { ProgressionDirection readingProgression = "ltr"; }; @@ -2147,7 +2036,7 @@-Manifest Expression
"rtl" };+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -2156,7 +2045,6 @@-Manifest Expression
"readingProgression" : "ltr" }
The title provides the human-readable name of the Web Publication. It is expressed using
the name
property.
The title is specified by the manifest expression, when
- present. If not included in the manifest, user agents MAY use the value of the title
element [[!html]] of the Web Publication’s primary
- entry page (if present) .
Relying on the title
element could be semantically problematic if
- the Web Publication consists of several HTML resources (e.g., one per chapter of a book),
- because the HTML definition defines this element as "metadata" for the enclosing HTML document,
- not for a collection of resources. Using this element is, on the other hand, preferred in
- the case of a publication consisting of a single HTML document (e.g., a scholarly journal
- article).
When specified in the infoset, the title MUST be - non-empty.
- -If a user agent requires a title and one is not available in the infoset, it MAY create one (e.g., provide a - language-specific placeholder title or use the URL of the manifest).
- -A user agent is not expected to produce a meaningful - title [[wcag20]] for a Web Publication when one is not specified.
-Term | +Description | +Required Value | +[[!schema.org]] Mapping | +
---|---|---|---|
+ name
+ |
+ Human-readable title of the Web Publication. | +One or more text items for the title. | +
+ name (Thing) |
+
The title is specified by the manifest expression, when present. If not
+ included in the manifest, user agents MAY use the value of the title
element [[!html]] of the Web Publication’s primary entry
+ page (if present) .
Relying on the title
element could be semantically problematic if the
+ Web Publication consists of several HTML resources (e.g., one per chapter of a book), because
+ the HTML
+ definition defines this element as "metadata" for the enclosing HTML document, not for a
+ collection of resources. Using this element is, on the other hand, preferred in the case of a
+ publication consisting of a single HTML document (e.g., a scholarly journal article).
When specified in the manifest, the title MUST be non-empty.
+ +If a user agent requires a title and one is not available in the manifest, it MAY create one + (e.g., provide a language-specific placeholder title or use the URL of the manifest).
+ +A user agent is not expected to produce a meaningful + title [[wcag20]] for a Web Publication when one is not specified.
-Term | -Description | -Required Value | -[[!schema.org]] Mapping | -
---|---|---|---|
- name
- |
- Human-readable title of the Web Publication. | -One or more text items for the title. | -
- name (Thing) |
-
+partial dictionary WebPublicationManifest { sequence<LocalizableString> name; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -2235,7 +2113,6 @@-Manifest Expression
"name" : "Moby Dick" }
Note that a particular resource's URL MUST NOT appear in more than one of these lists, and a URL MUST NOT be repeated within a list.
-The manifest itself MUST NOT include a reference to itself, i.e., the reference to the manifest MUST - NOT appear within these lists.
+The manifest itself MUST NOT include a reference to itself, i.e., the reference to the manifest MUST + NOT appear within these lists.
The default reading order is a specific progression through a set of Web
Publication resources. It is expressed using the readingOrder
property.
Term | +Description | +Required Value | +[[!schema.org]] Mapping | +
---|---|---|---|
+ readingOrder
+ |
+ + |
+ An array of: +
The order in the array is significant. The URLs MUST NOT include
+ fragment identifiers. Non-HTML resources SHOULD be expressed as
+ |
+ (None) | +
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 MUST include at least one resource.
-The default reading order MUST include at least one resource.
+The default reading order is specified directly in the manifest, but MAY be omitted when it only + consists of the primary entry page. When the default reading order is absent, user agents + MUST include an entry for the primary entry page when compiling the canonical manifest.
-The default reading order is specified directly in the manifest, but MAY be omitted when it - only consists of the primary entry page. When the default reading order is absent, - user agents MUST include an entry for the primary entry page when compiling the infoset.
-If present in the Web Publication Manifest, this item MUST be mapped on the
+ readingOrder
term, defined specifically for Web Publications.
If present in the Web Publication Manifest, this item MUST be mapped on the
- readingOrder
term, defined specifically for Web Publications.
Term | -Description | -Required Value | -[[!schema.org]] Mapping | -
---|---|---|---|
- readingOrder
- |
- - |
- An array of: -
The order in the array is significant. The URLs MUST NOT include
- fragment identifiers. Non-HTML resources SHOULD be expressed as
- |
- (None) | -
+partial dictionary WebPublicationManifest { required sequence<PublicationLink> readingOrder; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -2334,7 +2204,7 @@-Manifest Expression
] }+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -2356,7 +2226,6 @@-Manifest Expression
}] }
resources
property.
- The completeness of the resource list will affect the usability of the Web Publication in - certain reading scenarios (e.g., the ability to read the Web Publication offline). For this - reason, it is strongly RECOMMENDED to provide a comprehensive list of all of the Web - 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 Web Publication even if some of these resources are - not identified as belonging to the Web Publication (e.g., when it is taken offline without - them).
-Term | +Description | +Required Value | +[[!schema.org]] Mapping | +
---|---|---|---|
+ resources
+ |
+ + |
+ An array of: +
The order in the array is not significant. The URLs MUST NOT include
+ fragment identifiers. It is RECOMMENDED to use |
+ (None) | +
The completeness of the resource list will affect the usability of the Web Publication in certain + reading scenarios (e.g., the ability to read the Web Publication offline). For this reason, it + is strongly RECOMMENDED to provide a comprehensive list of all of the Web 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 Web Publication even if some of these resources are not + identified as belonging to the Web Publication (e.g., when it is taken offline without + them).
+ +If present in the Web Publication Manifest, this item MUST be mapped on the
+ resources
term, defined specifically for Web Publications.
If present in the Web Publication Manifest, this item MUST be mapped on the
- resources
term, defined specifically for Web Publications.
Term | -Description | -Required Value | -[[!schema.org]] Mapping | -
---|---|---|---|
- resources
- |
- - |
- An array of: -
The order in the array is not significant. The URLs MUST NOT include
- fragment identifiers. It is RECOMMENDED to use |
- (None) | -
+partial dictionary WebPublicationManifest { sequence<PublicationLink> resources = []; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "TechArticle", @@ -2453,7 +2314,6 @@-Manifest Expression
}
link
property.
+ Term | +Description | +Required Value | +[[!schema.org]] Mapping | +
---|---|---|---|
+ links
+ |
+ + |
+ An array of: +
The order in the array is not significant. It is RECOMMENDED to use
+ |
+ (None) | +
Linked resources are typically made available to user agents to augment or enhance the processing or rendering of it, such as:
@@ -2485,60 +2376,21 @@The links
list SHOULD include resources necessary to render a linked resource
- (e.g., scripts, images, style sheets).
Resources listed in the links
list MUST NOT be listed in the default reading order or resource list.
User agents MAY ignore linked resources, and are not required to take them offline with a Web - Publication. These resources SHOULD NOT be included when packaging a Web Publication.
-The links
list SHOULD include resources necessary to render a linked resource (e.g.,
+ scripts, images, style sheets).
Resources listed in the links
list MUST NOT be listed in the default reading order or resource
+ list.
Term | -Description | -Required Value | -[[!schema.org]] Mapping | -
---|---|---|---|
- links
- |
- - |
- An array of: -
The order in the array is not significant. It is RECOMMENDED to use
- |
- (None) | -
User agents MAY ignore linked resources, and are not required to take them offline with a Web + Publication. These resources SHOULD NOT be included when packaging a Web Publication.
-+partial dictionary WebPublicationManifest { sequence<PublicationLink> links = []; };-
An accessibility report is identified using the
https://www.w3.org/ns/wp#accessibility-report
link relationship.
The infoset SHOULD include a link to an - accessibility report when one is available for a Web Publication. It is RECOMMENDED that the - report be included as a resource of the Web Publication.
- -It is also RECOMMENDED that the accessibility report be provided in a human-readable format, - such as HTML [[html]]. Augmenting these - reports with machine-processable metadata, such as provided in Schema.org [[schema.org]], is - also RECOMMENDED.
-The manifest SHOULD include a link to an accessibility report when one is available for a Web + Publication. It is RECOMMENDED that the report be included as a resource of the Web + Publication.
-It is also RECOMMENDED that the accessibility report be provided in a human-readable format, such + as HTML [[html]]. Augmenting these reports + with machine-processable metadata, such as provided in Schema.org [[schema.org]], is also + RECOMMENDED.
-If present in the manifest, the accessibility report MUST be expressed as
- a PublicationLink
. The rel
- value of the PublicationLink
MUST include
- the https://www.w3.org/ns/wp#accessibility-report
identifier.
If present in the manifest, the accessibility report MUST be expressed as a
+ PublicationLink
. The rel
value
+ of the PublicationLink
MUST include the
+ https://www.w3.org/ns/wp#accessibility-report
identifier.
The Working Group will attempt to define the accessibility-report
- term with IANA, to avoid using a URL.
The Working Group will attempt to define the accessibility-report
+ term with IANA, to avoid using a URL.
+partial dictionary WebPublicationManifest { PublicationLink accessibilityReport; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -2604,7 +2449,6 @@-Manifest Expression
… }
A privacy policy is identified using the privacy-policy
link relationship.
A link to a privacy policy can be included in the manifest. It is RECOMMENDED that the privacy + policy be included as a resource of the Web Publication.
-A link to a privacy policy can be included in the infoset. It is RECOMMENDED that the privacy policy be included as a - resource of the Web Publication.
+It is RECOMMENDED that the privacy policy be provided in a human-readable format, such as HTML [[html]].
-It is RECOMMENDED that the privacy policy be provided in a human-readable format, such as - HTML [[html]].
+Refer to for more information about privacy considerations in Web + Publications.
-Refer to for more information about privacy considerations in Web - Publications.
-If present in the manifest, the privacy policy MUST be expressed as a PublicationLink
. The rel
value of
+ the PublicationLink
MUST include the
+ privacy-policy
identifier [[!iana-link-relations]].
If present in the manifest, the privacy policy MUST be expressed as a PublicationLink
. The rel
- value of the PublicationLink
MUST include
- the privacy-policy
identifier [[!iana-link-relations]].
+partial dictionary WebPublicationManifest { PublicationLink privacyPolicy; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "TechArticle", @@ -2665,7 +2501,6 @@-Manifest Expression
… }
The working group has not reached consensus on whether the cover should be any resource or should be limited to images.
-The infoset SHOULD include a reference to a - cover.
- -More than one cover MAY be referenced from the infoset (e.g., to provide alternative formats - and sizes for different device screens). If multiple covers are specified, each instance - MUST define at least one unique property to allow user agents to determine its usability - (e.g., a different format, height, width or relationship).
-The manfiest SHOULD include a reference to a cover.
-More than one cover MAY be referenced from the manifest (e.g., to provide alternative formats and + sizes for different device screens). If multiple covers are specified, each instance MUST define + at least one unique property to allow user agents to determine its usability (e.g., a different + format, height, width or relationship).
-If present in the manifest, the cover MUST be expressed as a PublicationLink
. The URL expressed in the
- url
term MUST NOT include a fragment identifier.
If present in the manifest, the cover MUST be expressed as a PublicationLink
. The URL expressed in the url
term MUST
+ NOT include a fragment identifier.
The rel
value of the PublicationLink
MUST include the
- https://www.w3.org/ns/wp#cover
identifier.
The rel
value of the PublicationLink
MUST include the
+ https://www.w3.org/ns/wp#cover
identifier.
If the cover is in an image format, a title
and description
SHOULD
- be provided. User agents can use these properties to provide alternative text and
- descriptions when necessary for accessibility.
If the cover is in an image format, a title
and description
SHOULD be
+ provided. User agents can use these properties to provide alternative text and descriptions when
+ necessary for accessibility.
The Working Group will attempt to define the cover
term by IANA,
- to avoid using a URL.
The Working Group will attempt to define the cover
term by IANA, to
+ avoid using a URL.
+partial dictionary WebPublicationManifest { sequence<PublicationLink> cover; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -2737,7 +2564,7 @@-Manifest Expression
}+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -2758,7 +2585,7 @@-Manifest Expression
}+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -2781,7 +2608,6 @@-Manifest Expression
… }
The pagelist property identifies the resource that contains the Web Publication's page list. It is identified by the
- https://www.w3.org/ns/wp#pagelist
link relationship.
https://www.w3.org/ns/wp#pagelist
link relationship.
- User agents MUST compute the pagelist
as follows:
User agents MUST compute the pagelist
as follows:
rel
value including
- https://www.w3.org/ns/wp#pagelist
, the corresponding
- url
value identifies the page list resource. If there are
- several such resources, the first one MUST be used, with the default reading order taking precedence
- over resource-list. role
[[!html]] value
- doc-pagelist
[[!dpub-aria-1.0]], the user agent MUST use that element
- as the page list. If there are several such HTML elements the user agent MUST use the
- first in document tree
- order [[!dom]]. If this process does not result in a link to the page list, the Web Publication does not have - a page list and this property MUST NOT be included in the infoset.
+rel
value including https://www.w3.org/ns/wp#pagelist
,
+ the corresponding url
value identifies the page list resource. If there
+ are several such resources, the first one MUST be used, with the default reading order taking precedence over
+ resource-list. role
[[!html]] value doc-pagelist
[[!dpub-aria-1.0]],
+ the user agent MUST use that element as the page list. If there are several such HTML
+ elements the user agent MUST use the first in document tree
+ order [[!dom]]. The Working Group will attempt to define the pagelist
term by
- IANA, to avoid using a URL.
If this process does not result in a link to the page list, the Web Publication does not have a + page list and this property MUST NOT be included in the canonical manifest.
- The Working Group will attempt to define the pagelist
term by IANA,
+ to avoid using a URL.
If present in the manifest, the page list MUST be expressed as a PublicationLink
. The URL expressed in the
- url
term MUST NOT include a fragment identifier.
If present in the manifest, the page list MUST be expressed as a PublicationLink
. The URL expressed in the
+ url
term MUST NOT include a fragment identifier.
The rel
value of the PublicationLink
MUST include the
- https://www.w3.org/ns/wp#pagelist
identifier.
The rel
value of the PublicationLink
MUST include the
+ https://www.w3.org/ns/wp#pagelist
identifier.
The link to the page list MAY be specified in either the default reading order or resource-list, but MUST NOT - be specified in both.
+The link to the page list MAY be specified in either the default + reading order or resource-list, but MUST NOT be specified + in both.
-+partial dictionary WebPublicationManifest { HTMLElement pagelist; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -2863,7 +2681,6 @@-Manifest Expression
… }
contents
link relationship.
- User agents MUST compute the toc
as follows:
rel
value including
- contents
[[!iana-link-relations]], the corresponding
- url
value identifies the table of contents resource. If there
- are several such resources, the first one MUST be used, with the default reading order taking precedence
- over resource-list. role
[[!html]] value doc-toc
[[!dpub-aria-1.0]], the
- user agent MUST use that element as the table of contents. If there are several such
- HTML elements the user agent MUST use the first in document tree
- order [[!dom]]. User agents MUST compute the toc
as follows:
If this process does not result in a link to the table of contents, the Web Publication does - not have a table of contents and this property MUST NOT be included in the infoset.
+rel
value including
+ contents
[[!iana-link-relations]], the corresponding
+ url
value identifies the table of contents resource. If there are
+ several such resources, the first one MUST be used, with the default reading order taking precedence over
+ resource-list. role
[[!html]] value doc-toc
[[!dpub-aria-1.0]], the
+ user agent MUST use that element as the table of contents. If there are several such HTML
+ elements the user agent MUST use the first in document tree
+ order [[!dom]]. Depending on the resolution to this issue, the infoset might - contain a separate entry for a machine-processable table of contents, restrictions could be - placed on the HTML structure of the referenced table of contents, or parsing rules for - extracting a table of contents could be added.
-If this process does not result in a link to the table of contents, the Web Publication does not + have a table of contents and this property MUST NOT be included in the canonical manifest.
-Depending on the resolution to this issue, the manifest might + contain a separate entry for a machine-processable table of contents, restrictions could be + placed on the HTML structure of the referenced table of contents, or parsing rules for + extracting a table of contents could be added.
-If present in the manifest, the table of contents MUST be expressed as a PublicationLink
. The URL expressed in the
- url
term MUST NOT include a fragment identifier.
If present in the manifest, the table of contents MUST be expressed as a PublicationLink
. The URL expressed in the url
term MUST
+ NOT include a fragment identifier.
The rel
value of the PublicationLink
MUST include the contents
- identifier [[!iana-link-relations]].
The rel
value of the PublicationLink
MUST include the contents
+ identifier [[!iana-link-relations]].
The link to the table of contents MAY be specified in either the default reading order or resource-list, but MUST NOT be specified in both.
+The link to the table of contents MAY be specified in either the default reading order or resource-list, but MUST NOT be + specified in both.
-+partial dictionary WebPublicationManifest { HTMLElement toc; };-+{ "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"], "type" : "Book", @@ -2948,7 +2757,7 @@-Manifest Expression
}+<head> … <script type="application/ld+json"> @@ -2971,16 +2780,14 @@-Manifest Expression
… </body>
The infoset is designed to provide a basic set of - properties for use by user agents in presenting and rendering a Web Publication, but MAY be - extended in the following ways:
+The manifest is designed to provide a basic set of properties for use by user agents in presenting + and rendering a Web Publication, but MAY be extended in the following ways:
Although both methods are valid, the use of linked records to extend the infoset is RECOMMENDED.
+Although both methods are valid, the use of linked records is RECOMMENDED.
This specification does not define how such additional properties are compiled, stored or exposed by - user agents in their internal representation of the infoset. A user agent MAY ignore some or all + user agents in their internal representation of the manifest. A user agent MAY ignore some or all extended properties.
Linked records MUST be included in the resource list when they are - part of the Web Publication (i.e., are needed for more than just infoset extensibility). + part of the Web Publication (i.e., are needed for more than just manifest extensibility). Otherwise, they MUST be included in the links list.
@@ -3033,7 +2840,7 @@Linked records
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.
See the diagrams in the appendix for a visual - representation of the lifecycle algorithm.
+ representation of the lifecycle algorithm.The steps for - obtaining a manifest, starting from the primary entry page, are given by the - following algorithm. The algorithm, if successful, returns a processed manifest; otherwise, - it terminates prematurely and returns nothing. In the case of nothing being returned, the user agent - MUST ignore the manifest declaration.
+The steps for obtaining + a manifest, starting from the primary entry page, are given by the following + algorithm. The algorithm, if successful, returns a processed manifest; otherwise, it + terminates prematurely and returns nothing. In the case of nothing being returned, the user agent + MUST ignore the manifest declaration.
Document
of the top-level browsing context of the primary entry
@@ -3169,24 +2976,14 @@ The algorithm does not describes how error and warning messages should be reported. - This is implementation dependent.
+ This is implementation dependent.A Canonical Web Publication - Manifest (or Canonical Manifest) is a version of the Web Publication Manifest where - all possible ambiguities on property values (see, e.g., or - ) have been removed, and all values that are possibly - harnessed from the primary entry page are incorporated. Using a Canonical Manifest when processing the manifest makes those processing steps, as well as - the transformation of the manifest to programming language structures, clearer. Converting the - Manifest into its canonical form is done when the manifest is obtained.
- -The steps to convert a Web Publication Manifest into a Canonical Manifest are given by the following +
The steps to convert a Web Publication Manifest into a Canonical Manifest are given by the following algorithm. The algorithm takes the following arguments:
The steps of the algorithm are described below. As an abuse of notation, P["term"] refers +
The steps of the algorithm are described below. As an abuse of notation, P["term"] refers
to the value in the object P for the label "term", where P is
either manifest, or an object appearing within manifest (e.g., a
Person). The algorithm replaces or adds some terms to manifest; the
- replacement terms are expressed in JSON syntax as {"term":"value"}
.
{"term":"value"}
.
See the diagram in the appendix for a visual representation of the algorithm. Also, to help understanding the result of the algorithm, there is a link to the corresponding canonical manifests for all the examples in .
+ href="#app-manifest-examples">. The steps for processing a
+ The steps for processing a
manifest are given by the following algorithm. The algorithm takes a json
object representing a canonical manifest. The output from inputting a JSON object into this
algorithm is a processed manifest. The goal of the algorithm is to ensure that the data
represented in json abides to the minimal requirements on the data, removing, if
- applicable, non-conformant data.
This feature has the following requirements:
Publication mode is a display mode implemented by the user agent that follows the @@ -3597,21 +3392,21 @@
The user agent should provide access to the table of contents without leaving current - resource from anywhere in the publication.
-For accessibility reasons, it is RECOMMENDED for User Agents to use a table of contents to - allow multiple ways for users to access content.
+The user agent should provide access to the table of contents without leaving current + resource from anywhere in the publication.
+For accessibility reasons, it is RECOMMENDED for User Agents to use a table of contents to + allow multiple ways for users to access content.
The table of contents is a listed as a structural property in the infoset, see The table of contents is a listed as a structural property in the manifest, see
-The table of content is referred to in the Web Publication Manifest (see ) and is expressed using an HTML element; see for further details.
-User agents MAY use the default reading order in the case a Table of Contents is not - explicitly specified to create a table of contents.
+The table of content is referred to in the Web Publication Manifest (see ) and is expressed using an HTML element; see for further details.
+User agents MAY use the default reading order in the case a Table of Contents is not + explicitly specified to create a table of contents.
The user must be able to leave the Web Publication and return to it at the last position they +
The user must be able to leave the Web Publication and return to it at the last position they left from. The User Agent must retain the reading position, based on the last known position of the reader in the web publication. The position should be based on the reader's position in the - file, within the reading order.
-The user agent may retain reading state if the web publication is revised.
+ file, within the reading order. +The user agent may retain reading state if the web publication is revised.
The navigation of the web publication should be defined in the Default Reading Order - required by the Information Set.
-User Agents should not have to set the reading state in the following type of resources:
+The navigation of the web publication should be defined in the required Default Reading + Order.
+User Agents should not have to set the reading state in the following type of resources:
Reading state should only apply to content documents listed as being within the bounds of the - Web Publication.
+Reading state should only apply to content documents listed as being within the bounds of the Web + Publication.
Example 1:
Sarah is reading a long article on her way to work. She arrives before she has
+
Example 1:
Sarah is reading a long article on her way to work. She arrives before she has
finished, but wants to continue from the place she left off. The user agent should remember her
- reading state for the next time she opens the publication.
If a tester opens a web publication in a WP-aware UA, moves ahead in the publication, closes the - reader, then reopens it, they should be returned to the last known reading state.
+If a tester opens a web publication in a WP-aware UA, moves ahead in the publication, closes the + reader, then reopens it, they should be returned to the last known reading state.
The document referred from this section, i.e., Web Annotation Extensions for Web Publications [[wpub-ann]], has been recently renamed. Its previous was "Locators for Web - Publication". The terminology used in this section has to be realigned with the name change.
+ Publication". The terminology used in this section has to be realigned with the name change.Locators are used to identify, locate, retrieve, and/or reference locations and content fragments within Web Publications (e.g., for address(es), bookmarks, and annotations). Locators traditionally @@ -3729,15 +3524,14 @@
In composing a Web Publication Locator, use the canonical identifier of the Web Publication in preference to any alternative addresses. Such use facilitates the collation of Web Publication Locators associated with a particular Web Publication. URLs of Web Publication resources appearing in a Web Publication Locator should match - the URL of the resource provided in the infoset.
+ the URL of the resource provided in the manifest.The manifest is expressed in one of two forms depending on the state of the Web Publication:
The Authored Web Publication Manifest, as its name suggests, is the serialization of the manifest that the author provides with their Web Publication.
@@ -246,17 +246,19 @@THe Canonical Web Publication Manifest is a version of the Web Publication - Manifest created by user agents when they The Canonical Web Publication Manifest is a version of an Authored Web Publication + Manifest typically created by user agents when they obtain the authored manifest and remove all possible ambiguities and incorporate any missing values that can be inferred from another source.
+This specification describes the requirements for creating both authored and canonical manifests. This section, in particular, details how to create the authored manifest, while provides the various property definitions. These definitions - include the rules user agents uses to supplement the canonical manifest.
+ include the rules user agents uses to supplement the canonical manifest. The algorithm for transforming an Authored Manifest into a Canonical Manifest is described in the separate section . +For embedded manifests, this means that relative URLs are resolved against the URL of the primary
entry page unless the page declares a base direction (i.e., in a <base>
element in its header or via an xml:base
attribute [[html]]).
<base>
element in its header).
+
+ The usage (or not) of the <base>
element for embedded manifests is currently the subject of several issues in the JSON-LD Working Group Working Group: JSON-LD
+ #22, JSON-LD #57, and,
+ ultimately, TAG #312.
This specification defines a collection of information that describes the structure of Web Publications - so that user agents can provide user experiences tailored to reading publications, such as sequential - navigation and offline reading. This information includes the default reading order, a list of - resources, and publication-wide metadata.
+ so that user agents can provide user experiences specially tailored to reading publications, such as + sequential navigation and offline reading. This information includes the default reading order, a list + of resources, and publication-wide metadata.This draft provides a draft version of a Web Publication. Many details are under active consideration @@ -74,6 +74,11 @@ href="#wp-properties">, which include the definition of a manifest making use of terms in schema.org, as well as the Lifecycle and WebIDL sections.
+ +Significant to this draft is the removal of the Information Set (infoset) — the final data + model produced from the processing of manifest properties. This draft instead relies on the canonical manifest to express this model, as it already encompasses + the final JSON-compliant data set that user agents are expected to produce.
The Canonical Web Publication Manifest is a version of an Authored Web Publication - Manifest typically created by user agents when they The Canonical Web Publication Manifest is a version of the Web Publication + Manifest created by user agents when they obtain the authored manifest and remove all possible ambiguities and incorporate any missing values that can be inferred from another source.
-This specification describes the requirements for creating both authored and canonical manifests. This section, in particular, details how to create the authored manifest, while provides the various property definitions. These definitions - include the rules user agents uses to supplement the canonical manifest. The algorithm for transforming an Authored Manifest into a Canonical Manifest is described in the separate section .
+ include the rules user agents uses to supplement the canonical manifest. The algorithm for + transforming an Authored Manifest into a Canonical Manifest is described in the + separate section .Although a Web Publication manifest is authored as [[json-ld]], user agents process this +
Although a Web Publication manifest is authored as [[json-ld]], a user agent processes this information into an internal data structure in order to utilize the properties. The exact manner in which this processing occurs, and how the data is used internally, is user agent-dependent.
To ensure interoperability when exposing the items, this specification defines an abstract representation of the data structures using the Web Interface Definition Language (WebIDL) - [[webidl-1]] which expresses the expected name, datatype, and possible restrictions for each - member of the manifest. (A WebIDL representation can be mapped onto ECMAScript, C, or other - programming languages.)
+ [[webidl-1]]. The WebIDL definitions express the expected names, datatypes, and possible + restrictions for each member of the manifest. (A WebIDL representation can be mapped onto + ECMAScript, C, or other programming languages.) + +Authors of Web Publications are encouraged to review these definitions, but they + are not necessary to understand.
WebPublicationManifest
DictionaryThe WebPublicationManifest
dictionary is the [[!webidl-1]] representation of the
- collection of Web Publication manifest properties. WebIDL definitions are also included at
- the beginning of each property that belongs to the dictionary — these represent the
- members of the WebPublicationManifest
dictionary.
WebPublicationManifest
dictionary.
Refer to for a complete listing of the
WebPublicationManifest
dictionary.
The Web Publication context file MAY add features to the properties defined in Schema.org (e.g., +
The Web Publication context document adds features to the properties defined in Schema.org (e.g., the requirement for the creator property to be order preserving).
-As part of the continuous contacts with Schema.org the additional features defined in the Web Publication context file could migrate to the core Schema.org vocabulary.
@@ -327,7 +335,6 @@https
scheme as its default. This specification requires the use
https
when referencing Schema.org in the manifest.
-
Various manifest properties can have one or more values. As a general rule, these values can - be expressed as [[!json]] arrays. When the property value is an array with a single - element, however, the array syntax can be omitted.
+ be expressed as [[!json]] arrays. When the property value is an array with a single + element, however, the array syntax MAY be omitted.When opting to embed the manifest, it MUST be included in the primary entry page using the A manifest MAY be embedded only in the primary entry page.
+ In this case, the manifest MUST be included in a script
element [[!html]]. The type
attribute of this
- element MUST be set to application/ld+json
.
script
element [[!html]] whose type
attribute is set
+ to application/ld+json
.
Additionally, the With the exception of the primary entry page, linking a resource to its Web Publication
manifest is OPTIONAL. Including a link is encouraged whenever possible, however, as it allows
- user agents to immediately ascertain that a resource belongs to a Web Publication, regardless of
+ user agents to immediately ascertain that a resource belongs to a Web Publication regardless of
how the user reaches the resource. Links to a Web Publication manifest MUST take one or both of the following forms: A Web Publication MUST include at least one HTML document [[!html]]—the primary entry page. A Web Publication MUST include at least one HTML document [[!html]]—the primary
+ entry page. There are no restrictions on a Web Publication beyond this requirement. The Web Publication MAY
include references to resources of any media type, both in the default reading order and as
@@ -747,7 +756,7 @@ script
element MUST include a unique identifier in an
id
attribute [[!html]]. This identifier ensures that the manifest Linking To
Web Publication Bounds
Resources
- Primary Entry Page
the Web Publication instead of a specific page of content). If a default reading order is not
provided, however, the primary entry page will be used as the default entry.
The primary entry page is the only resource in which a manifest MAY be
+ The primary entry page is the only resource in which a manifest can be
embedded. To ensure discovery of the manifest, the primary entry page MUST provide a link to the manifest, regardless of whether the manifest is
embedded within the page or external to it. The table of contents provides a hierarchical list of links that reflects the structural outline of
the major sections of the Web Publication. The table of contents is expressed via an HTML element (typically a The table of contents is expressed via an [[!html]] element (typically a If the table of contents is not located in the primary entry
page, the manifest SHOULD identify the resource that
@@ -791,17 +801,18 @@ The page list is a list of links that provides navigation to static page demarcation points within
- the content. These locations allow users, for example, to coordinate access into the content. The
+ the content. These locations allow users to coordinate access into the content, for example. The
exact nature of these locations is left to content creators to define. They usually correspond to
pages of a print document which is the source of the digital publication, but might be a purely
- digital creation added for the sake of easing navigation.Table of Contents
nav
- element [[!html]]) in one of the resources. 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 with
- that role
value in document
- tree order [[!dom]].nav
element) in
+ one of the resources. 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.Table of Contents
Page List
The page list is expressed via an HTML element (typically a nav
element [[!html]])
- in one of the resources. This element MUST be identified by the
+
The page list is expressed via an [[!html]] element (typically a nav
element) in
+ one of the resources. This element MUST be identified by the
role
attribute [[!html]] value
"doc-pagelist
" [[!dpub-aria-1.0]], and MUST be the first element in the document
- with that role
value document
- tree order [[!dom]].
role
value.
If the page list is not located in the primary entry page, the manifest SHOULD identify the resource that contains the structure.
@@ -838,29 +849,27 @@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 external resources (images, - script files, separate metadata files, etc.).
+ reading order. These properties refer to one or more resources, such as HTML + documents, images, script files, and separate metadata files.Informative properties identify resources that contain additional information about the Web - Publication, such as its privacy policy or an privacy policy or accessibility report.
Structural properties identify key meta structures of the Web Publication, such as the cover image, or the location of the table - of contents or the pagelist.
+ href="#cover">cover image, table of contents, and + page list.The categorization of properties is done to simplify comprehension of their purpose; the groupings have no relevance outside this specification (i.e., the groupings do not exist in the manifest).
-Each manifest item drawn from schema.org identifies the property it maps to and includes its defining type in parentheses. Properties are often available in many types, however, as a result @@ -912,9 +921,9 @@
These properties do not all have to be serialized in the manifest. Refer to each property's - definition to determine whether it is required in the manifest or can be compiled from other - information.
+These properties do not all have to be serialized in the authored manifest. Refer to each + property's definition to determine whether it is required in the manifest or can be compiled into + the canonical manifest from other information.
Values SHOULD be drawn from the preferred vocabulary for each accessibility property, but user agents MUST NOT omit values from - that are not included in the lists.
+ that are not included in the lists when generating the canonical + manifest. -The author can also provide a reference to a more detailed Accessibility Report, beyond the accessibility information - expressed by these properties.
+The author can also provide a reference to a detailed Accessibility Report if more information is needed than can + be expressed by these properties.
partial dictionary WebPublicationManifest { @@ -1276,8 +1286,9 @@Address
If the address does not resolve to an HTML - document [[!html]], user agents SHOULD NOT provide access to it to users. A Web Publication - MAY have more than one address, but all the addresses MUST resolve to the same document.
+ document [[!html]], user agents SHOULD NOT provide access to the resource to users. A Web + Publication MAY have more than one address, but all the addresses MUST resolve to the same + document.The referenced document SHOULD be a resource of the Web Publication. It can be any resource, including one that is not listed in the default reading order. This document MUST include @@ -1353,11 +1364,9 @@
The canonical identifier MUST be a URL [[!url]].
-If a URL is not provided in the manifest, or the value is an invalid URL, the Web 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.
+ identifier from any other identifiers provided in the manifest for the canonical manifest.Is a canonical identifier necessary to call out explicitly, or can it be handled by other metadata.
@@ -1399,18 +1408,7 @@A creator is an individual or entity responsible for the creation of the Web - Publication. Creators are represented in one of the following two ways:
- -Person
and Organization
objects,
- respectively. In other words, a single string value is a shorthand for a Person
object whose
- name
property is set to that string value. (See also .)
The following properties are categorized as creators:
@@ -1564,6 +1562,20 @@Creators are represented in one of the following two ways:
+ +Person
[[!schema.org]]; orPerson
or Organization
+ [[!schema.org]].In other words, a single string value is a shorthand for a [[!schema.org]] Person
+ whose name
property is set to that string value. (See also .)
When compiling each set of creator information from a
[[!schema.org]] Person
or Organization
type, user agents MUST
@@ -1590,7 +1602,7 @@
Note that user agents MAY interpret a wider range of creator properties defined by schema.org +
Note that user agents MAY interpret a wider range of creator properties defined by Schema.org than the ones in the preceding list.
The manifest MAY include more than one of each type of creator.
@@ -1689,61 +1701,15 @@of both the Web Publication (inLanguage
and inDirection
) and the
- natural language properties values of the manifest.
The manifest MAY contain global language and base direction declarations for the Web Publication. - The natural language MUST be a tag that conforms to [[!bcp47]], while the base language direction MUST 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;auto
: indicates that the textual values are explicitly directionally
- set to the direction of the first character with a strong directionality.When specified, these properties are also used as defaults for textual values in the +
of both the Web Publication and the natural language properties values of the manifest.
-It is important to differentiate the language of the publication from the - language and the base direction of the individual resources that compose it. If such resources - are, for example, in HTML, the language and direction need to be set in those resources, too. - The language and base direction of the publication are not inherited.
- -The global language information MAY be overridden by individual values.
- -When using Web Publication manifests with bidirectional text, user agents SHOULD identify the - base direction of any given natural language value by scanning the text for the first strong - directional character. Once the base direction has been identified, user agents MUST determine - the appropriate rendering and display of natural language values according to the Unicode - Bidirectional Algorithm [[!bidi]]. This could require wrapping additional control - characters or markup around the string prior to display, in order to apply the base direction. - (See .)
- -This section, in particular the features related to text directions, must be - reviewed by I18N experts.
- -If the manifest is embedded in the primary entry page via a
- script
element, and the manifest does not set the global language and/or the
- base direction (see ), the lang
- and the dir
attributes of the script
element are used as the global
- language and base direction, respectively (see the details on handling the lang
and dir
attributes in [[!html]]).
It is to be discussed whether this last paragraph, i.e., inheriting values from
- script
, should be kept.
If a user agent requires the language and one is not available in the manifest (globally, or - specifically for that property), or the obtained value is invalid, the user agent MAY attempt to - determine the language. This specification does not mandate how such a language tag is created. - The user agent might:
+If a user agent requires the language and one is not available in the authored manifest (either + globally or specifically for that property), or the obtained value is invalid, the user agent + MAY attempt to determine the language when generating the + canonical manifest. This specification does not mandate how such a language tag is + created. The user agent might:
No default values are specified for the language or the default base direction.
+This section, in particular the features related to text directions, must be + reviewed by I18N experts.
The manifest MAY include global language and base direction declarations for the Web + Publication using the following properties.
+The natural language MUST be a tag that conforms to [[!bcp47]], while the base language direction MUST 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;auto
: indicates that the textual values are explicitly
+ directionally set to the direction of the first character with a strong
+ directionality.When specified, these properties are also used as defaults for textual values in the + manifest.
+ +It is important to differentiate the language of the publication from + the language and the base direction of the individual resources that compose it. If such + resources are, for example, in HTML, the language and direction need to be set in those + resources, too. The language and base direction of the publication are not inherited.
+ +The global language information MAY be overridden by individual values.
+ +If the manifest is embedded in the primary entry page via a
+ script
element, and the manifest does not set the global language and/or
+ the base direction (see ), the
+ lang
and the dir
attributes of the script
element
+ are used as the global language and base direction, respectively (see the
+ details on handling the lang
and dir
+ attributes in [[!html]]).
It is to be discussed whether this last paragraph, i.e., inheriting values from
+ script
, should be kept.
If authors intend to use a manifest, or a manifest template, both as embedded
manifest and as a separate resource, they are strongly encouraged to set these properties
explicitly to avoid interference of the containing script
element in case of
@@ -1862,6 +1872,14 @@
When using Web Publication manifests with bidirectional text, user agents SHOULD identify the + base direction of any given natural language value by scanning the text for the first strong + directional character. Once the base direction has been identified, user agents MUST + determine the appropriate rendering and display of natural language values according to the + Unicode Bidirectional Algorithm [[!bidi]]. This could require wrapping additional + control characters or markup around the string prior to display, in order to apply the base + direction. (See .)
+dictionary LocalizableString { required DOMString value; @@ -2028,8 +2046,8 @@Reading Progression Direction
publication level interactions as menu position, swap direction, defining tap zones to lead the user to the next and previous pages, touch gestures, etc. -If the
+readingProgression
is not set, user agents MUST use the default value is -ltr
.If the
readingProgression
is not set, user agents MUST use the default value +ltr
when generating the canonical manifest.partial dictionary WebPublicationManifest { @@ -2085,7 +2103,7 @@Title
included in the manifest, user agents MAY use the value of thetitle
element [[!html]] of the Web Publication’s primary entry - page (if present) . + page (if present) when generating the canonical manifest.Relying on the
title
element could be semantically problematic if the Web Publication consists of several HTML resources (e.g., one per chapter of a book), because @@ -2140,7 +2158,11 @@Resource Categorization Properties
Default Reading Order
The default reading order is a specific progression through a set of Web - Publication resources. It is expressed using the
+ 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. + +readingOrder
property.The default reading order is expressed using the
readingOrder
property.
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 MUST include at least one resource.
The default reading order is specified directly in the manifest, but MAY be omitted when it only @@ -2282,9 +2300,6 @@
If present in the Web Publication Manifest, this item MUST be mapped on the
- resources
term, defined specifically for Web Publications.
partial dictionary WebPublicationManifest { sequence<PublicationLink> resources = []; @@ -2327,7 +2342,7 @@Links
Links provide a list of resources that are not required for the processing and rendering of a Web Publication (i.e., the content of the Web Publication remains unaffected even if these resources are not available). They are expressed - using the
+ using thelink
property.links
property.