Web Publications

1.3 Terminology

This document uses terminology defined by the W3C Note "Publishing and Linking on the Web" [publishing-linking], including, in particular, user, user agent, browser, and address.

Identifier

An identifier is metadata that can be used to refer to Web Content in a persistent and unambiguous manner. URLs, URNs, DOIs, ISBNs, and PURLs are all examples of persistent identifiers frequently used in publishing.

Manifest

A manifest represents structured information about a Web Publication, such as informative metadata, a list of all resources, and a default reading order.

Non-empty

For the purposes of this specification, non-empty is used to refer to an element, attribute or property whose text content or value consists of one or more characters after whitespace normalization, where whitespace normalization rules are defined per the host format.

URL

The general term URL is defined by the URL Standard [url]. It is used as in other W3C specifications, like HTML [html]. In particular, a URL allows for the usage of characters from Unicode following [rfc3987]. See the note in the HTML5 specification for further details.

Web Publication

A Web Publication is a collection of one or more resources, organized together through a manifest into a single logical work with a default reading order. The Web Publication is uniquely identifiable and presentable using Open Web Platform technologies.

2.1 Conformance Classes

This specification defines two conformance classes: one for Web Publications and one for user agents that process them.

A Web Publication conforms to this specification if it meets the following criteria:

• it has a manifest that conforms to 4.2 Requirements;
• it adheres to the construction requirements defined in 3. Web Publication Construction.

A user agent conforms to this specification if it meets the following criteria:

• it is capable of obtaining a conforming manifest for a Web Publication.

3.1 Manifest

dictionary WebPublicationManifest {

};

{
    "@context" : ["https://schema.org", "https://www.w3.org/ns/wp-context"],
    …
}

{
    …
    "resources" : [
        "datatypes.svg",
        {
            "type"            : "LinkedResource",
            "url"             : "test-utf8.csv",
            "encodingFormat"  : "text/csv",
            "name"            : "Test Results",
            "description"     : "CSV file containing the full data set used."
        },
        {
            "type"            : "LinkedResource",
            "url"             : "terminology.html",
            "encodingFormat"  : "text/html",
            "rel"             : "glossary"
        }
    ]
}

dictionary LinkedResource {
    required DOMString           url;
             DOMString           encodingFormat;
             sequence<LocalizableString>   name;
             LocalizableString   description;
             sequence<DOMString> rel;
};

{
    "@context" : ["https://schema.org", "https://www.w3.org/ns/wp-context"],
    "type"     : "CreativeWork"
    …
}

{
    "@context" : ["https://schema.org", "https://www.w3.org/ns/wp-context"],
    "type"     : "Book"
    …
}

{
    "@context" : ["https://schema.org", "https://www.w3.org/ns/wp-context"],
    "type"     : ["Book", "VisualArtwork"],
    …
}

partial dictionary WebPublicationManifest {
    required sequence<DOMString> type;
};

<script id="example_manifest" type="application/ld+json">
   {
      …
   }
</script>

<link href="#example_manifest" rel="publication">
…
<script id="example_manifest" type="application/ld+json">
{
       "@context" : ["https://schema.org", "https://www.w3.org/ns/wp-context"],
       …
}
</script>

3.2 Web Publication Bounds

A Web Publication consists of a finite set of resources that represent its content. This extent is known as its bounds and is defined within its manifest — it is obtained from the union of resources listed in the default reading order and resource list.

To determine whether a resource is within the bounds of a Web Publication, user agents MUST compare the absolute URL of a resource to the absolute URLs of the resources obtained from the union. If the resource is identified in the enumeration, it is within the bounds of the Web Publication. All other resources are external to the Web Publication.

Resources within the bounds of a Web Publication do not have to share the same domain.

3.3 Resources

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 dependencies of other resources.

3.4 Primary Entry Page

The primary entry page represents the preferred starting resource for a Web Publication and enables discovery of its manifest. It is the resource that is returned when accessing the Web Publication's address, and MUST be included in either the default reading order or the resource list.

Although any resource can link to the Web Publication manifest, the primary entry page typically introduces the publication and provides access to the content. It might contain all the content, in the case of a single-page Web Publication, or provide navigational aids to begin reading a multi-document Web Publication. To facilitate the user ease of consumption, the primary entry page SHOULD contain the table of contents.

It is not required that the primary entry page be included in the default reading order, nor that it be the first document listed when it is included. This specification leaves the exact nature of the document intentionally underspecified to provide flexibility for different approaches. If a default reading order is not provided, however, user agents will create one using the primary entry page.

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 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).

In certain cases where information has been omitted from the manifest, user agents will sometimes use the primary entry page as a fallback source of information (see language and base direction and title).

3.5 Table of Contents

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 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.

If the table of contents is not located in the primary entry page, the manifest SHOULD identify the resource that contains the structure.

When specified, the table of content MUST include a link to at least one resource, and all links SHOULD refer to resources within publication bounds.

Refer to the table of contents property definition for more information on how to identify which resource contains the table of contents.

3.6 Page List

The page list is a list of links that provides navigation to static page demarcation points within 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 to ease navigation.

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 — in document tree order [dom] — with that role value.

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.

Refer to the pagelist property definition for more information on how to identify which resource contains the page list.

4.2 Requirements

The requirements for the expression of Web Publication properties are defined as follows:

REQUIRED:

• address
• default reading order
• title

RECOMMENDED:

• accessibility
• accessibility report
• base direction
• canonical identifier
• cover
• creators
• language and base direction
• links
• last modification date
• publication date
• privacy policy
• reading progression direction
• resource list
• table of contents
• page list

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.

4.4 Descriptive Properties

partial dictionary WebPublicationManifest {
    sequence<DOMString> accessMode;
    sequence<DOMString> accessModeSufficient;
    sequence<DOMString> accessibilityAPI;
    sequence<DOMString> accessibilityControl;
    sequence<DOMString> accessibilityFeature;
    sequence<DOMString> accessibilityHazard;
    LocalizableString      accessibilitySummary;
};

{
    "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"     : "CreativeWork",
    …
    "accessibilityAPI"      : "ARIA",
    "accessMode"            : ["textual", "visual"],
    "accessModeSufficient"  : [
        {
            "type"           : "ItemList",
            "itemListElement": ["textual", "visual"]
        },
        {
            "type"           : "ItemList",
            "itemListElement": ["textual"]
        }
    ],
    …
}

partial dictionary WebPublicationManifest {
    required DOMString url;
};

{
    "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"     : "Book",
    …
    "url"      : "https://publisher.example.org/mobydick",
    …
}

partial dictionary WebPublicationManifest {
    DOMString id;
};

{
    "@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/",
    …
}

{
    "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"     : "Book",
    …
    "isbn"     : "9780123456789",
    "url"      : "https://publisher.example.org/mobydick",
    …
}

partial dictionary WebPublicationManifest {
    sequence<CreatorInfo> artist;
    sequence<CreatorInfo> author;
    sequence<CreatorInfo> colorist;
    sequence<CreatorInfo> contributor;
    sequence<CreatorInfo> creator;
    sequence<CreatorInfo> editor;
    sequence<CreatorInfo> illustrator;
    sequence<CreatorInfo> inker;
    sequence<CreatorInfo> letterer;
    sequence<CreatorInfo> penciler;
    sequence<CreatorInfo> publisher;
    sequence<CreatorInfo> readBy;
    sequence<CreatorInfo> translator;
};


dictionary CreatorInfo {
             sequence<DOMString>         type;
    required sequence<LocalizableString> name;
             DOMString                      id;
             DOMString                      url;
};

{
    "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"     : "Book",
    …
    "url"      : "https://publisher.example.org/mobydick",
    "author"   : {
        "type"  : "Person",
        "name"  : "Herman Melville"
    }
}

{
    "@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/"
    }
    …
}

partial dictionary WebPublicationManifest {
    DOMString     inLanguage;
    TextDirection inDirection;
};

enum TextDirection {
    "ltr",
    "rtl",
    "auto"
};

{
    "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"     : "Book",
    …
    "author" : {
        "type"  : "Person",
        "name" : {
            "value"    : "Marcel Proust",
            "language" : "fr"
        }
    }
}

{
    "@context"   : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"       : "Book",
    "inLanguage" : "fr",
    …
    "author"     : "Marcel Proust",
}

dictionary LocalizableString {
    required DOMString value;
             DOMString language;
};

partial dictionary WebPublicationManifest {
    DOMString dateModified;
};

{
    "@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/",
    "dateModified" : "2015-12-17",
    …
}

partial dictionary WebPublicationManifest {
    DOMString datePublished;
};

{
    "@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/",
    "datePublished" : "2015-12-17",
    "dateModified"  : "2016-01-30",
    …
}

partial dictionary WebPublicationManifest {
    ProgressionDirection readingProgression = "ltr";
};

enum ProgressionDirection {
	"ltr",
	"rtl"
};

{
    "@context"           : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"               : "Book",
    …
    "url"                : "https://publisher.example.org/mobydick",
    "readingProgression" : "ltr"
}

partial dictionary WebPublicationManifest {
    required sequence<LocalizableString> name;
};

{
    "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"     : "Book",
    …
    "url"      : "https://publisher.example.org/mobydick",
    "name"     : "Moby Dick"
}

4.5 Resource Categorization Properties

Web Publication resources are specified via the default reading order, the resource list, and the links, as defined in this section. These lists contain references to informative properties like the privacy policy, and structural properties like the table of contents.

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.

partial dictionary WebPublicationManifest {
   required sequence<LinkedResource> readingOrder;
};

{
    "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"     : "Book",
    …
    "url"      : "https://publisher.example.org/mobydick",
    "name"     : "Moby Dick",
    "readingOrder" : [
        "html/title.html",
        "html/copyright.html",
        "html/introduction.html",
        "html/epigraph.html",
        "html/c001.html",
        …
    ]
}

{
    "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"     : "Book",
    …
    "url"      : "https://publisher.example.org/mobydick",
    "name"     : "Moby Dick",
    "readingOrder" : [{
        "type"           : "LinkedResource",
        "url"            : "html/title.html",
        "encodingFormat" : "text/html",
        "name"           : "Title page"
    },{
        "type"           : "LinkedResource",
        "url"            : "html/copyright.html",
        "encodingFormat" : "text/html",
        "name"           : "Copyright page"
    },{
        …
    }]
}

partial dictionary WebPublicationManifest {
    sequence<LinkedResource> resources = [];
};

{
    "@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/",
    …
    "resources"  : [
        "datatypes.html",
        "datatypes.svg",
        "datatypes.png",
        "diff.html",
        {
            "type"              : "LinkedResource",
            "url"               : "test-utf8.csv",
            "encodingFormat"    : "text/csv"
        },{
            "type"              : "LinkedResource",
            "url"               : "test-utf8-bom.csv",
            "encodingFormat"    : "text/csv"
        },{
            …
        }
    ],
    …
}

partial dictionary WebPublicationManifest {
    sequence<LinkedResource> links = [];
};

4.6 Informative Properties

{
    "@context"   : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"       : "Book",
    …
    "url"        : "https://publisher.example.org/mobydick",
    "name"       : "Moby Dick",
    "links"  : [{
        "type"        : "LinkedResource",
        "url"         : "https://www.publisher.example.org/mobydick-accessibility.html",
        "rel"         : "https://www.w3.org/ns/wp#accessibility-report"
    },{
        …
    }],
    …
}

{
    "@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/",
    …
    "links"  : [{
        "type"           : "LinkedResource",
        "url"            : "https://www.w3.org/Consortium/Legal/privacy-statement-20140324",
        "encodingFormat" : "text/html",
        "rel"            : "privacy-policy"
    },{
            …
    }],
    …
}

4.7 Structural Properties

{
    "@context"   : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"       : "Book",
    …
    "url"        : "https://publisher.example.org/donquixote",
    "name"       : "Don Quixote",
    "resources"  : [{
        "type"           : "LinkedResource",
        "url"            : "cover.html",
        "encodingFormat" : "text/html"
        "rel"            : "https://www.w3.org/ns/wp#cover"
    },{
        …
    }],
    …
}

{
    "@context"   : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"       : "Book",
    …
    "url"        : "https://publisher.example.org/mobydick",
    "name"       : "Moby Dick",
    "resources"  : [{
        "type"           : "LinkedResource",
        "url"            : "whale-image.jpg",
        "encodingFormat" : "image/jpeg",
        "rel"            : "https://www.w3.org/ns/wp#cover",
        "name"           : "Moby Dick attacking hunters",
        "description"    : "A white whale is seen surfacing from the water to attack a small whaling boat"
    },{
        …
    }],
    …
}

{
    "@context"   : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"       : "Book",
    …
    "url"        : "https://publisher.example.org/donquixote",
    "name"       : "Gulliver's Travels",
    "resources"  : [{
        "type"           : "LinkedResource",
        "url"            : "lilliput.jpg",
        "encodingFormat" : "image/jpeg",
        "rel"            : "https://www.w3.org/ns/wp#cover"
    },{
        "type"           : "LinkedResource",
        "url"            : "lilliput.svg",
        "encodingFormat" : "image/svg+xml",
        "rel"            : "https://www.w3.org/ns/wp#cover"
    },{
        …
    }],
    …
}

{
"@context"   : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type"       : "Book",
…
"url"        : "https://publisher.example.org/mobydick",
"name"       : "Moby Dick",
"resources"  : [{
	"type"       : "LinkedResource",
	"url"        : "toc_file.html",
	"rel"        : "https://www.w3.org/ns/wp#pagelist"
},{
	…
}],
…
}

{
    "@context"   : ["https://schema.org","https://www.w3.org/ns/wp-context"],
    "type"       : "Book",
    …
    "url"        : "https://publisher.example.org/mobydick",
    "name"       : "Moby Dick",
    "resources"  : [{
        "type"       : "LinkedResource",
        "url"        : "toc_file.html",
        "rel"        : "contents"
    },{
        …
    }],
    …
}

<head>
    …
    <script type="application/ld+json">
    {
        "@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/",
        …
    }
    </script>
    …
</head>
<body>
    …
    <section role="doc-toc">
        …
    </section>
    …
</body>

4.8 Extensibility

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:

1. by the provision of linked metadata records.
2. through the inclusion of additional properties in the manifest;

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 manifest. A user agent MAY ignore some or all extended properties.

{
"@context"   : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type"       : "Book",
…
"url"        : "https://publisher.example.org/mobydick",
"name"       : "Moby Dick",
"links"  : [{
	"type"            : "LinkedResource",
	"url"             : "https://www.publisher.example.org/mobydick-onix.xml",
	"encodingFormat"  : "application/onix+xml",
	"rel"             : "describedby"
},{
	…
}],
…
}

{
"@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/",
"copyrightYear"   : "2015",
"copyrightHolder" : "World Wide Web Consortium",
…
}

{
"@context"   : ["https://schema.org","https://www.w3.org/ns/wp-context"],
"type"       : "CreativeWork",
…
"id"         : "http://www.w3.org/TR/tabular-data-model/",
"url"        : "http://www.w3.org/TR/2015/REC-tabular-data-model-20151217/",
"dc:subject" : ["Web data description languages","Data integration","Data Exchange"]
…
}

5.1 Obtaining a manifest

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.

1. From the Document of the top-level browsing context of the primary entry page, let origin be the Document's origin, and manifest link be the first link element in tree order in Document whose rel attribute contains the publication token.
2. If origin is an [html] opaque origin, terminate this algorithm.
3. If manifest link is null, terminate this algorithm.
4. If manifest link's href attribute's value is the empty string, terminate this algorithm.
5. If manifest link's href attribute's value is a relative URL, i.e., it points to origin and it has a non-null fragment identifying an identifier id in Document:
   1. Let embedded manifest script be the first script element in tree order, whose id attribute is equal to id and whose type attribute is equal to application/ld+json.
   2. If embedded manifest script is null, terminate this algorithm.
   3. Let text be the child text content of embedded manifest script
   4. Let base be the value of baseURI of the script element.
   Explanation

   This branch is in use when the manifest is embedded in the primary entry page. The algorithm locates the script element and extract the manifest itself. The document's URL or, if set by the author, the value of a possible base element will be used to turn relative URLs into absolute ones.

6. Otherwise:
   1. Let manifest URL be the result of parsing the value of the href attribute, relative to the element's base URL. If parsing fails, then abort these steps.
   2. Let request be a new [fetch] request, whose URL is manifest URL, and whose context is the same as the browsing context of the Document.
   3. If the manifest link's crossOrigin attribute's value is 'use-credentials', then set request's credentials to 'include'.
   4. Await the result of performing a fetch with request, letting response be the result.
   5. If response is a network error, terminate this algorithm.
   6. Let text be the result of UTF-8 decoding response's body.
   7. Let base be the value of manifest URL.
   Explanation

   This branch is in use when the manifest is in a separate file. It performs the standard operations to retrieve the manifest from the Web; the URL of the manifest file will be used to turn relative URLs into absolute ones.

7. Let json be the result of parsing text. If parsing throws an error, terminate this algorithm.
8. If Type(json) is not Object, terminate this algorithm.
9. Let canonical manifest be the canonical manifest derived from json, using the values of json, base, and Document as input to the algorithm described in 5.2 Generating a Canonical Manifest.
10. Check whether the canonical manifest fulfills the minimal requirements for a Web Publication Manifest, namely:
    • The JSON-LD context is set (see 3.1.3 Manifest Contexts)
    • The Publication type is set (see 3.1.5 Publication Types)
    • The Publication address is set (see 4.4.2 Address)
    If any of these requirements is not fulfilled, terminate the algorithm.
11. Let processed manifest be the result of running processing a manifest given canonical manifest.
12. Return processed manifest.

5.2 Generating a Canonical Manifest

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 manifest the JSON object that represent the manifest
• the base URL string, that represents the base URL for the manifest
• the document HTML Document (DOM) Node, representing the primary entry page

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"}.

1. let lang string represent the default language, set to:
   • the value of the lang value for the script element in the primary entry page, in case the manifest is embedded; or
   • undefined otherwise
   Explanation

   This value is used in the step on language below.

2. let dir string represents the base direction, set to:
   • the value of the dir value for the script element in the primary entry page, in case the manifest is embedded; or
   • undefined otherwise
   Explanation

   This value is used in the step on base direction below.

3. (4.4.9 Title) if manifest["name"] is undefined, then locate the title HTML element using document. If that element exists and is non-empty, let t be its text content, and add to manifest:
   • if the language of title is explicitly set to the value of l, then add
     "name": [{"value": t, "language": l}]
   • or
     "name": [t]
     otherwise
   Explanation

   This step ensures that the title element's content in the primary entry page can be used, as a default, as the title of the publication. For example,

   Example 38

   <html>
   <head>
       <title>Moby Dick</title>
       …
       <script type="application/ld+json">
       {
           "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
           …
       }
       </script>

   yields (unless the name is set explicitly in the manifest):

   Example 39

   {
       "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
       "name"     : ["Moby Dick"],
       …
   }

4. (4.4.5 Language and Base Direction) if manifest["inLanguage"] is undefined and the value of lang is not undefined, add
   "inLanguage": lang
   to manifest
   Explanation

   This step ensures that the language explicitly set in the primary entry page is valid for an embedded manifest content. For example,

   Example 40

   <html>
   <head>
       …
       <script type="application/ld+json" lang=ur>
       {
           "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
           …
       }
       </script>

   yields (unless the language and the direction are set explicitly in the manifest):

   Example 41

   {
       "@context"    : ["https://schema.org","https://www.w3.org/ns/wp-context"],
       "inLanguage"  : "ur",
       …
   }

5. (4.4.5 Language and Base Direction) if manifest["inDirection"] is undefined and the value of dir is not undefined, add
   "inDirection": dir
   to manifest
   Explanation

   This step ensures that the base direction explicitly set in the primary entry page is valid for an embedded manifest content. For example,

   Example 42

   <html>
   <head>
       …
       <script type="application/ld+json" dir=rtl lang=ur>
       {
           "@context" : ["https://schema.org","https://www.w3.org/ns/wp-context"],
           "inLanguage"  : "ur",
           …
       }
       </script>

   yields (unless the language and the direction are set explicitly in the manifest):

   Example 43

   {
       "@context"    : ["https://schema.org","https://www.w3.org/ns/wp-context"],
       "inLanguage"  : "ur",
       "inDirection" : "rtl"
       …
   }

6. (4.5.1 Default Reading Order) if manifest["readingOrder"] is undefined, let u be the value of document.URL, and add
   "readingOrder": [{"type": ["LinkedResource"], "url": u}]
   to the manifest
   Explanation

   If the publication consists only of the primary entry page, the default reading order can be omitted; it will consist, automatically, of that single resource.

7. (3.1.4.1 Arrays and Single Values) consider P["term"], where P is any object in manifest (including itself) and term is
   • type; or
   • one of the accessibility terms except for accessibilitySummary; or
   • one of the creator terms; or
   • name; or
   • one of the resource categorization properties; or
   • rel.
   If P["term"] is a single string or object v, then change the relevant term/value to
   "term": [v]
   Repeat this step for all possible values of P["term"].
   Explanation

   A number of terms require their values to be arrays but, for the sake of convenience, authors are allowed to use a single value instead of a one element array. For example,

   Example 44

   {
       "@context"  : ["https://schema.org","https://www.w3.org/ns/wp-context"],
       "name"      : "Moby Dick",
       "author"    : "Herman Melville",
       "resources" : [{
           "type"           : "LinkedResource",
           "rel"            : "https://www.w3.org/ns/wp#cover-page",
           "url"            : "images/cover.jpg"
           "encodingFormat" : "image/jpeg"
       },
           …
       }],
       …
   }

   yields:

   Example 45

   {
       "@context"  : ["https://schema.org","https://www.w3.org/ns/wp-context"],
       "name"      : ["Moby Dick"],
       "author"    : ["Herman Melville"],
       "resources" : [{
           "type"           : ["LinkedResource"],
           "rel"            : ["https://www.w3.org/ns/wp#cover-page"],
           "url"            : "images/cover.jpg"
           "encodingFormat" : "image/jpeg"
       },
           …
       }],
       …
   }

8. (4.4.4 Creators) if the value v in a manifest["term"] array, where term is one of the creator terms, is a simple string or localizable string, exchange that element in the array to
   {"type": ["Person"], "name": [v]}
   Repeat this step for all possible values of v.
   Explanation

   An author, editor, etc., should be explicitly designed as an object of type Person but, for the sake of convenience, authors are allowed to just give their name. For example,

   Example 46

   {
       "@context"  : ["https://schema.org","https://www.w3.org/ns/wp-context"],
       "name"      : ["Moby Dick"],
       "author"    : ["Herman Melville"],
       …
   }

   yields:

   Example 47

   {
       "@context"  : ["https://schema.org","https://www.w3.org/ns/wp-context"],
       "name"      : ["Moby Dick"],
       "author"    : [{
           "type" : ["Person"],
           "name" : "Herman Melville"
       }],
       …
   }

9. (3.1.4.3 Link Values) if the value v in a manifest["term"] array, where term is one of the resource categorization properties, is a simple string, exchange that element in the array to
   {"type": ["LinkedResource"], "url": v}
   Repeat this step for all possible values of v.
   Explanation

   Resource links should be explicitly designed as an object of type LinkedResource but, for the sake of convenience, authors are allowed to just give their absolute or relative URL. For example,

   Example 48

   {
       "@context"  : ["https://schema.org","https://www.w3.org/ns/wp-context"],
       …
       "resources" : [
           "css/mobydick.css",
           …
       ],
       …
   }

   yields:

   Example 49

   {
       "@context"  : ["https://schema.org","https://www.w3.org/ns/wp-context"],
       …
       "resources" : [{
           "type" : ["LinkedResource"],
           "url"  : "css/mobydick.css"
       },
           …
       ],
       …
   }

10. (3.1.4.2 Text Values or Objects) let v be the value, or one of the values in case of an array, of P["term"], where P is any object in manifest (including itself) and term is:
    • accessibilitySummary; or
    • name; or
    • description.
    If v is a single string, then change the relevant term/value to:
    • if manifest[inLanguage] is set to the value of l then
      "term": {"value": v,"language": l}
    • otherwise
      "term": {"value": v}
    Repeat this step for all possible values of v.
    Explanation

    Natural language text values should be explicitly designed as localizable string objects but, for the sake of convenience, authors are allowed to just use a simple string. I.e., if no language information has been provided (via inLanguage) in the manifest then, for example,

    Example 50

    {
        "@context"  : ["https://schema.org","https://www.w3.org/ns/wp-context"],
        "name"      : ["Moby Dick"],
        "author"    : ["Herman Melville"],
        …
    }

    yields:

    Example 51

    {
        "@context"  : ["https://schema.org","https://www.w3.org/ns/wp-context"],
        "name"      : [{
            "value" : "Moby Dick"
        }],
        "author"    : [{
            "value" : "Herman Melville"
        }],
        …
    }

    If an explicit language has also been provided in the manifest, that language is also added to the localizable string object. For example,

    Example 52

    {
        "@context"   : ["https://schema.org","https://www.w3.org/ns/wp-context"],
        "inLanguage" : "en",
        "name"       : ["Moby Dick"],
        "author"     : ["Herman Melville"],
        …
    }

    yields:

    Example 53

    {
        "@context"  : ["https://schema.org","https://www.w3.org/ns/wp-context"],
        "inLanguage": "en",
        "name"      : [{
            "value"    : "Moby Dick",
            "language" : "en"
        }],
        "author"    : [{
            "value"    : "Herman Melville"
            "language" : "en"
        }],
        …
    }

11. (3.1.7 Relative URLs) if the value of P["term"], where P is any object in manifest (including itself) and term is:
    • url; or
    • id
    is a single string u which is not an absolute URL string, then resolve this value (considered to be a relative URL) using the value of base, yielding the value of au, and replace the term/value pair by
    "term": au
    Explanation

    All relative URLs in the publication manifest must be resolved against the base value to yield absolute URLs.

12. Return the (transformed) manifest.

5.3 Processing the manifest

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.

1. Let manifest object be the result of converting json to a WebPublicationManifest dictionary.
2. Extension point: process any proprietary and/or other supported members at this point in the algorithm.
3. Perform data cleanup operations on manifest object, possibly removing data, as well as raising warnings.
   1. Check whether the value of manifest object["url"] is a valid URL [url]. If not, issue a warning.
   2. For all the terms defined in 4.4.1 Accessibility, except for accessModeSufficient and accessibilitySummary, check whether all tokens listed in manifest[term] are defined in the preferred vocabulary (see the list of expected values for each). Issue a warning for each unrecognized value.
   3. For all values in manifest object["accessModeSufficient"], check whether each token in each ItemList [schema.org] is defined in the preferred vocabulary (see the list of expected values). Issue a warning for each unrecognized value.
   4. For all the terms defined in 4.4.4 Creators, check whether every object Obj in manifest object[term] has Obj["name"] set. If not, remove Obj from manifest object[term] array and issue a warning.
   5. Check whether the value of manifest object["name"] is not empty. If it is, generate a value (see the separate note for details) and issue a warning.
   6. For all the terms defined in 4.5 Resource Categorization Properties, check whether every object Obj in manifest object[term] has Obj["url"] set. If not, remove Obj from manifest object[term] array and issue a warning. If yes, check whether Obj["url"] is a valid URL [url] and, if not, issue a warning.
   7. Check whether manifest object["datePublished"] is a valid date or date-time, per [iso8601]. If the check fails, issue a warning.
   8. Check whether manifest object["dateModified"] is a valid date or date-time, per [iso8601]. If the check fails, issue a warning.
4. Return manifest object.