/
index.html
5736 lines (5205 loc) · 234 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
<head>
<meta charset="utf-8" />
<title>Publication Manifest</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove" defer="defer"></script>
<script src="common/js/biblio.js" class="remove"></script>
<script src="common/js/idllink.js" class="remove"></script>
<script src="https://unpkg.com/reqlist/lib/reqlist.js" class="remove"></script>
<link href="https://unpkg.com/reqlist/lib/reqlist.css" class="removeOnSave" rel="stylesheet" type="text/css" />
<link href="common/css/common.css" rel="stylesheet" type="text/css" />
<script class="remove">
//<![CDATA[
var respecConfig = {
preProcess: [ prepare_reqlist ],
postProcess: [ convert_dfn_to_link, add_reqlist_button],
group: "pm",
specStatus: "ED",
prEnd: "2020-10-30",
shortName: "pub-manifest",
previousPublishDate: "2020-10-01",
previousMaturity: "PR",
implementationReportURI: "https://www.w3.org/publishing/groups/publ-wg/implementation/results.html",
crEnd: "2020-03-31",
updateableRec: true,
edDraftURI: "https://w3c.github.io/pub-manifest/",
errata: "https://w3c.github.io/pub-manifest/errata/",
editors:[ {
"name": "Matt Garrish",
"company": "DAISY Consortium",
"companyURL": "https://daisy.org",
"w3cid": 51655
}, {
"name": "Ivan Herman",
"url": "https://www.w3.org/People/Ivan/",
"company": "W3C",
"w3cid": 7382,
"orcid": "0000-0003-0782-2704",
"companyURL": "https://www.w3.org",
}],
processVersion: 2020,
includePermalinks: true,
permalinkEdge: true,
permalinkHide: false,
pluralize: true,
diffTool: "http://www.aptest.com/standards/htmldiff/htmldiff.pl",
wgPublicList: "public-pm-wg",
github: {
repoURL: "https://github.com/w3c/pub-manifest/",
branch: "main"
},
localBiblio: localBiblio,
alternateFormats: [{
"uri": "pub-manifest.epub",
"label": "EPUB"
}]
};//]]>
</script>
<style>
var {
color: brown;
}
code.json {
color: teal;
}</style>
</head>
<body>
<section id="abstract">
<p>This specification defines a general manifest format for expressing information about a digital
publication. It uses [[schema.org]] metadata augmented to include various structural properties about
publications, serialized in [[json-ld11]], to enable interoperability between publishing formats while
accommodating variances in the information that needs to be expressed.</p>
</section>
<section id="sotd"></section>
<section id="intro">
<h2>Introduction</h2>
<section id="scope">
<h3>Scope</h3>
<p>This specification defines a general manifest format to describe publications. It is designed to be
adaptable to the needs of specific areas of publishing, such as audiobook production, by specifying
a modular approach for creating specializations.</p>
<p>This specification is also intended to facilitate different user agent architectures. While it is
expected that traditional Web user agents (browsers) will be able to consume a publication manifest,
this should not limit the capabilities of any other possible type of user agent (e.g., applications,
whether standalone or running within a user agent, or even publications that include their own user
interface).</p>
<p>This specification does not define how user agents are expected to render publications that use the
manifest format.</p>
</section>
<section id="manifest-format" class="informative">
<h4>Manifest Format</h4>
<p>A <a>digital publication</a> is described by its <a>manifest</a>, which provides a set of properties
expressed using a specific shape of JSON-LD [[json-ld11]] (a variant of JSON [[ecma-404]]
for linked data).</p>
<p>The manifest is what enables user agents to understand the <a>bounds</a> of <a>digital
publication</a> and the connection between its resources. It includes metadata that describes
the digital publication, as a publication has an identity and nature beyond its constituent
resources. The manifest also provides a <a href="#resource-list">list of resources</a> that belong
to the digital publication and a <a href="#default-reading-order">default reading order</a>, which
is how it connects resources into a single contiguous work.</p>
<p>The properties of the manifest describe the basic information a user agent requires to process and
render a publication. For ease of understanding, these properties are categorized as follows:</p>
<dl>
<dt>
<a href="#descriptive-properties">Descriptive properties</a>
</dt>
<dd>
<p>Descriptive properties describe aspects of a digital publication, such as its <a
href="#pub-title">title</a>, <a href="#creators">creator</a>, and <a href="#inLanguage"
>language</a>.</p>
</dd>
<dt>
<a href="#resource-categorization-properties">Resource categorization properties</a>
</dt>
<dd>
<p>Resource categorization properties describe or identify common sets of resources, such as the
<a href="#resource-list">resource list</a> and <a href="#default-reading-order">default
reading order</a>. These properties refer to one or more resources, such as HTML
documents, images, scripts, and metadata records.</p>
</dd>
</dl>
<p>The <a>manifest</a> also identifies key resources of a digital publication using link relations.
These relations are defined in the <a href="#linkedresource-rel"><code>rel</code> property</a> of
<a><code>LinkedResource</code></a> objects (i.e., the JSON objects that represent each
resource in the default reading order, resource list, and links sections).</p>
<p>The types of resources these relations identify are categorized as follows:</p>
<dl>
<dt>
<a href="#informative-rel">Informative resources</a>
</dt>
<dd>
<p>Informative resources are resources that contain additional information about the
publication, such as its <a href="#privacy-policy">privacy policy</a>, <a
href="#accessibility-report">accessibility report</a>, or <a href="#preview"
>preview</a>.</p>
</dd>
<dt>
<a href="#structural-rel">Structural resources</a>
</dt>
<dd>
<p>Structural resources are key meta structures of the publication, such as the <a href="#cover"
>cover image</a>, <a href="#contents">table of contents</a>, and <a href="#page-list"
>page list</a>.</p>
</dd>
</dl>
</section>
<section id="manifest-jsonld">
<h4>JSON-LD Authoring and Processing</h4>
<p>This specification defines the publication manifest as a specific "shape" of [[!json-ld11]]. This
means that the manifest SHOULD be expressed using only the syntactic constructions defined in this
specification, as opposed to all the possibilities offered by the JSON-LD syntax.</p>
<p class="note">This shape is also defined, informally, through a JSON schema [[json-schema]] that
expresses the constraints defined in this specification. This schema is maintained at <a
href="https://www.w3.org/ns/pub-schema/manifest/"
>https://www.w3.org/ns/pub-schema/manifest/</a>.</p>
<p>The publication manifest also has several authoring flexibilities and compact authoring expressions.
For example, it is not always required that object types be explicitly authored, as these are
automatically generated during processing when missing (see <a href="#explicit-implied-objects"></a>
for more information). An <a>internal representation</a> of the manifest data is defined separately;
see <a href="#app-internal-rep-data-model"></a> for further details.</p>
<p>Consequently, a user agent does not have to be a full JSON-LD processor. User agents only need to be
able to read the manifest's specific shape and internalize the data.</p>
</section>
<section id="manifest-schemaorg" class="informative">
<h4>Relationship to Schema.org</h4>
<p>Manifest properties, in particular those categorized as <a href="#descriptive-properties">descriptive
properties</a>, are primarily drawn from <a href="https://schema.org">Schema.org</a> and its <a
href="https://schema.org/docs/schemas.html">hosted extensions</a> [[schema.org]].
Consequently, these properties inherit their syntax and semantics from Schema.org, making manifest
authoring compatible with Schema.org authoring.</p>
<p>When a manifest item corresponds to a Schema.org property, its <a href="#manifest-properties"
>property definition</a> identifies its mapping and includes the defining type (e.g., <a
href="https://schema.org/CreativeWork">CreativeWork</a> or <a href="https://schema.org/Book"
>Book</a>) in parentheses.</p>
<p>Schema.org additionally includes many properties that, though relevant for publishing, are not
mentioned in this specification. These properties can be used in a manifest as this document defines
only the minimal set of manifest items (see <a href="#extensibility-manifest-properties"></a>).</p>
<p>When using additional Schema.org properties, ensure that they are valid for the <a
href="#publication-types">type of publication</a> specified in the manifest. Properties are
often available in many Schema.org types, as a result of the inheritance model used by the
vocabulary, but not all properties are available for all types. For more detailed information about
which types accept which properties, refer to [[schema.org]].</p>
<p>More information about using additional Schema.org properties is also available in <a
href="#publication-types"></a> and <a href="#extensibility-manifest-properties"></a>.</p>
</section>
</section>
<section id="terminology">
<h3>Terminology</h3>
<p>This specification depends on the Infra Standard [[!infra]].</p>
<dl>
<dt>
<dfn>Bounds</dfn>
</dt>
<dd>
<p>A <a>digital publication</a> consists of a finite set of resources that represent its content.
This extent is known as its bounds and is defined within its manifest as described in <a
href="#publication-resources"></a>.</p>
</dd>
<dt>
<dfn data-lt="digital publications|digital publication's">Digital Publication</dfn>
</dt>
<dd>
<p>A digital publication is any publication authored in a format that uses a <a>profile</a> of the
<a>manifest</a>.</p>
</dd>
<dt>
<dfn>Internal Representation</dfn>
</dt>
<dd>
<p>The internal representation of a manifest is the data structure created by user agents when they
<a href="#manifest-processing">process the manifest</a> and remove all possible ambiguities
and incorporate any missing values that can be inferred from another source.</p>
<p>It is possible for the information expressed in the manifest to be the equivalent of the internal
representation created by user agents if there are no ambiguities or missing information.</p>
</dd>
<dt>
<dfn data-lt="Manifests">Manifest</dfn>
</dt>
<dd>
<p>A manifest represents structured information about a publication, such as informative metadata, a
<a href="#resource-list">list of resources</a>, and a <a>default reading order</a>.</p>
</dd>
<dt>
<dfn data-lt="profiles|profile(s)">Profile</dfn>
</dt>
<dd>
<p>Profiles are publication formats (e.g., audiobooks) that use the <a>manifest</a> format defined
in this specification to describe their <a>bounds</a> and content. These formats can extend the
core definition in this specification with profile-specific terms and/or new requirements.</p>
<p>Although profiles can differ in their structural and content requirements, such variances are
restricted to maintain a high degree of predictability between formats. (See <a
href="#extensions"></a>.)</p>
</dd>
</dl>
</section>
<section id="conformance">
<p>All algorithm explanations are <em>informative</em>.</p>
</section>
<section id="manifest">
<h2>Publication Manifest</h2>
<section id="manifest-requirements">
<h5>Requirements</h5>
<p>The following properties MUST be set in the manifest:</p>
<ul>
<li>
<a href="#manifest-context">
<code>context</code>
</a>
</li>
<li>
<a href="#profile-conformance">
<code>conformsTo</code>
</a>
</li>
</ul>
<p>The following properties are RECOMMENDED:</p>
<ul>
<li>
<a href="#publication-types">
<code>type</code>
</a>
</li>
<li>
<a href="#canonical-identifier">
<code>id</code>
</a>
</li>
</ul>
<p>The priority of all other <a href="#manifest-properties">properties</a> and <a href="#manifest-rel"
>resource relations</a> is OPTIONAL, but MAY be modified by implementations of the manifest
format.</p>
<p class="note">Some properties are implicitly required, as they are compiled from alternative
information when not explicitly authored. See <a href="#app-internal-rep-data-model"></a> for more
information.</p>
</section>
<section id="properties-value-categories">
<h3>Value Categories</h3>
<p>This section describes the categories of values that can be used with properties of the publication
manifest.</p>
<section id="value-literal">
<h4>Literals</h4>
<p>When a <a href="#manifest-properties">manifest</a> property expects a literal text string —
one that is not language-dependent, such as a code value or date — as its value, the value
MUST be expressed as a [[!json]] <a href="https://tools.ietf.org/html/rfc4627#section-2.5"
>string</a>.</p>
<p>Literal values are not changed <a href="#manifest-processing">during processing of the
manifest</a>, unlike other values which might be, for example, <a
href="#explicit-implied-objects">converted to objects</a>.</p>
</section>
<section id="value-number">
<h4>Numbers</h4>
<p>When a <a href="#manifest-properties">manifest</a> property expects a number as its value, the
value MUST be expressed as a [[!json]] <a href="https://tools.ietf.org/html/rfc4627#section-2.4"
>number</a>.</p>
</section>
<section id="value-boolean">
<h4>Booleans</h4>
<p>When a <a href="#manifest-properties">manifest</a> property expects a boolean as its value, the
value MUST be expressed as an [[!ecmascript]] <a
data-cite="ecmascript#sec-terms-and-definitions-boolean-value">Boolean value</a>
(<code>true</code> or <code>false</code>).</p>
</section>
<section id="explicit-implied-objects">
<h4>Explicit and Implied Objects</h4>
<p>Various manifest properties are expected to be expressed as [[!json]] <a
href="https://tools.ietf.org/html/rfc4627#section-2.2">objects</a>. Although the use of
explicit objects is usually advised, the following sections identify cases where it is also
acceptable to use string values. These strings are automatically translated into objects during
<a href="#manifest-processing">processing of the manifest</a> by a user agent (the exact
mapping of text values to objects is included in each definition).</p>
<section id="value-localizable-string">
<h5>Localizable Strings</h5>
<p>When a <a href="#manifest-properties">manifest</a> property expects a localizable text string
as its value, the value MUST be expressed as one of:</p>
<ul>
<li>a [[!json]] <a href="https://tools.ietf.org/html/rfc4627#section-2.5">string</a> value;
or</li>
<li>a <a><code>LocalizableString</code></a>.</li>
</ul>
<p>A single string value represents an implied object whose <code>value</code> property is the
string's text and whose language and base direction is determined from other information in
the manifest.</p>
<p>As localizable strings are intended to facilitate multiple language representations of a
value, properties that accept a localizable string always accept an array of these values.
For this reason, although only a single string or object has to be authored, such values are
converted to <a href="#value-array">arrays</a> for consistency of processing.</p>
<p>A <dfn data-lt="LocalizableStrings|localizable string"><code>LocalizableString</code></dfn>
is a [[!json]] <a href="https://tools.ietf.org/html/rfc4627#section-2.2">object</a>
consisting of the following properties:</p>
<table class="zebra">
<thead>
<tr>
<th>Term</th>
<th>Description</th>
<th>Required Value</th>
<th>Value Category</th>
<th>[[!schema.org]] Mapping</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>value</code>
</td>
<td>The value of the localizable string. REQUIRED.</td>
<td>Text.</td>
<td>
<a href="#value-literal">Literal</a>
</td>
<td>(None)</td>
</tr>
<tr>
<td>
<code>language</code>
</td>
<td>The language of the value. OPTIONAL.</td>
<td>A <a href="https://tools.ietf.org/html/bcp47#section-2.2.9">well-formed language
tag</a> [[!bcp47]].</td>
<td>
<a href="#value-literal">Literal</a>
</td>
<td>(None)</td>
</tr>
<tr>
<td>
<code>direction</code>
</td>
<td>The base direction of the value. OPTIONAL.</td>
<td><code>ltr</code> or <code>rtl</code></td>
<td>
<a href="#value-literal">Literal</a>
</td>
<td>(None)</td>
</tr>
</tbody>
</table>
<p>The meanings of the base direction values are:</p>
<ul>
<li><code>ltr</code>: indicates that the textual value is explicitly directionally set to
left-to-right text.</li>
<li><code>rtl</code>: indicates that the textual value is explicitly directionally set to
right-to-left text.</li>
</ul>
<p> A missing base direction value means that that the textual value is explicitly directionally
set to the direction of the first character with a strong directionality, following the
rules of the Unicode Bidirectional Algorithm [[!bidi]]. </p>
<aside class="example" title="Set the language of a string">
<pre>{
"value" : "孔子",
"language" : "zh"
}</pre>
</aside>
<aside class="example" title="Set the language and the base direction of a string">
<pre>{
"value" : "<bdo dir="ltr">HTML היא שפת סימון.</bdo>",
"language" : "he",
"direction" : "rtl"
}</pre>
</aside>
<div class="note">
<p> If the base direction value were not set in the last example, the text would be
displayed, following the Unicode Bidirectional Algorithm [[bidi]] and due to the
presence of a Latin character starting the string, as: </p>
<p dir="ltr">HTML היא שפת סימון.</p>
<p> However, that would be incorrect. The extra <code>direction</code> value is necessary to
control the display to yield: </p>
<p dir="rtl">HTML היא שפת סימון.</p>
<p>Note that the <var>value</var> field in the example represents the text as it is stored
in memory, hence the discrepancy between it and the two renderings depicted here. Text
editors might also display the JSON value differently (e.g., using the Unicode
Bidirectional Algorithm only).</p>
<p>See also the [[string-meta]] document for further explanations and examples.</p>
</div>
</section>
<section id="value-entity">
<h6>Entities</h6>
<p>When a <a href="#manifest-properties">manifest</a> property expects an entity (i.e., an
individual or organization responsible for the various aspects of creation), its value MUST
be expressed either as:</p>
<ul>
<li>a [[!json]] <a href="https://tools.ietf.org/html/rfc4627#section-2.5">string</a> value;
or</li>
<li>an <a><code>Entity</code></a>.</li>
</ul>
<p>A single string value represents an instance of an <code>Entity</code> object whose
<code>name</code> property is the string's text and whose <code>type</code> is assumed
to be <a href="https://schema.org/Person">Person</a> [[!schema.org]].</p>
<p>An <dfn data-lt="Entities">Entity</dfn> is defined as an instance of either the
[[!schema.org]] <a href="https://schema.org/Person"><code>Person</code></a> or <a
href="https://schema.org/Organization"><code>Organization</code></a> type with the
following minimal property set:</p>
<table class="zebra">
<thead>
<tr>
<th>Term</th>
<th>Description</th>
<th>Required Value</th>
<th>Value Category</th>
<th>[[!schema.org]] Mapping</th>
</tr>
</thead>
<tbody>
<tr>
<td id="entity-type">
<code>type</code>
</td>
<td>The type of entity. OPTIONAL</td>
<td>One or more Text. Sequence MUST include "<code>Person</code>" or
"<code>Organization</code>".</td>
<td>
<a href="#value-array">Array</a> of <a href="#value-literal">Literals</a>
</td>
<td>(None)</td>
</tr>
<tr>
<td id="entity-name">
<code>name</code>
</td>
<td>Name of the entity. REQUIRED.</td>
<td>One or more Text.</td>
<td>
<a href="#value-array">Array</a> of <a href="#value-localizable-string"
>Localizable Strings</a>
</td>
<td>
<a href="https://schema.org/name">
<code>name</code>
</a>
</td>
</tr>
<tr>
<td id="entity-id">
<code>id</code>
</td>
<td>A canonical identifier associated with the entity. OPTIONAL.</td>
<td>A URL record [[!url]].</td>
<td>
<a href="#value-id">Identifier</a>
</td>
<td>(None)</td>
</tr>
<tr>
<td id="entity-url">
<code>url</code>
</td>
<td>An address associated with the entity. OPTIONAL.</td>
<td>A valid URL string [[!url]].</td>
<td>
<a href="#value-url">URL</a>
</td>
<td>
<a href="https://schema.org/url">
<code>url</code>
</a>
</td>
</tr>
<tr>
<td id="entity-identifier">
<code>identifier</code>
</td>
<td>An identifier associated with the entity (e.g., ORCID). OPTIONAL.</td>
<td>One or more Text.</td>
<td>
<a href="#value-array">Array</a> of <a href="#value-literal">Literals</a>
</td>
<td>
<a href="https://schema.org/identifier">
<code>identifier</code>
</a>
</td>
</tr>
</tbody>
</table>
<p class="note">This minimal set of properties is not restrictive. Authors can include any
additional properties defined for the [[schema.org]] <a href="https://schema.org/Person"
><code>Person</code></a> or <a href="https://schema.org/Organization"
><code>Organization</code></a> types, as appropriate. User agents are similarly not
limited to interpreting only the preceding properties.</p>
<aside class="example" title="Using a string instead of a Person object.">
<p>The following author name is expressed as a string:</p>
<pre>{
…
"author" : "Edgar Allen Poe",
…
}</pre>
<p>but, in the context of <a href="#creators">creators</a>, it is equivalent to:</p>
<pre>{
…
"author" : {
"type" : "Person",
"name" : "Edgar Allen Poe"
},
…
}</pre>
<p>(See <a href="#creators"></a> for further details.)</p>
</aside>
</section>
<section id="value-linked-resource">
<h5>Linked Resources</h5>
<p>When a manifest property links to one or more resources, it MUST be expressed either as:</p>
<ol>
<li>a [[!json]] <a href="https://tools.ietf.org/html/rfc4627#section-2.5">string</a>
encoding the <a>URL</a> of the resources; or</li>
<li>an instance of a <a><code>LinkedResource</code></a>.</li>
</ol>
<p>A string value represents an implied <code>LinkedResource</code> object whose
<code>url</code> property is set to the string value.</p>
<p>A <dfn data-lt="LinkedResources|linked resources"><code>LinkedResource</code></dfn> object is
defined as follows:</p>
<table class="zebra">
<thead>
<tr>
<th>Term</th>
<th>Description</th>
<th>Required Value</th>
<th>Value Category</th>
<th>[[!schema.org]] Mapping</th>
</tr>
</thead>
<tbody>
<tr>
<td id="linkedresource-type">
<code>type</code>
</td>
<td>The type of resource. OPTIONAL</td>
<td>One or more Text. Sequence MUST include "<code>LinkedResource</code>".</td>
<td>
<a href="#value-array">Array</a> of <a href="#value-literal">Literals</a>
</td>
<td>(None)</td>
</tr>
<tr>
<td id="linkedresource-url">
<code>url</code>
</td>
<td>Location of the resource. REQUIRED.</td>
<td>A valid URL string [[!url]]. Refer to the property definitions that accept
this type for additional restrictions.</td>
<td>
<a href="#value-url">URL</a>
</td>
<td>
<a href="https://schema.org/url">
<code>url</code>
</a>
</td>
</tr>
<tr>
<td id="linkedresource-encodingformat">
<code>encodingFormat</code>
</td>
<td>Media type of the resource (e.g., <code>text/html</code>). OPTIONAL.</td>
<td>MIME Media Type [[!rfc2046]].</td>
<td>
<a href="#value-literal">Literal</a>
</td>
<td>
<a href="https://schema.org/encodingFormat">
<code>encodingFormat</code>
</a>
</td>
</tr>
<tr>
<td id="linkedresource-name">
<code>name</code>
</td>
<td>Name of the item. OPTIONAL.</td>
<td>One or more Text.</td>
<td>
<a href="#value-array">Array</a> of <a href="#value-localizable-string"
>Localizable Strings</a>
</td>
<td>
<a href="https://schema.org/name">
<code>name</code>
</a>
</td>
</tr>
<tr>
<td id="linkedresource-description">
<code>description</code>
</td>
<td>Description of the item. OPTIONAL.</td>
<td>One or more Text.</td>
<td>
<a href="#value-array">Array</a> of <a href="#value-localizable-string"
>Localizable Strings</a>
</td>
<td>
<a href="https://schema.org/description">
<code>description</code>
</a>
</td>
</tr>
<tr>
<td id="linkedresource-rel">
<code>rel</code>
</td>
<td>The relation of the resource to the publication. OPTIONAL.</td>
<td>
<p>One or more <a href="#manifest-rel">relations</a>.</p>
<p>Keywords are <a href="https://infra.spec.whatwg.org/#ascii-case-insensitive"
>ASCII case-insensitive</a> [[!infra]] and MUST be compared as such.</p>
</td>
<td>
<a href="#value-array">Array</a> of <a href="#value-literal">Literals</a>
</td>
<td>(None)</td>
</tr>
<tr>
<td id="linkedresource-integrity">
<code>integrity</code>
</td>
<td>A cryptographic hashing of the resource that allows its integrity to be
verified. OPTIONAL.</td>
<td>
<p>One or more whitespace-separated sets of <a
href="https://www.w3.org/TR/SRI/#dfn-integrity-metadata">integrity
metadata</a> [[!sri]]. The value MUST conform to the <a
href="https://www.w3.org/TR/SRI/#the-integrity-attribute">metadata
definition</a> [[!sri]].</p>
<p>Refer to [[!sri]] for the <a
href="https://www.w3.org/TR/SRI/#cryptographic-hash-functions">list of
cryptographic hashing functions</a> that user agents are expected to
support.</p>
</td>
<td>
<a href="#value-literal">Literal</a>
</td>
<td>(None)</td>
</tr>
<tr>
<td id="linkedresource-duration">
<code>duration</code>
</td>
<td>Overall duration of a time-based media resource. OPTIONAL</td>
<td>Duration value as defined by [[!iso8601-1]].</td>
<td>
<a href="#value-literal">Literal</a>
</td>
<td>
<a href="https://schema.org/duration"><code>duration</code></a> (<a
href="https://schema.org/Property">Property</a>) </td>
</tr>
<tr>
<td id="linkedresource-alternate">
<code>alternate</code>
</td>
<td>
<p>References to one or more reformulation(s) of the resource in alternative
formats, where the <code>encodingFormat</code> specifies the format of the
reformulation. OPTIONAL.</p>
</td>
<td>
<p>One or more of:</p>
<ul>
<li>a string, representing the <a>URL</a> of the resource reformulation in
an alternative format; or</li>
<li>an instance of a <code>LinkedResource</code> object</li>
</ul>
<p>A string value represents an implied <code>LinkedResource</code> object whose
<code>url</code> property is set to the string value.</p>
</td>
<td>
<a href="#value-array">Array</a> of <a href="#value-linked-resource">Linked
Resources</a>
</td>
<td>(None)</td>
</tr>
</tbody>
</table>
<p>Although user agent support for the <code>integrity</code> property is OPTIONAL, user agents
that support cryptographic hashing comparisons using this property MUST do so in accordance
with [[!sri]].</p>
<p>This specification only defines the <code>alternate</code> property for selecting from
alternative formats (i.e., based on <code>encodingFormat</code> or by inspecting URLs).
<a>Profiles</a> MAY extend this behaviour to allow selection based on other criteria.
The process for selecting an alternate is described in <a href="#app-select-alternate"
></a>.</p>
<p class="note">When defining a <code>LinkedResource</code> object, it is advised to always
specify the media type of the resource using the <code>encodingFormat</code> property. Doing
so allows user agents to more readily determine the usability of the resource.</p>
<pre class="example" title="A resource with a SHA-256 hashing of its content.">{
"type" : "LinkedResource",
"url" : "chapter1.html",
"encodingFormat" : "text/html",
"name" : "Chapter 1 - Loomings",
"integrity" : "sha256-13AE04E21177BABEDFDE721577615A638341F963731EA936BBB8C3862F57CDFC"
}</pre>
<pre class="example" title="A resource with its alternate formats.">{
"type" : "LinkedResource",
"url" : "chapter1.mp3",
"encodingFormat" : "audio/mpeg",
"name" : "Chapter 1 - Loomings",
"alternate" : [
"chapter1.html",
{
"type": "LinkedResource",
"url": "chapter1.json",
"encodingFormat": "application/vnd.syncnarr+json",
"duration": "PT1669S"
}
]
}</pre>
<pre class="example" title="Resource list that includes one link using a relative URL as a string ('datatypes.svg') and two that display the various properties of the a LinkedResource object.">{
…
"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"
}
],
…
}</pre>
</section>
<section id="value-object">
<h3>Objects</h3>
<p>When a manifest property expects a type of object not defined in this section, or by a
<a>profile</a>, it MUST be expressed as a [[!json]] <a
href="https://tools.ietf.org/html/rfc4627#section-2.2">object</a> (i.e., the property's
value will not be processed to create an object).</p>
</section>
</section>
<section id="value-url">
<h4>URLs</h4>
<p><dfn data-lt="URL">URLs</dfn> are used to identify resources associated with a <a>digital
publication</a>. When a property expects a URL value, it MUST be a <a
href="https://url.spec.whatwg.org/#absolute-url-string">valid URL
string</a> [[!url]].</p>
<p>In the case of <a href="https://url.spec.whatwg.org/#relative-url-string">relative-URL
strings</a>, these are resolved to <a
href="https://url.spec.whatwg.org/#absolute-url-string">absolute-URL strings</a> using a <a
href="https://url.spec.whatwg.org/#concept-base-url">base URL</a> [[!url]].</p>
<p>The <dfn>base URL</dfn> for relative-URL strings is determined as follows:</p>
<ul>
<li>In the case of an <a href="#manifest-embed">embedded manifest</a>, it is the <a
href="https://www.w3.org/TR/json-ld11/#inheriting-base-iri-from-html-s-base-element"
>document base URL of the embedding document</a> [[!json-ld11]].</li>
<li>In the case of a <a href="#manifest-link">linked manifest</a>, it is the URL of the manifest
resource.</li>
<li>In the case of a digital publication format that uses <a href="#manifest-other-discovery"
>another means of discovering the manifest</a>, it is defined by the format.</li>
</ul>
<p>By consequence, relative-URL strings in embedded manifests are resolved against the URL of the
document that references the manifest <em>unless</em> the document declares a base URL (i.e., in
a <a href="https://html.spec.whatwg.org/multipage/semantics.html#the-base-element"
><code><base></code> element</a> in its header).</p>
</section>
<section id="value-id">
<h4>Identifiers</h4>
<p>Identifiers are used to refer to a <a>digital publication</a> and the <a href="#value-entity"
>entities</a> responsible for its creation in a persistent and unambiguous manner. <abbr
title="Uniform Resource Locators">URLs</abbr>, <abbr title="Uniform Resource Names"
>URNs</abbr>, <abbr title="Digital Object Identifiers">DOIs</abbr>, <abbr
title="International Standard Book Numbers">ISBNs</abbr>, and <abbr
title="Persistent Uniform Resource Locators">PURLs</abbr> are all examples of persistent
identifiers frequently used in publishing.</p>
<p>Identifiers MUST be expressed as <a href="https://url.spec.whatwg.org/#concept-url">URL
records</a> [[!url]]</p>
</section>
<section id="value-array">
<h4>Arrays</h4>
<p>When a <a href="#manifest-properties">manifest property</a> allows one or more value of their
respective type (e.g., <a href="#value-literal">literal</a>, <a href="#explicit-implied-objects"
>object</a>, or <a href="#value-url">URL</a>), these values are expressed as [[!json]] <a
href="https://tools.ietf.org/html/rfc4627#section-2.3">arrays</a>. When a property value is
a single element, however, the array syntax MAY be omitted.</p>
<aside class="example" title="Using a text string instead of an array.">
<p>As a digital publication typically contains many resources, this declaration of a single
resource:</p>
<pre>{
…
"resources" : "datatypes.svg",
…
}</pre>
<p>is equivalent to the array:</p>
<pre>{
…
"resources" : ["datatypes.svg"],
…
}</pre>
</aside>
</section>
</section>
<section id="manifest-context">
<h3>Manifest Contexts</h3>
<p>A <a>manifest</a> MUST set its JSON-LD context [[!json-ld11]] with the following two components,
in the specified order:</p>
<ol>
<li>the [[!schema.org]] context: <code>https://schema.org</code></li>
<li>the <dfn>publication context</dfn>: <code>https://www.w3.org/ns/pub-context</code></li>
</ol>
<p class="note">Although Schema.org is often referenced using the <code>http</code> URI scheme, <a
href="https://schema.org/docs/faq.html#19">the vocabulary is being migrated</a> to use the
secure <code>https</code> scheme as its default. As a result, only the <code>https</code> scheme is
recognized in the publication manifest context.</p>
<pre class="example" title="Setting the context declaration.">{
"@context" : [
"https://schema.org",
"https://www.w3.org/ns/pub-context"
],
…
}</pre>
<p>The publication context document adds features to the properties defined in Schema.org (e.g., the
requirement for the <a href="https://schema.org/creator">creator</a> property to be order
preserving).</p>
<p><a>Profiles</a> of this specification MAY require additional context URLs, but such URLs MUST be
ordered after these two components.</p>
<p>The context can be extended by including additional parameters — such as the <a
href="#manifest-context">global language and direction declarations</a> — in an object
following the publication context.</p>
<pre class="example">{
"@context" : [
"https://schema.org",
"https://www.w3.org/ns/pub-context",
{
"language" : "es"
}
],
…
}</pre>
</section>
<section id="manifest-lang-dir">
<h3>Manifest Language and Direction</h3>
<p>Each <a href="#value-localizable-string">natural language property value</a> in a manifest (e.g., <a
href="#pub-title">title</a>, <a href="#creators">creators</a>) has a default natural
<dfn>language</dfn>, which is the language that it is expressed in (e.g., English, French,
Chinese). It also has a natural <dfn>base direction</dfn> in which it is written — the display
direction, either left-to-right or right-to-left.</p>
<p> The digital publication manifest provides the ability to set both these concepts <a
href="#manifest-lang-dir-global">globally</a> as well as on <a href="#manifest-lang-dir-local"
>individual items</a> to aid user agents in interpreting and presenting the metadata. </p>
<p class="note"> The ability to set the base direction is a JSON-LD 1.1 [[json-ld11]] feature.
In other words, the Publication Manifest has a dependency on that version of the JSON-LD
specification (as opposed to the earlier 1.0 [[json-ld10]] version). </p>
<section id="manifest-lang-dir-global">
<h4>Global Declarations</h4>
<p>The global language and base direction declarations for natural language manifest properties are