Accessibility
The accessibility properties provides information about the suitability of a digital
publication for consumption by users with varying preferred reading modalities.
These properties typically supplement an evaluation against established accessibility
criteria, such as those provided in [WCAG20]. (For linking to a detailed accessibility
report, see .)
The following properties are categorized as accessibility properties:
Term |
Description |
Required Value |
Value Category |
[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). |
Array of Literals
|
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. |
Array of Literals
|
accessModeSufficient (CreativeWork) |
accessibilityFeature
|
Content features of the resource, such as accessible media, alternatives and
supported enhancements for accessibility. |
One or more text(s). |
Array of Literals
|
accessibilityFeature (CreativeWork) |
accessibilityHazard
|
A characteristic of the described resource that is physiologically dangerous to
some users. |
One or more text(s). |
Array of Literals
|
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. |
Localizable String
|
accessibilitySummary (CreativeWork) |
Detailed descriptions of these properties, including the expected values to use
with them, are available at [webschemas-a11y].
The author can also provide a reference to a detailed Accessibility Report if more information is needed than
can be expressed by these properties.
Example 8: Example accessiblity metadata for a document with text and images. The publication provides alternative text and long descriptions appropriate for each image, so can also be read in purely textual form.
{
"@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type" : "CreativeWork",
…
"accessMode" : ["textual", "visual"],
"accessModeSufficient" : [
{
"type" : "ItemList",
"itemListElement": ["textual", "visual"]
},
{
"type" : "ItemList",
"itemListElement": ["textual"]
}
],
…
}
Canonical Identifier
A digital publication's
canonical identifier property provides a unique identifier for the publication.
It is expressed using the id
property.
Term |
Description |
Required Value |
Value Type |
[schema.org] Mapping |
id
|
Preferred version of the publication. |
A URL record [url]. |
Identifier |
(None) |
The canonical identifier SHOULD be a URL that resolves to the preferred version of the
digital publication. Using a URL provides a measure of permanence above and
beyond a digital publication's address(es). If a digital publication
is permanently relocated to a new URL, for example, the canonical address provides a way of
discovering the new location (e.g., a DOI
registry could be updated with the new URL, or a redirect could be added to the URL of the
canonical identifier). It is also intended to provide a means of identifying instances of
the same digital publication hosted at different URLs.
Ensuring uniqueness of canonical identifiers is outside the scope of this
specification. The actual achievable uniqueness depends on such factors as the conventions
of the identifier scheme used and the degree of control over assignment of identifiers.
If a canonical identifier is not provided in the manifest, or the value is an invalid URL,
the digital publication does not have a canonical identifier. User agents MUST NOT attempt
to construct a canonical identifier from any other identifiers provided in the manifest for
the canonical manifest.
The specification of the canonical identifier MAY be complemented by the inclusion of
additional types of identifiers using the identifier
property [schema.org] and/or its subtypes.
Example 10: Example of setting the canonical identifier and the address as URLs
{
"@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type" : "TechArticle",
…
"id" : "http://www.w3.org/TR/tabular-data-model/",
"url" : "http://www.w3.org/TR/2015/REC-tabular-data-model-20151217/",
…
}
Example 11: Example of a URN for the canonical identifier
{
"@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type" : "Book",
…
"id" : "urn:isbn:9780123456789",
"url" : "https://publisher.example.org/mobydick",
…
}
Creators
A creator is an individual or entity responsible for the creation of the
digital publication.
The following properties are categorized as creators:
Creators are represented in one of the following two ways:
- as a string encoding the name of a
Person
[schema.org]; or
- as an instance of a
Person
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 retain the following information when available:
-
type
- One or more strings that identifies the type of creator. This sequence SHOULD include
"Person" or "Organization".
-
name
- One or more localizable strings for the name of the creator.
-
id
- A canonical identifier of the creator as an Identifier.
-
url
- An address for the creator in the form of a URL.
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.
{
"type" : "Book",
"@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
…
"url" : "https://publisher.example.org/mobydick",
"author" : {
"type" : "Person",
"name" : "Herman Melville"
}
}
Example 13: Separate listing of editors, authors, and publisher, with some persons expressed as simple strings
{
"@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type" : "TechArticle",
…
"id" : "http://www.w3.org/TR/tabular-data-model/",
"url" : "http://www.w3.org/TR/2015/REC-tabular-data-model-20151217/",
"author" : [
"Jeni Tennison",
{
"type" : "Person",
"name" : "Gregg Kellogg",
},{
"type" : "Person",
"name" : "Ivan Herman",
"id" : "https://www.w3.org/People/Ivan/"
}
],
"editor" : [
"Jeni Tennison",
{
"type" : "Person",
"name" : "Gregg Kellogg",
}
],
"publisher" : {
"type" : "Organization",
"name" : "World Wide Web Consortium",
"id" : "https://www.w3.org/"
}
…
}
Language and Base Direction
A digital publication has at least one natural language, which is the
language that the content is expressed in (e.g., English, French, Chinese). It also has a
natural base direction in which it is written — the display direction, either
left-to-right or right-to-left.
The digital publication manifest includes entries to set both these concepts, 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).
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.
Similarly, each natural language property value in the manifest (e.g., title, creators) is a localizable string.
For more information about localized strings on the Web, refer to
[string-meta].
The natural language and base direction can be set for both the publication and the natural language properties values of the
manifest.
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:
- use the non-empty language declaration of the manifest;
- use the first non-empty language declaration found in a resource in the default
reading order;
- calculate the language using its own algorithm.
No default values are specified for the language or the default base
direction.
Global Language and Direction
The manifest MAY include global language and base direction declarations for the
publication using the following properties.
Term |
Description |
Required Value |
Value Category |
[schema.org] Mapping |
inLanguage
|
Default language for the publication as well as the textual manifest
values |
language code as defined in [bcp47] |
Literal
|
inLanguage (Property) |
inDirection
|
Default base direction for the publication as well as the textual
manifest values |
ltr , rtl , or auto |
Literal
|
(None) |
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, following the rules of the Unicode Bidirectional Algorithm
[bidi].
When specified, these properties are also used as defaults for textual values in the
manifest.
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]).
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.
Item-specific Language
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]:
Example 15: Setting the author name to French using a localizable string
{
"@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type" : "Book",
…
"author" : {
"type" : "Person",
"name" : {
"value" : "Marcel Proust",
"language" : "fr"
}
}
}
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 the inLanguage
property, if applicable, and unset otherwise. In other words, the previous example is
equivalent to:
Example 16: Setting the default language of an author name to French
{
"@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type" : "Book",
"inLanguage" : "fr",
…
"author" : "Marcel Proust",
…
}
(See also .)
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 manifests to include this.
In order to correctly handle manifests entries containing right-to-left or 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.
In situations where the first-strong heuristics will produce the wrong
result (e.g., a string in the Arabic or Hebrew script that begins with a Latin acronym),
content developers may want to prepend a Unicode formatting character to the string.
This would then produce the necessary base direction when the heuristics are applied.
They should use one of the following formatting characters: U+200E LEFT-TO-RIGHT MARK,
or U+200F RIGHT-TO-LEFT MARK. (See .)
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 markup or Unicode
formatting characters around the string prior to display, in order to apply the base
direction.
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 markup or control characters
around the string prior to display, in order to apply the base direction. (See .
Reading Progression Direction
The reading progression establishes the reading
direction from one resource to the next within a digital publication. It is expressed
using the readingDirection
property.
Term |
Description |
Required Value |
Value Category |
[schema.org] Mapping |
readingProgression
|
Reading direction from one resource to the other. |
ltr or rtl |
Literal
|
(None) |
The value of this property MUST be either:
ltr
: left-to-right;
rtl
: right-to-left.
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.
The reading progression of a 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
ltr
when generating the canonical manifest.
Example 19: Reading progression set explicitl to ltr
{
"@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type" : "Book",
…
"url" : "https://publisher.example.org/mobydick",
"readingProgression" : "ltr"
}