IIIFプレゼンテーションAPI 2.1

このドキュメントのステータス

本バージョン: 2.1.0

最新安定版: 2.1.0

旧バージョン: 2.0

編集者

Michael Appleby , Yale University
Tom Crane , Digirati
Robert Sanderson , Stanford University
Jon Stroop , Princeton University Library
Simeon Warner , Cornell University

1. はじめに

画像ベースの資源へのアクセスは、多くの研究領域、学問、文化に関する知識の伝達の基礎となります。美術品、本、新聞、手紙、手稿、地図、巻物、一枚物のコレクション(pl.)、そして、織物、実物教材、当座資料のデジタル代用物のウェブ・ベース配信において、デジタル画像は、多くの情報コンテンツの入れ物です。ボーン・デジタル画像のコレクション(pl.)も、スライドショー、画像カルーセル、ウェブ漫画などのレイアウトや表示方法を構造化するために、標準化された手法から恩恵を得ることができます。

このドキュメントは、複雑な画像ベース・オブジェクトの構造やレイアウトを標準的な方法で提供できるようにする方法を記述しています。コレクション(pl.)や提供機関にまたがるコンテンツを利用して、豊かでダイナミックな経験を実現するために情報を利用する様々なスタイルのビューアを実装できます。

オブジェクトは、一連のページ、サーフェス、その他のビューで構成することができます。例えば、絵画の単一ビュー、写真の両面、彫像の基本4面ビュー、1冊の新聞や本の多数のページなどです。プレゼンテーションAPIの主な要件は、これらのビューの順序、ビューの表示に必要な資源、何が表示されているのかをユーザが理解できるようにするために必要な記述情報を提供することです。

分散型の相互運用可能なシステムを提供するために、リンクト・データとウェブ・アーキテクチャの原則を採用しています。実装が容易なJSONベースのフォーマットを作成するために、Shared Canvasデータ・モデルとJSON-LDを利用しています。

フィードバックはiiif-discuss@googlegroups.comにお送りください。

1.1. 対象と範囲

IIIF(「トリプル・アイ・エフ」と発音)プレゼンテーションAPIの目的は、IIIF画像APIとの連携が期待できる画像ベースのオブジェクトの豊かなオンライン表示環境を、主に人間のユーザーに提示できるようにするために必要な情報を提供することです。これがこのAPIの唯一の目的であり、したがって、記述情報は、機械がセマンティックに利用できるような方法ではなく、人間が読むことを意図した方法で提供しています。特に、デジタル化オブジェクトの発見に至るようなメタデータを提供することを目指したものでは明らかにありません。

現在のこのドキュメントの範囲は次のとおりです。

特定の物理的なオブジェクトに関連付けられているデジタル画像やボーン・デジタル合成オブジェクトの表示
オブジェクトのページ、サーフェス、ビューの間のナビゲーション
オブジェクトやそのページに関連付けられているテキスト、およびその他のメディア・タイプの資源の表示 – オブジェクトに関する記述情報、個々のページに関連付けられている数値、著作権、帰属情報(attribution information)などのナビゲーションに役立つラベルが含まれる。

以下は範囲としていません。

面白いデジタル化オブジェクトの発見または選択に関しては、直接サポートしていません。しかし、別の資源を参照するための手掛かりは提供しています。
オブジェクト内の検索に関しては、このプレゼンテーションAPIではサポートしていません。しかし、これは将来のIIIF仕様でカバーする予定です。

以下の記述では、デジタル化された物理的なオブジェクトやボーン・デジタル合成オブジェクトを参照するために「オブジェクト」(または「物理的なオブジェクト」)を用いており、「資源」は、そのデジタル化またはデジタル作成プロセスの結果であるデジタル資源を示すことに注意してください。

1.2. ユースケースの動機づけ

古代の巻き物から現代の新聞まで、中世の手稿からオンライン・コミックまで、そして、大判の地図から小さな写真まで、様々な種類のデジタル化オブジェクトやデジタル合成オブジェクトがあります。それらの多くには文字が書かれており、物理的なオブジェクトの劣化や、文字や言語に関する理解不足のために読むのが困難な場合があります。これらのユースケースについては、別のドキュメントで記述しています。

全体として、ユースケースには、オブジェクトの特性を把握可能となるモデル(マニフェスト資源による)、個々のサーフェスやビューが表示される順序(シーケンス資源)、個々のサーフェスやビュー(カンバス資源)が必要です。個々のカンバスは、ビューを表示可能とするために、画像および/またはそれと関連付けられている他のコンテンツ資源(コンテンツ資源)を持つことができます。オブジェクトは、部分を持つこともできます。例えば、本は章を持つことができ、その中では、複数のページが1つの章に関連付けられているかもしれませんし(範囲資源)、1冊の本を構成するすべての文章などのページ・レベルを超えるコンテンツ資源のグループもありえます(レイヤー資源)。IIIFプレゼンテーションAPIは、これらの資源タイプとそのプロパティーで構成されています。

1.3. 用語

このドキュメントの「しなければならない(must)」、「してはならない(must not)」、「必須である/要求される(required)」、「することになる(shall)」、「することはない(shall not)」、「すべきである/する必要がある(should)」、「すべきでない/する必要がない(should not)」、「推奨される(recommended)」、「することができる/してもよい(may)」、「選択できる/任意である(optional)」というキーワードは、RFC 2119で記述されているように解釈されるべきです。

2. 資源タイプの概要

この項では、この仕様で用いる資源タイプ(または、クラス)の概要を提供します。これらについては5項でそれぞれ詳細に提示しています。

2.1. 基本的なタイプ

この仕様では、下記の主要な資源タイプを用います。

基本的な資源タイプ

Manifest(マニフェスト)

オブジェクトのデジタル表現の構造と特性に関する全般的な記述。これは、タイトルやオブジェクトまたはそれが伝える知的作業に関するその他の記述情報など、デジタル化されたコンテンツをビューアでユーザに提供するために必要な情報を伝えます。個々のマニフェストには、本、写真、彫像などの1つのオブジェクトを表示する方法が記述されます。

Sequence(順序)

オブジェクトのビューの順序。手稿のページが再製本された時や、アーカイブ用のコレクション(pl.)が並び替えられた時などの、同等に有効な複数のシーケンスがコンテンツに存在するケースをカバーするために、複数のシーケンスが認められています。

Canvas(カンバス)

ページやビューを表示する仮想的な入れ物で、それもしくはそれの部分と関連付けられているコンテンツ資源を持っています。カンバスは、コンテンツのレイアウトに枠組み(frame of reference)を提供します。カンバスという概念は、PDFやHTMLなどの標準や、PhotoshopやPowerpointなどのアプリケーションから借りたもので、空白のカンバスの表示で始まり、その上に、画像、テキスト、その他の資源が「描かれ」ます。

Content(コンテンツ)

カンバスに関連付けられている画像やテキストなどのコンテンツ資源。

2.2. 付加的なタイプ

すべての資源タイプ

Collection(コレクション)

マニフェスト(pl.)の順序付きリスト、および/または、さらに追加されたコレクション(pl.)。コレクション(pl.)によって、マニフェスト(pl.)を階層構造で容易に通知、閲覧できるようになります。自身の記述情報を用いることもできます。コレクションにより、公開機関が知っているすべてのマニフェスト(pl.)を見つける方法をクライアントに提供することもできます。

Annotation(アノテーション)

コンテンツ資源とコメントは、アノテーションにより、カンバスに関連付けられます。これは、情報を連携させるための1つの、整合性のある手段を提供し、資源部分とカンバス(pl.)部分を区別するための標準に基づくフレームワークを提供します。アノテーションは後で追加できるため、これによって、公開者が、自身のコンテンツを、他者が作成した記述と連携させることができる分散型システムが促進されます。

AnnotationList(アノテーション・リスト)

アノテーションの順序付きリスト。一般的に1つのカンバスに関連付けられます。

Layer(レイヤー)

アノテーション・リストの順序付きリスト。レイヤーにより、アノテーションをより高レベルでグルーピングして記録できます。例えば、中世フランス語ドキュメントのすべての英訳のアノテーションを、テキスト化データ(transcription)や現代フランス語版と分けておくことができます。

Range(範囲)

カンバス(pl.)の順序付きリスト、および/または、さらに追加された範囲(pl.)。範囲(pl.)によって、カンバス(pl.)またはその部分を何らかの方法でグルーピングできます。これは、本、章、節、項、内容のないページ、目次などを区別するためなどの、テキストの区別がその理由でありえます。同様に、折丁や丁合い、後で追加された部分などの物理的な特徴が重要な場合もあります。

3. 資源プロパティー

この仕様では、5つの異なる領域のプロパティーを定義しています。ほとんどのプロパティーは、上記のどの資源タイプにも関連付けることができ、複数の値を持つことができます。プロパティーは、それが関連付けられている資源と関係を有するため、マニフェスト上のdescriptionプロパティーはオブジェクトに関する記述ですが、カンバス上のdescriptionプロパティーはオブジェクトの特定ページやビューに関する記述です。

プロパティーの使用に関する要件を付録Bで要約しています。

カスタマイズ拡張またはIIIFによる承認により、他のプロパティーも認められます。クライアントが、理解できないプロパティーを発見した場合は、それを無視しなければなりません(must)。他のプロパティーは、IIIFの仕様で定義されているプロパティーと衝突しないようにするために、「prefix:name」という形式の接頭辞と名前で構成すべきです(should)。可能な限り拡張にはサービスを用いるべきで(should)、新しいプロパティーのセマンティクスを定義するJSON-LDコンテキスト・ドキュメントを追加すべきです。

3.1. 記述プロパティー

label(ラベル)

人間が読める、資源に対するラベル、名前やタイトル。このプロパティーは、ページ間の区別や表示する画像の選択などの、その資源と類似する資源とを人が区別する必要がある場合に、資源の代わりに短いテキストとして表示することを目的としています。

コレクションはラベルを少なくとも1つ持っていなければなりません(must)。
マニフェストは、オブジェクトの名前やそれが具現化している知的作業のタイトルなどのラベルを少なくとも1つ持っていなければなりません(must)。
シーケンスはラベルを1つ以上持つことができ(may)、1つのマニフェストに複数のシーケンスがある場合は、それぞれにラベルが少なくとも1つなければなりません(must)。
カンバスは、ページ番号やビューに関する短い記述などのラベルを少なくとも1つ持っていなければなりません(must)。
コンテンツ資源は、ラベルを1つ以上持つことができ(may)、同じカンバスに選択可能なコンテンツ資源がある場合は、それぞれにラベルが少なくとも1つあるべきです(should)。
範囲はラベルを少なくとも1つ持っていなければなりません(must)。
レイヤーはラベルを少なくとも1つ持っていなければなりません(must)。
その他の資源タイプはラベルを持つことができます(may)。

metadata(メタデータ)

短い記述エントリーのリストで、ユーザに示す人間が読めるラベルと値のペアとして提供されます。値は、リンクやテキストのマークアップなどのシンプルなHTMLか、プレーン・テキストであるべきで(should)、ラベルは、プレーン・テキストであるべきです(should)。この情報によって伝えられるセマンティクスはなく、クライアントは発見やその他の目的にこれを用いるべきではありません(should not)。この記述のペアのリストは、ユーザ・インターフェース上で表形式で表示できるべきです(should)。クライアントは、マニフェスト(pl.)とカンバス(pl.)に関する情報を表示する方法を持っているべきで(should)、他の資源に関する情報を表示する方法を持つことができます(may)。クライアントは、記述で示されている順序でペアを表示すべきです(should)。ペアは、ユースケースの中でも、とりわけ、作品の作者、その作成に関する情報、短い物理的な記述、所有権情報を伝えるために用いられるかもしれません。ラベルと値の表示以外に、クライアントがこの情報に対して何らかのアクションを行うことは期待されません。ラベルと値のペアの例として、「作者」というラベルと「Jehan Froissart」という値があげられます。

コレクションは、それと関連付けられているメタデータのペアを1つ以上持っているべきです(should)。
マニフェストは、オブジェクトや作業を記述した、それと関連付けられているメタデータのペアを1つ以上持っているべきです(should)。
その他の資源タイプはメタデータのペアを1つ以上持つことができます(may)。

description(記述)

シンプルなラベルや値ではなく、プロパティーが付与されるオブジェクトや資源に関する長い形式の文章記述で、フル・テキストの記述としてユーザに伝えることを意図しています。これは、シンプルなHTMLやプレーン・テキストでありえます(may)。これは、何が表示されているかを理解するために必要な追加情報とともに、metadataフィールドのあらゆる情報をコピーできます。クライアントは、マニフェスト(pl.)とカンバス(pl.)の記述を表示する方法を持っているべきで(should)、他の資源に関する情報を表示する方法を持つことができます(may)。

コレクションは記述を1つ以上持っているべきです(should)。
マニフェストは記述を1つ以上持っているべきです(should)。
その他の資源タイプは記述を1つ以上持つことができます(may)。

thumbnail(サムネイル)

標題紙、重要な画像、関連付けられている複数のコンテンツ資源を用いたカンバスの描画などの、プロパティーが付与されている資源を描いた、または、絵で表現した小さな画像。リサイズなどの操作のために、この画像にIIIF画像APIサービスを利用できることが推薦されます(recommended)。資源に複数のサムネイルがある場合は、それらはそれぞれ違うものであるべきです(should)。

コレクションはサムネイル画像を1つだけ持っているべきで(should)、2つ以上持つことができます(may)。
マニフェストはサムネイル画像を1つだけ持っているべきで(should)、2つ以上持つことができます(may)。
シーケンスはサムネイルを1つ以上持つことができ(may)、1つのマニフェストに複数のシーケンスがある場合は、サムネイルを少なくとも1つ持っているべきです(should)。
カンバスはサムネイルを1つ以上持つことができ(may)、表現を構成する画像や資源が複数ある場合は、サムネイルを少なくとも1つ持っているべきです(should)。
コンテンツ資源はサムネイルを1つ以上持つことができ(may)、それが資源選択のオプションである場合は、サムネイルを少なくとも1つ持っているべきです(should)。
その他の資源タイプはサムネイルを1つ以上持つことができます(may)。

3.2. 権利・ライセンス・プロパティー

下記のプロパティーは、表示環境に関係なく所有・公開機関の利害が伝えられることを保証します。クライアントはこれらのプロパティーを明確にユーザに提示しなければなりません(must)。クライアントのユーザ・インターフェースが多様でありえることを考えると、クライアントの初期状態において、プロパティーのすべてまたは一部をユーザに表示することが常に可能であるわけではないでしょう。最初に表示しない場合は、ボタンやスクロール・バーなどの、それを表示する方法は分かりやすいものでなければなりません(must)。

attribution(帰属)

関連付けられている資源が表示または使用される時に表示されなければならない(must)文章。例えば、これは、著作権や所有権のステートメント、または、所有機関および/または公開機関の謝意をシンプルに示すために使用できます。ユーザが希望する言語との一致を試みるべきで(should)、希望する言語が不明または利用できない場合には、クライアントは、どの値を表示するかを選択できます。同じ言語や不明な言語の値が複数ある場合は、それらの値をすべて表示しなければなりません(must)。

資源タイプは帰属ラベルを1つ以上持つことができます(may)。

license(ライセンス)

資源利用にあたってのライセンスまたは権利のステートメントが記述されている外部資源へのリンク。これが、URIであり、人間が読めるラベルではない根拠は、資源が多くてもそれらに対するライセンスは1つであるのが一般的であること、そして、テキストが長すぎてオブジェクトと一緒にユーザに表示できないということです。テキストの表示が必要な場合は、代わりに、attributionプロパティーを用いて情報を含めることをお勧めします(recommended)。

資源タイプは、それと関連付けられているライセンスを1つ以上持つことができます(may)。

logo(ロゴ)

それが付与されている資源に関連付けられている個人や組織を表す小さな画像。所有機関や提供機関のロゴでありえます。資源が表示または使用される時には、ロゴは、画像を切り取ったり、回転させたり、その他の方法で変形させたりすることなく、はっきりと表示しなければなりません(must)。リサイズなどの操作のために、この画像にIIIF画像APIサービスを利用できることが推薦されます(recommended)。

資源タイプは、それと関連付けられているロゴを1つ以上持つことができます(may)。

3.3. 技術プロパティー

@id

資源を識別するURI。すべての資源にHTTP URIを用いることをお勧めします(recommended)。様々なクラスの資源に対する推奨されるHTTP URIのパターンを下記で示しています。あらゆる登録済みスキームのURIを使用でき(may)、実装者は、"urn:uuid:uuid-goes-here-1234"という形式のUUID URNを用いると便利だと思うかもしれません。URIが不要な資源には空白ノード識別子割り当てることができ(may)、これは@idを省略するのと同じです。

コレクションはidを1つだけ持っていなければならず(must)、それは、それが公開されている場所のhttp(s) URIでなければなりません(must)。
マニフェストはidを1つだけ持っていなければならず(must)、それは、それが公開されている場所のhttp(s) URIでなければなりません(must)。
シーケンスはidを持つことができますが(may)、2つ以上持ってはなりません(must not)。
カンバスはidを1つだけ持っていなければならず(must)、それはhttp(s) URIでなければなりません(must)。そのURIでカンバスのJSON表現が公開されているべきです(should )。
コンテンツ資源は、idが応答に組み込まれていない場合は、idを1つだけ持っていなければならず(must)、それは、資源が公開されている場所のhttp(s) URIでなければなりません(must)。
範囲はidを1つだけ持っていなければならず(must)、それはhttp(s) URIでなければなりません(must)。
レイヤーはidを1つだけ持っていなければならず(must)、それはhttp(s) URIでなければなりません(must)。
アノテーション・リストはidを1つだけ持っていなければならず(must)、それは、それが公開されている場所のhttp(s) URIでなければなりません(must)。
アノテーションは1つのidを1つだけ持つべきで(should)、2つ以上持ってはならず(must not)、そのURIでアノテーションの表現が公開されているべきです(should)。

@type

資源のタイプ。この仕様で定義している資源タイプに関しては、以下の項で@typeの値を記述しています。コンテンツ資源では、タイプは他の語彙から得ることもできます。画像、テキスト、音声などの基本的なタイプに対する推薦も、以下の項で提供しています。

すべての資源タイプは、特定のタイプを少なくとも1つ持っていなければなりません(must)。

この要件は、2項で記述されているタイプにのみ当てはまります。サービス、サムネイルおよびその他の資源には独自の要件があります。

format(フォーマット)

「image/jpeg」などの、コンテンツ資源の具体的なメディア・タイプ(MIMEタイプと呼ばれることが多い)。例えば、これはXMLのテキストをプレーン・テキストと区別するために重要です。

コンテンツ資源はフォーマットを1つだけ持つことができ(may)、それは資源が逆参照された時に返されるContent-Typeヘッダーの値でなければなりません(must)。
その他の資源タイプはフォーマットを持ってはなりません(must not)。

これは、画像APIのformatsプロパティー(そのAPI内で用いる拡張子を示す)とは異なります。formatは、画像のみではなく、あらゆるコンテンツ資源にも使用できるため、このケースに用いるのは不適当でしょう。

height(高さ)

カンバスまたは画像資源の高さ。画像の場合、値はピクセルです。カンバス(pl.)の場合、値には単位はありません。幅と組み合わせて、コンテンツ資源が位置する空間の縦横比を伝えます。

カンバスは高さを1つだけ持っていなければなりません(must)。
コンテンツ資源は、必要に応じて、高さを1つだけ持つことができ(may)、ピクセルで示されます。
その他の資源タイプは高さを持ってはなりません(must not)。

width(幅)

カンバスまたは画像資源の幅。画像の場合、値はピクセルです。カンバス(pl.)の場合、値には単位はありません。高さと組み合わせて、コンテンツ資源が位置する空間の縦横比を伝えます。

カンバスは幅を1つだけ持っていなければなりません(must)。
コンテンツ資源は、必要に応じて、幅を1つだけ持つことができ(may)、ピクセルで示されます。
その他の資源タイプは幅を持ってはなりません(must not)。

viewingDirection(表示方向)

カンバス(pl.)のシーケンスがユーザに表示されるべき(should)方向。可能な値を以下の表で指定しています。

マニフェストは表示方向を1つだけ持つことができ(may)、シーケンスに独自の表示方向が指定されていなければ、それはそのシーケンスのすべてに当てはまります。
シーケンスは表示方向を1つだけ持つことができます(may)。
範囲またはレイヤーは表示方向を1つだけ持つことができます(may)。
その他の資源タイプは表示方向を持ってはなりません(must not)。

値説明

left-to-right オブジェクトは左から右に表示されます。未指定の場合のデフォルト。

right-to-left オブジェクトは右から左に表示されます。

top-to-bottom オブジェクトは上から下に表示されます。

bottom-to-top オブジェクトは下から上に表示されます。

値	説明
`left-to-right`	オブジェクトは左から右に表示されます。未指定の場合のデフォルト。
`right-to-left`	オブジェクトは右から左に表示されます。
`top-to-bottom`	オブジェクトは上から下に表示されます。
`bottom-to-top`	オブジェクトは下から上に表示されます。

viewingHint(表示用ヒント)

資源の最適な表示方法に関するクライアントへのヒント。この仕様では、下記表で指定している値を定義しています。他の値が存在している場合は、それを提供することもでき(may)、それはURIでなければなりません(must)。

資源タイプは、表示用ヒントを1つ以上持つことができます(may)。

値説明

individuals コレクション、マニフェスト、シーケンス、範囲で有効。コレクションのviewingHintとして用いる場合は、クライアントはマニフェスト(pl.)をそれぞれ、別個の個々のオブジェクトとして扱うべきです。マニフェスト、シーケンスおよび範囲では、参照されるカンバス(pl.)は、すべて別個の個々のビューであり、ページめくりインターフェースで表示すべきではありません(should not)。例には、絵画のギャラリー、3次元オブジェクトのビューの集合、またはコレクション内の写真の表面の集合が含まれます。

paged マニフェスト、シーケンス、範囲で有効。カンバス(pl.)は1冊の中のページを表します。ページめくりインターフェースが利用できる場合は、それで表示すべきです(should)。最初のカンバスは単一のビュー(最初の右ページ(recto))であり、そのため、2番目のカンバスは最初のカンバスのオブジェクトの裏面を表します。

continuous マニフェスト、シーケンス、範囲で有効。個々のカンバスは部分的なビューであり、カンバス(pl.)を個々に表示するか、すべてのカンバス(pl.)をディスプレイ上で仮想的に接合するかのどちらかが適切な描画でしょう。これが適切と思われる例には、長い巻物、巻装本、互いに隣接して表示するように設計されたオブジェクトがあげられます。このviewingHintが存在している場合は、資源には、カンバス(pl.)の配列を決定するviewingDirectionもなければなりません(must)。これによって、このviewingHintを用いて巻物の両面を同じマニフェストに含むことが認められるわけではないことに注意してください。それを達成するためには、マニフェストが「individuals」であり、「continuous」である2つの範囲(pl.)(各面に1つずつ)を持つべきです。

multi-part コレクション(pl.)でのみ有効。このヒントを持つコレクション(pl.)は、それぞれが論理的全体の一部を成している複数のマニフェスト(pl.)で構成されます。クライアントは、コレクションをサムネイルではなく目次として表示できます。例には、多巻本または複数号の雑誌またはその他の定期刊行物の集合が含まれます。

non-paged このヒントを持つカンバス(pl.)は、ページめくりインターフェースで表示してはならず(must not)、ページのシーケンスを決定する時にスキップしなければなりません(must)。現在のシーケンスやマニフェストに「paged」という表示用ヒントがない場合には、この表示用ヒントは無視しなければなりません(must)。

top 範囲でのみ有効。このviewingHintを持っている範囲は、ナビゲーションに役立つようにクライアントが表示する構造を示す範囲(pl.)の階層において最上位にあるノードです。例えば、ページ付きオブジェクト内の目次、3次元オブジェクトの主要部分、1つの巻物内のテキスト領域などがあげられます。「top」という範囲の下位に位置するその他の範囲(pl.)は、ナビゲーション構造内に表示するエントリーです。このヒントで複数の範囲(pl.)を記述できます(may)。その場合、クライアントは、ナビゲート用の構造の選択肢を複数表示すべきです(should)。

facing-pages 「paged」という表示用ヒントを持っているシーケンスまたはマニフェストにおいて、このヒントを持っているカンバス(pl.)は、それらごとに、見開きの両方の部分を描画する形で表示しなければなりません(must)。すべてのカンバス(pl.)がこのように指定されている場合は、ページめくりは不可能であるため、シンプルに「individuals」を用いてください。

値	説明
`individuals`	コレクション、マニフェスト、シーケンス、範囲で有効。コレクションのviewingHintとして用いる場合は、クライアントはマニフェスト(pl.)をそれぞれ、別個の個々のオブジェクトとして扱うべきです。マニフェスト、シーケンスおよび範囲では、参照されるカンバス(pl.)は、すべて別個の個々のビューであり、ページめくりインターフェースで表示すべきではありません(should not)。例には、絵画のギャラリー、3次元オブジェクトのビューの集合、またはコレクション内の写真の表面の集合が含まれます。
`paged`	マニフェスト、シーケンス、範囲で有効。カンバス(pl.)は1冊の中のページを表します。ページめくりインターフェースが利用できる場合は、それで表示すべきです(should)。最初のカンバスは単一のビュー(最初の右ページ(recto))であり、そのため、2番目のカンバスは最初のカンバスのオブジェクトの裏面を表します。
`continuous`	マニフェスト、シーケンス、範囲で有効。個々のカンバスは部分的なビューであり、カンバス(pl.)を個々に表示するか、すべてのカンバス(pl.)をディスプレイ上で仮想的に接合するかのどちらかが適切な描画でしょう。これが適切と思われる例には、長い巻物、巻装本、互いに隣接して表示するように設計されたオブジェクトがあげられます。この`viewingHint`が存在している場合は、資源には、カンバス(pl.)の配列を決定する`viewingDirection`もなければなりません(must)。これによって、この`viewingHint`を用いて巻物の両面を同じマニフェストに含むことが認められるわけではないことに注意してください。それを達成するためには、マニフェストが「individuals」であり、「continuous」である2つの範囲(pl.)(各面に1つずつ)を持つべきです。
`multi-part`	コレクション(pl.)でのみ有効。このヒントを持つコレクション(pl.)は、それぞれが論理的全体の一部を成している複数のマニフェスト(pl.)で構成されます。クライアントは、コレクションをサムネイルではなく目次として表示できます。例には、多巻本または複数号の雑誌またはその他の定期刊行物の集合が含まれます。
`non-paged`	このヒントを持つカンバス(pl.)は、ページめくりインターフェースで表示してはならず(must not)、ページのシーケンスを決定する時にスキップしなければなりません(must)。現在のシーケンスやマニフェストに「paged」という表示用ヒントがない場合には、この表示用ヒントは無視しなければなりません(must)。
`top`	範囲でのみ有効。この`viewingHint`を持っている範囲は、ナビゲーションに役立つようにクライアントが表示する構造を示す範囲(pl.)の階層において最上位にあるノードです。例えば、ページ付きオブジェクト内の目次、3次元オブジェクトの主要部分、1つの巻物内のテキスト領域などがあげられます。「top」という範囲の下位に位置するその他の範囲(pl.)は、ナビゲーション構造内に表示するエントリーです。このヒントで複数の範囲(pl.)を記述できます(may)。その場合、クライアントは、ナビゲート用の構造の選択肢を複数表示すべきです(should)。
`facing-pages`	「paged」という表示用ヒントを持っているシーケンスまたはマニフェストにおいて、このヒントを持っているカンバス(pl.)は、それらごとに、見開きの両方の部分を描画する形で表示しなければなりません(must)。すべてのカンバス(pl.)がこのように指定されている場合は、ページめくりは不可能であるため、シンプルに「individuals」を用いてください。

navDate(ナビゲーションの日付)

カレンダーや年表などの時間ベースのユーザ・インターフェースでユーザに資源を表示する際に、ナビゲーション目的でクライアントが使用できる日付。値は、UTCのxsd:dateTimeというリテラルでなければならず(must)、「YYYY-MM-DDThh:mm:ssZ」という形式で表されます。正確な時間が不明な場合は「00:00:00」を用いるべきです(should)。同様に、月や日が不明な場合は01であるべきです(should)。任意の資源と関連付けられているnavDateが最大1つなければなりません(must)。人が利用するための、ユーザへの直接表示を目的とした記述形式の日付の範囲(pl.)は、metadataプロパティーに含めるべきです(should)。

コレクションまたはマニフェストは、それと関連付けられているナビゲーションの日付を1つだけ持つことができます(may)。
その他の資源タイプはナビゲーションの日付を持ってはなりません(must not)。

3.4. リンク付けプロパティー

ユーザへの直接表示を目的とした外部資源へのリンクで、relatedプロパティーを持っている資源に関連付けられます。例として、資源に関する動画や学術論文、ウェブサイト、HTML記述などがあげられます。ユーザに資源を表示する時にクライアントに役立つように、関連付けられている資源のラベルとフォーマットを提供すべきです(should)。

資源タイプは、それと関連する外部資源を1つ以上持つことができます(may)。

rendering(表示)

人のユーザによる表示またはダウンロードを目的とした外部資源へのリンク。このプロパティーは、マニフェスト、コレクション、その他の資源から、公開者のウェブサイトのビューア・ページなどの、その資源に対する望ましい表示環境にリンクするために使用できます。その他の用途には、本の画像とテキストを用いたPDFやEPUBとして、または、美術品の画像を用いたスライド資料集としてマニフェストを表示することなどがあります。クライアントがユーザにオプションを提示できるように、表示する資源のラベルとフォーマットを提供しなければなりません(must)。

資源タイプは、外部の表示資源を1つ以上持つことができます(may)。

service(サービス)

画像から関連するIIIF画像APIサービスの基底URIへのリンクなどの、資源に追加機能を利用できるようにするサービスへのリンク。サービス資源は、クライアントが適切な利用方法を決定できるように、サービス記述へのprofileリンクなどの、関連する追加情報を持っているべきです(should)。サービス自体からコピーした関連情報を持つこともできます(may)。このコピーは、HTTPリクエストを追加で行う必要なくオブジェクトを表示する性能を高めるために許されています。既知のサービスに関してはサービス・プロファイルのドキュメントを参照してください。

資源タイプは、外部サービスへのリンクを1つ以上持つことができます(may)。

seeAlso(をも見よ参照)

XMLやRDF記述などの、seeAlsoプロパティーで資源をセマンティックに記述している機械可読ドキュメントへのリンク。このドキュメントは、検索・発見や推論のために、または、単に資源に関するより長い記述を提供するために使用できます。クライアントがドキュメントを適切に利用しやすいように、ドキュメントのprofileとformatのプロパティーを提供すべきです(should)。

資源タイプは、それと関連する外部の記述を1つ以上持つことができます(may)。

within(内部)

レイヤー内のアノテーション・リストなどの、現在の資源を含んでいる資源へのリンク。これによって、コレクション(pl.)への上方リンクも可能となり、デジタル化オブジェクトの閲覧を提供できるようになります。

ページの機能を持っているコレクション(pl.)やアノテーション・リストは、1つのページ付き資源内にだけ存在していなければなりません(must)。
ページの機能を持っていないコレクション(pl.)やアノテーション・リストなどの、その他の資源タイプは、1つ以上の含んでいる資源内に存在できます(may)。

startCanvas(開始カンバス)

シーケンスまたは範囲からシーケンス内に含まれているカンバスへのリンク。クライアントは、この関係性に気づくとすぐに、シーケンスまたは範囲でナビゲーションを開始する時に、指定されたカンバスに進むべきです(should)。これによって、クライアントは、空白または空のカンバス(pl.)を手動でスキップすることをユーザに要求するのではなく、面白いコンテンツが含まれている最初のカンバスで始めることができます。

シーケンスまたは範囲は、その開始カンバスとしてカンバスを1つだけ持つことができます(may)。
その他の資源タイプは開始カンバスを持ってはなりません(must not)。

contentLayer(コンテンツ・レイヤー)

範囲から、その範囲に対するコンテンツ資源のアノテーションが含まれているレイヤーへのリンク。クライアントは、範囲との相互作用中に異なるカンバスのコンテンツをユーザに表示するために、または、同じカンバス内の範囲の次の部分にジャンプするために、これを使用できます。

範囲は、そのコンテンツ・レイヤーとしてレイヤーを1つだけ持つことができます(may)。
その他の資源タイプはコンテンツ・レイヤーを持ってはなりません(must not)。

3.5. ページ付けプロパティー

first(最初)

コレクションやレイヤーなどの、ページがある資源から、それぞれ、その最初のページ資源、別のコレクション、またはアノテーション・リストへのリンク。ページ資源は、その(@idの)URIのみで参照されるべきですが(should)、それと関連付けられているより多くの情報をオブジェクトとして持つこともできます(may)。

コレクションは、その最初のページとしてコレクションを1つだけ持つことができます(may)。
レイヤーは、その最初のページとしてアノテーション・リストを1つだけ持つことができます(may)。
その他の資源タイプは最初のページを持ってはなりません(must not)。

last(最後)

ページがある資源からその最後のページ資源へのリンク。ページ資源は、その(@idの)URIのみで参照されるべきですが(should)、それと関連付けられているより多くの情報をオブジェクトとして持つこともできます(may)。

コレクションは、その最後のページとしてコレクションを1つだけ持つことができます(may)。
レイヤーは、その最後のページとしてアノテーション・リストを1つだけ持つことができます(may)。
その他の資源タイプは最後のページを持ってはなりません(must not)。

total(合計)

レイヤー内のアノテーションなどの、ページのリスト内の紙葉資源の合計。値は負でない整数でなければなりません(must)。

コレクションは合計を1つだけ持つことができ(may)、これはそのページのリストのコレクション(pl.)とマニフェスト(pl.)の合計でなければなりません(must)。
レイヤーは合計を1つだけ持つことができ(may)、これはそのページのリストのアノテーションの合計でなければなりません(must)。
その他の資源タイプは合計を持ってはなりません(must not)。

next(次)

ページ資源から、順序がその次である、次ページ資源へのリンク。資源は、その(@idの)URIのみで参照されるべきですが(should)、それと関連付けられているより多くの情報をオブジェクトとして持つこともできます(may)。

コレクションは、その次のページとしてコレクションを1つだけ持つことができます(may)。
アノテーション・リストは、その次のページとしてアノテーション・リストを1つだけ持つことができます(may)。
その他の資源タイプは次のページを持ってはなりません(must not)。

prev(前)

ページ資源から、順序がその前である、前ページ資源へのリンク。資源は、その(@idの)URIのみで参照されるべきですが(should)、それと関連付けられているより多くの情報をオブジェクトとして持つこともできます(may)。

コレクションは、その前のページとしてコレクションを1つだけ持つことができます(may)。
アノテーション・リストは、その前のページとしてアノテーション・リストを1つだけ持つことができます(may)。
その他の資源タイプは前のページを持ってはなりません(must not)。

startIndex(開始インデックス)

親のページ付き資源に対して、現在のページに最初に含まれている資源の0オリジン(0 based)のインデックス。値は負でない整数でなければなりません(must)。

コレクションはstartIndexを1つだけ持つことができ(may)、それは、そのページ付けコレクションで設定されている順序に対して最初のコレクションまたはマニフェストのインデックスでなければなりません(must)。
アノテーション・リストはstartIndexを1つだけ持つことができ(may)、それは、そのページ付けレイヤーで設定されている順序に対して最初のアノテーションのインデックスでなければなりません(must)
その他の資源タイプはstartIndexを持ってはなりません(must not)。

4. JSON-LDに関する留意点

この項は、すべてのプレゼンテーションAPIコンテンツに適用可能な機能について説明しています。ほとんどの場合、これらは、APIにおいて特定の用途を持つJSON-LD仕様の機能です。

4.1. URI表現

資源記述は高レベルな記述に組み込むべきですが(should)、応答の中でリンクされているhttp(s) URIに基づく別個のリクエストでも入手可能でありえます(may)。このURIは資源に対する@idプロパティーにあります。資源へのリンクは、関連する追加情報がない場合はURIのみで提供するか、@idプロパティーを用いたJSONオブジェクトで提供することができます(may)。HTTPで資源を検索できない場合には、他のURIスキームを使用できます(may)。下記はどちらも同じURIを提供しますが、2番目のパターンは追加情報を資源に関連付けます。

// Option A, plain string
{"seeAlso": "http://example.org/descriptions/book1.xml"}

// Option B, object with @id property
{"seeAlso": {"@id": "http://example.org/descriptions/book1.xml", "format": "text/xml"}}

4.2. プロパティーの繰り返し

APIのプロパティーの多くは繰り返すことができます(may)。これは、1つの文字列ではなく、上記のどちらかの表現を用いて値のリストを提供することで行われます。

{
  "seeAlso": [
    "http://example.org/descriptions/book1.md",
    "http://example.org/descriptions/book1.csv",
    {"@id": "http://example.org/descriptions/book1.xml", "format": "text/xml"}
  ]
}

4.3. プロパティー値の言語

言語は、プレーンな文字列ではなく、下記の@valueに加え、@languageにRFC 5646コードを記述したパターンを用いて、ユーザへの表示を目的とした文字列と関連付けることができます(may)。例えば、次のとおりです。

{"description": {"@value": "Here is a longer description of the object", "@language": "en"}}

このパターンは、label、description、attributionおよびmetadata構築子のlabelとvalueフィールドで使用できます。

RFC 5646では、ar-latnのように、ハイフンの後にテキストの文字を含めることができ、クライアントはこの可能性を知っているべきであるということに注意してください。値のみでなくラベルもこの方法で翻訳できるため、これによって、応答で記述されるユーザ・インターフェースのコンポーネントを完全に国際化することができます。下記に例を示しています。

複数の値が提供されている場合は、クライアントは、ユーザにどの値を表示するかを決定するために、以下のアルゴリズムを用いなければなりません(must)。

値に関連付けられている言語がまったくない場合は、クライアントはすべての値を表示しなければなりません(must)。
そうでない場合は、クライアントはユーザの言語プレファレンスの特定を試みるか、それが駄目なら、いくつかのデフォルトの言語プレファレンスを用いるべきです。その場合、
- いずれかの値に関連付けられている言語があれば、クライアントは、言語プレファレンスと最も一致する言語に関連付けられている値をすべて表示しなければなりません(must)。
- すべての値に関連する言語があり、どれも言語プレファレンスと一致しなければ、クライアントは言語を選択し、その言語と関連付けられている値をすべて表示しなければなりません(must)。
- 一部の値に関連する言語があるものの、どれも言語プレファレンスと一致しなければ、クライアントは、関連付けられている言語がない値をすべて表示しなければなりません(must)。

4.4. プロパティー値内のHTMLマークアップ

最小限のHTMLマークアップを、description、attribution、metadataのプロパティーに含めることができます(may)。これは、labelやその他のプロパティーに用いてはなりません(must not)。これは、マニフェストの作成者がリンクとシンプルな書式設定指示をテキスト・ブロックに追加できるようにするために含まれます。コンテンツは整形式のXMLでなければならず(must)、したがって、pやspanなどの要素で囲まれなければなりません。HTMLの文字列のどちら側にも空白があってはならず(must not)、したがって、文字列の最初の文字は「<」という文字でなければならず(must)、最後の文字列は「>」でなければなりません(must)。そして、これによって、利用用のアプリケーションは、値がHTMLなのか、それとも、これらを用いたプレーン・テキストなのかを調べることができます。HTMLではない文字列がこれと一致することを避けるために、値の末尾に空白文字を追加することをお勧めします(recommended)。

HTMLやスクリプト・インジェクション攻撃を回避するために、クライアントは下記を削除しなければなりません(must)。

script、style、object、form、inputおよび、これらと類似するタグ。
aタグのhref、imgタグのsrcとalt以外のすべての属性。
CDataセクション。
XMLコメント。
処理の指示。

クライアントは、a、b、br、i、img、p、およびspanのタグのみを許すべきです(should)。クライアントは、ありとあらゆるタグを削除することも選択でき(may)、したがって、書式が常に表示されるとは想定すべきではありません(should not)。

{"description": {"@value": "<p>Some <b>description</b></p>", "@language": "en-latn"}}

4.5. リンクト・データのコンテキストと拡張

応答の最上位資源には@contextプロパティーがなければならず(must)、それはJSON表現の最初のキー/値のペアとして出現すべきです(should)。これは、情報の解釈方法をリンクト・データ・プロセッサに伝えます。下記のIIIFプレゼンテーションAPIコンテキストは、応答ごとに1つだけ出現し、組み込み資源には含まれないようにしなければなりません(must)。例えば、マニフェスト内にシーケンスを組み込む時には、そのシーケンスに@contextフィールドがあってはなりません(must not)。

{"@context": "http://iiif.io/api/presentation/2/context.json"}

この仕様で定義していないフィールドの追加は、コンテキスト・ドキュメントを追加してRDFの述語にマッピングすべきです(should)。そのとき、囲みオブジェクトには独自の@contextプロパティーがなければならず(must)、それはそのオブジェクトの最初のキー/値のペアであるべきです(should)。これは、profileを超える情報を組み込むserviceリンクの場合には必須です(required)。これらのコンテキストによってprofileが再定義されることがあるべきではありません(should not)。最上位資源にはIIIFプレゼンテーションAPIコンテキストがなければならいため(must)、コンテキストの追加が必要な場合は、値は下記のようなURI文字列の配列になるでしょう。

{
  "@context": [
    "http://iiif.io/api/presentation/2/context.json",
    "http://example.org/extension/context.json"
  ]
}

5. 資源構造

この項では、この仕様で用いている資源タイプについて詳細に説明します。2項では、資源タイプの概要とそれらの間で許されている関係を示す数値を提供し、付録Bでは、プロパティーの要件を要約した表を提供しています。

5.1. マニフェスト

推奨されるURIのパターンは次のとおりです。

{scheme}://{host}/{prefix}/{identifier}/manifest

マニフェスト応答には、クライアントが自身を初期化し、ユーザに何かを迅速に表示し始めるために必要な情報が含まれています。マニフェスト資源には、1つのオブジェクトと、知的作業またはそのオブジェクト内で具現化されている作品が表現されています。具体的には、オブジェクトの記述、権利、リンク付け情報が含まれています。次に、ユーザに表示すべきカンバス(pl.)のシーケンスが組み込まれています。

@idの識別子は、マニフェストのJSON記述を検索するために常に逆参照できなければならず(must)、したがって、http(s) URIスキームを用いなければなりません(must)。

記述情報に加え、sequencesセクションがあり、それはJSON-LDオブジェクトのリストです。個々のオブジェクトには、作品の部分の順序を表すシーケンス(次の項で論じている)が記述されており、それぞれカンバスで表されてます。このシーケンスは、マニフェストに含まれていなければならず(must)、オプションで独自のURIで提供することもできます。その後のシーケンスは、その識別子(@id)、クラス(@type)とlabelのみで参照されなければならず(must)、したがって、ユーザがそのシーケンスを表示することを選択した場合に処理を行えるようにクライアントにより逆参照できなければなりません(must)。

目次として表示されるような、コンテンツの付加的な構造を表す1つ以上の範囲(s)を列挙するstructuresセクションもありえます(may)。

下記の例にはマニフェスト・レベルの情報のみが含まれていますが、実際の実装では、先頭のシーケンス、カンバス、コンテンツの情報を組み込まなければなりません(must)。これには、複数のエントリーを1つのフィールドに関連付ける方法と、特定のエントリーの言語を明示する方法に関する記述メタデータの例が含まれています。

{
  // Metadata about this manifest file
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/manifest",
  "@type": "sc:Manifest",

  // Descriptive metadata about the object/work
  "label": "Book 1",
  "metadata": [
    {"label": "Author", "value": "Anne Author"},
    {"label": "Published", "value": [
        {"@value": "Paris, circa 1400", "@language": "en"},
        {"@value": "Paris, environ 1400", "@language": "fr"}
      ]
    },
    {"label": "Notes", "value": ["Text of note 1", "Text of note 2"]},
    {"label": "Source",
     "value": "<span>From: <a href=\"http://example.org/db/1.html\">Some Collection</a></span>"}
  ],
  "description": "A longer description of this example book. It should give some real information.",
  "thumbnail": {
    "@id": "http://example.org/images/book1-page1/full/80,100/0/default.jpg",
    "service": {
      "@context": "http://iiif.io/api/image/2/context.json",
      "@id": "http://example.org/images/book1-page1",
      "profile": "http://iiif.io/api/image/2/level1.json"
    }
  },

  // Presentation Information
  "viewingDirection": "right-to-left",
  "viewingHint": "paged",
  "navDate": "1856-01-01T00:00:00Z",

  // Rights Information
  "license": "http://example.org/license.html",
  "attribution": "Provided by Example Organization",

  "logo": {
    "@id": "http://example.org/logos/institution1.jpg",
    "service": {
        "@context": "http://iiif.io/api/image/2/context.json",
        "@id": "http://example.org/service/inst1",
        "profile": "http://iiif.io/api/image/2/profiles/level2.json"
    }
  },

  // Links
  "related":{
    "@id": "http://example.org/videos/video-book1.mpg",
    "format": "video/mpeg"
  },
  "service": {
    "@context": "http://example.org/ns/jsonld/context.json",
    "@id": "http://example.org/service/example",
    "profile": "http://example.org/docs/example-service.html"
  },
  "seeAlso": {
    "@id": "http://example.org/library/catalog/book1.xml",
    "format": "text/xml",
    "profile": "http://example.org/profiles/bibliographic"
  },
  "rendering": {
    "@id": "http://example.org/iiif/book1.pdf",
    "label": "Download as PDF",
    "format": "application/pdf"
  },
  "within": "http://example.org/collections/books/",

  // List of sequences
  "sequences": [
      {
        "@id": "http://example.org/iiif/book1/sequence/normal",
        "@type": "sc:Sequence",
        "label": "Current Page Order"
        // sequence's page order should be included here, see below...
      }
      // Any additional sequences can be referenced here...
  ]
}

5.2. シーケンス

推奨されるURIのパターンは次のとおりです。

{scheme}://{host}/{prefix}/{identifier}/sequence/{name}

シーケンスはオブジェクトのビューの順序を伝えます。デフォルトのシーケンス(そして、一般的に唯一のシーケンス）がマニフェスト内に組み込まれていなければならず(must)、独自のURIで提供することもできます(may)。デフォルトのシーケンスは、それを識別するためのURIを持つことができます(may)。シーケンスを追加する場合は、それをマニフェスト内に組み込むのではなく、マニフェストから参照できるようにしなければならず(must)、したがって、この追加のシーケンスにはHTTP URIがなければなりません(must)。

URI構造内の{name}パラメータは、これを、物理的なオブジェクトに利用できる他のシーケンスと区別できなければなりません(must)。一般的なシーケンスのデフォルト名は「normal」(通常)や「basic」(基本)です。

シーケンスは、マニフェスト(pl.)と同じフィールドを用いて、自身の記述、権利、リンク付けのメタデータを持つことができます(may)。シーケンスにはlabelプロパティーを付与でき(may)、マニフェストからの参照が2つ以上ある場合は付与しなければなりません(must)。メタデータの後に、オブジェクト内のページ(カンバス資源で表される)を、canvasesプロパティー内の順序で列挙します。少なくとも1つのカンバスが提供されなければなりません(must)。

シーケンスは、シーケンス内に記述されているカンバス資源のURIを含んでいる、1つの値を持つstartCanvasを持つことができます(may)。これは、ユーザのためにビューアがディスプレイを初期化すべき(should)カンバスです。これがない時には、ビューアはシーケンス内の最初のカンバスを用いるべきです(should)。

上記のマニフェストの例では、シーケンスはURIで参照され、label、@type、@idという基本的な情報のみが含まれています。デフォルトのシーケンスは、下記のように、マニフェスト・ファイル内で略さずに記述すべきですが、@contextプロパティーが含まれていてはなりません(must not)。

{
  // Metadata about this sequence
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/sequence/normal",
  "@type": "sc:Sequence",
  "label": "Current Page Order",

  "viewingDirection": "left-to-right",
  "viewingHint": "paged",
  "startCanvas": "http://example.org/iiif/book1/canvas/p2",

  // The order of the canvases
  "canvases": [
    {
      "@id": "http://example.org/iiif/book1/canvas/p1",
      "@type": "sc:Canvas",
      "label": "p. 1"
      // ...
    },
    {
      "@id": "http://example.org/iiif/book1/canvas/p2",
      "@type": "sc:Canvas",
      "label": "p. 2"
      // ...
    },
    {
      "@id": "http://example.org/iiif/book1/canvas/p3",
      "@type": "sc:Canvas",
      "label": "p. 3"
      // ...
    }
  ]
}

5.3. カンバス

推奨されるURIのパターンは次のとおりです。

{scheme}://{host}/{prefix}/{identifier}/canvas/{name}

カンバスは、個々のページやビューを表し、ディスプレイを構成する様々なコンテンツ資源をレイアウトするための中心的な役割を果たします。カンバス(pl.)はURIで識別されなければならず(must)、それはHTTP(s) URIでなければなりません(must)。推奨されているURIのパターン従っている場合は、そのカンバスは、{name}パラメータによってオブジェクト内の他のすべてのカンバス(pl.)と一意に区別されなければなりません(must)。カンバスのURIには、フラグメント(#の後に文字が続く)を含むべきではありません(should not)。それによって、#xywh=という構文でカンバスのエリアのセグメントを参照できなくなるためです。

すべてのカンバスは、表示用のlabel、およびheightとwidthを整数で持っていなければなりません(must)。カンバスは、オブジェクトのある部分の1つの論理的ビューを表す縦横比を有する二次元の矩形空間であり、縦横比は高さと幅のプロパティーで示されます。これによって、空間全体ではなく、カンバスの特定部分に資源を関連付けることができます。0,0未満や、高さや幅より大きい座標などの、コンテンツをカンバスの範囲外の空間に関連付けてはなりません(must not)。

(実装時に)そのページを描写している画像が1つであれば、単純化するために、画像の大きさをカンバスの大きさとして用いることをお勧めします(recommended)。フル画像が複数ある場合は、最も大きい画像の大きさを用いるべきです。最も大きい画像の一辺の大きさが1,200ピクセル未満である場合は、カンバスの大きさはその画像の大きさの倍であるべきです(should)。例で示しているように、クライアントは、これが常に当てはまるわけではなく、カンバスで表されている空間に合わせて画像を常に拡大・縮小しなければならない(must)ことを知っていなければなりません(must)。カンバスの大きさは物理的なオブジェクトと同じ縮尺比であるべきで(should)、したがって、画像はオブジェクトのみを描写すべきです(should)。これは、画像を切り取ったり、画像のセグメントのみをカンバスと関連付けたりすることで達成できます。オブジェクトの物理的な大きさは、記述内に組み込まれていたり、HTTPリクエストを行って読み出すことにより、サービスで入手できます。

画像資源(そして、画像資源のみ)が、カンバスのimagesプロパティーに含まれます。これらは画像資源で記述しているとおり、アノテーションによってカンバスにリンクされます。テキスト化データ、動画、音声、コメントなどの、その他のコンテンツは、アノテーション・リストで記述しているとおり、otherContentプロパティーで参照される外部のアノテーション・リストで提供されます。これらのプロパティーは両方とも、エントリーが1つだけであったとしても、値はリストでなければなりません(must)。カンバスと関連付けられている追加情報がない場合もあるため、両方ともオプションです。otherContentリストのアイテムが、@idプロパティーを有するオブジェクトか文字列のどちらかでありえることに注意してください。文字列の場合は、これはアノテーション・リストのURIであり、「sc:AnnotationList」というタイプが推測されます。

シーケンス内に「paged」というviewingHintの値があり、本の表示ユーザ・インターフェースで表示する場合は、最初のカンバスは、単独で表示されるべきです(should) – これは一般的に表紙または最初の右ページ(recto)です。その後、カンバス(pl.)は複数の紙葉面を表示し、したがって、本を見開きで表示した2つのカンバス(pl.)で表されるかもしれません。シーケンス内にこの順序付けを乱すカンバス(pl.)がある場合は、それに「non-paged」という値のviewingHintプロパティーを付与しなければなりません(must)。同様に、最初のカンバスが片面(single up)でない場合は、「non-paged」と記述しなければならず(must)、そうしないと、その前に空のカンバスが追加されます。

カンバス(pl.)は自身のURIで別個のマニフェストから逆参照でき(may)、下記の表示情報が返されるべきです。この情報は、以前と同様、シーケンス内に組み込まれているべきです。

{
  // Metadata about this canvas
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/canvas/p1",
  "@type": "sc:Canvas",
  "label": "p. 1",
  "height":1000,
  "width":750,

  "images": [
    {
      "@type": "oa:Annotation"
      // Link from Image to canvas should be included here, as below
    }
  ],
  "otherContent": [
    {
      // Reference to list of other Content resources, _not included directly_
      "@id": "http://example.org/iiif/book1/list/p1",
      "@type": "sc:AnnotationList"
    }
  ]

}

5.4. 画像資源

推奨されるURIのパターンは次のとおりです。

{scheme}://{host}/{prefix}/{identifier}/annotation/{name}

画像とその個々のカンバス(pl.)との関連付けはアノテーションによって行われます。通常、アノテーションは、アノテーションのテキストに関する物にコメントを関連付けるために用いられますが、オープン・アノテーションモデルは、あらゆる資源を他のあらゆる資源やその一部に関連付けることを可能にし、コメントとカンバス上の描画資源の両方に再利用されます。

アノテーションは、独自のURIを持つことができ(may)、JSONオブジェクトに@idプロパティーを追加することにより伝えられますが、その場合には、HTTP URIであるべきです(should)。URIが逆参照された時には、アノテーションのコンテンツが返されるべきです(should)。アノテーションは、別個のアノテーション・リスト、シーケンスおよびマニフェスト(pl.)から逆参照でき(may)、一部のシステムはこれを行うことができ、可能であれば、推奨されているパターンを用いて識別子を付与すべきです。

画像の個々の関連にはmotivationフィールドがなければならず(must)、その値は「sc:painting」でなければなりません(must)。これは、それをカンバスに関するコメントのアノテーションと区別するためであり、下記で詳細に説明しています。画像であるかどうかに関わらず、表現の一部として表示される資源にはすべて「sc:painting」というmotivationが付与されることに注意してください。例えば、あるページ内の文のテキスト化データは、それがオブジェクトを表現したものであるため、「painting」と見なされますが、そのページに関するコメントはそうではありません。

画像自身はアノテーションのresourceプロパティーでリンクされます。画像には@idフィールドがなければならず(must)、その値は画像を取得できるURIです。画像にIIIF画像サービスを利用できる場合は、URLは、http://example.org/image1/full/1000,/0/default.jpgなどの、特定サイズの画像コンテンツに対する完全なURLとなりえます(may)。これは「dctypes:Image」という@typeを持っているべきです(should)。そのメディア・タイプはformatで記述でき(may)、高さと幅は、それぞれheightとwidthに対し整数の値で付与できます(may)。

画像にIIIF画像APIサービスを利用できる場合は、サービスの基底URIへのリンクが含まれているべきです(should)。基底URIは識別子までの範囲のURIですが、末尾のスラッシュやその後のパラメータは含まれません。画像APIコンテキスト・ドキュメントへの参照が含まれていなければならず(must)、サービスの準拠レベル・プロファイルが含まれているべきです(should)。画像情報ドキュメントから追加したフィールドは、別個にダウンロードする必要性を避けるために、このJSONオブジェクトに含めることができます(may)。詳細については、外部サービスの利用に関する付録を参照してください。

冗長に見えますが、カンバスのURIはアノテーションのonフィールドで繰り返さなければなりません(must)。これは資源の一部のみをターゲットとしたアノテーションとの整合性を確保するためであり、下記で詳細を説明しています。

カンバスやコンテンツ資源のセグメントを選択したり、アノテーション内にコメントやテキスト化データを組み込んだりするなどの、オープン・アノテーションデータモデルの追加機能も使用できます(may)。これらの追加機能については次の項で説明しています。高度な機能を用いると、資源が画像ではなく、SpecificResource(特定資源)、Choice(選択)やその他の、コンテンツではない資源になるような状況になりえます。実装では、資源のタイプを確認すべきであり、それが常に画像であると想定すべきではありません。

画像または画像の部分を関連付けるアノテーションのみがimagesプロパティーのカンバスに含まれています。その他のアノテーション(カンバス上の資源を描画するアノテーションと、カンバスに関するコメントを行うアノテーションの両方を含む)は、アノテーション・リストを参照することで含まれます。これについては下記の項で論じています。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/p0001-image",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource": {
    "@id": "http://example.org/iiif/book1/res/page1.jpg",
    "@type": "dctypes:Image",
    "format": "image/jpeg",
    "service": {
      "@context": "http://iiif.io/api/image/2/context.json",
      "@id": "http://example.org/images/book1-page1",
      "profile": "http://iiif.io/api/image/2/profiles/level2.json"
    },
    "height":2000,
    "width":1500
  },
  "on": "http://example.org/iiif/book1/canvas/p1"
}

5.5. アノテーション・リスト

推奨されるURIのパターンは次のとおりです。

{scheme}://{host}/{prefix}/{identifier}/list/{name}

一部のオブジェクトでは、ページの表示に、画像のみではなくそれ以外のものも利用できます。他の資源には、オブジェクトのフル・テキスト、楽譜、演奏、図形転写、コメントのアノテーション、タグ、動画、データなどが含まれるかもしれません。これらの追加資源は、アノテーション・リストに含められ、それらが関連付けられているカンバスから参照されます。

アノテーション・リストは、遭遇した時に逆参照すべき(should)別個の資源です。それはアノテーションのコレクション(pl.)であり、個々のアノテーションはカンバスやその一部をターゲットとしています。マニフェスト表現との分離は、クライアントがユーザに画像を迅速に表示し、その後、ユーザが特定のカンバスに進んだ時に、ディスプレイにコンテンツとコメントを追加できるようにすることを目的としています。これにより、マニフェストは静的でより容易にキャッシュ可能でありながら、アノテーション・リストは動的に生成できるようになります。

URIのパターンの{name}パラメータは、他のすべてのリストとは一意に区別しなければならず(must)、一般的にカンバスと同じ名前です。1つのカンバスは追加資源のリストを複数持つことができるため、おそらくタイプで分けられていますが、これを前提としてはならず(must not)、そのURIは演繹的に(a priori)構築するのではなく、辿らなければなりません。

アノテーション・リストには、@idで付与されているhttp(s) URIがなければならず(must)、そのURIを逆参照すると、JSON表現が返されなければなりません(must)。これはこの仕様で定義している他のあらゆるフィールドを持つことができます(may)。

上記のとおり、アノテーションはresourcesリストで提供されます。アノテーションでリンクされている資源は画像以外のものでなければならず(must)、動機がsc:paintingである場合は、これはカンバスのimagesプロパティーに記録されます。上記のとおり、カンバスURIはonフィールドで繰り返さなければなりません(must)。

資源のフォーマットが記述されているべきであり(should)、それは資源が逆参照された時に返されるメディア・タイプでなければなりません(must)。コンテンツ資源のタイプは、このオープン・アノテーション仕様のリストまたはそれに似たよく知られている資源タイプ・オントロジーから取得すべきです(should)。描画の一部として表示される資源(画像、テキスト化データ、写本を基にした演奏などの)の場合、動機は「sc:painting」でなければなりません(must)。コンテンツ資源は、一般的にlabel、description、metadata、license、attributionなどの、この仕様で定義しているその他のフィールドをどれでも持つことができます(may)。

マニフェスト内にアノテーション・リストが組み込まれていなければならない(must not)ことに十分注意してください。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/list/p1",
  "@type": "sc:AnnotationList",

  "resources": [
    {
      "@type": "oa:Annotation",
      "motivation": "sc:painting",
      "resource":{
        "@id": "http://example.org/iiif/book1/res/music.mp3",
        "@type": "dctypes:Sound",
        "format": "audio/mpeg"
      },
      "on": "http://example.org/iiif/book1/canvas/p1"
    },
    {
      "@type": "oa:Annotation",
      "motivation": "sc:painting",
      "resource":{
        "@id": "http://example.org/iiif/book1/res/tei-text-p1.xml",
        "@type": "dctypes:Text",
        "format": "application/tei+xml"
      },
      "on": "http://example.org/iiif/book1/canvas/p1"
    }
    // ... and so on
  ]
}

5.6. 範囲

推奨されるURIのパターンは次のとおりです。

{scheme}://{host}/{prefix}/{identifier}/range/{name}

複数ページにまたがる新聞記事、作品冒頭の内容のないページの範囲、本の中の章などの、オブジェクト内の付加的な構造を記述することが重要でありえます。これらは、シーケンスと同じような方法で範囲(pl.)を用いて記述します。範囲(pl.)はURIを持っていなければならず(must)、それはhttp(s) URIであるべきです(should)。マニフェストに範囲を追加する目的は、ユーザが、単に現在のシーケンスを1つずつ実行せずに、オブジェクト内を移動できるようにするために、クライアントが構造化された階層を表示できるようにすることです。シーケンスと範囲(pl.)を分離する根拠は、本の物理構造と作品の文章構造などの、異なる範囲(pl.)には重複がありえるということです。例は、新聞記事が別の欄で継続されている場合や、単にページの途中から欄が始まる場合などでしょう。

範囲(pl.)はマニフェスト内のstructuresフィールドでリンクまたは組み込まれています。それは、範囲が1つのみであったとしても、オブジェクトのフラットなリストです。

範囲(pl.)には、メンバーシップを表現するための3つのリスト・ベースのプロパティーがあります。

ranges

現在の範囲の中にある範囲(pl.)への参照。含まれている範囲はそれぞれ、範囲のURIが含まれている文字列で参照されなければなりません(must)。

canvases

現在の範囲の中にある、カンバス(pl.)、または、カンバスの矩形部分への参照。含まれているカンバスはそれぞれ、カンバスのURIが含まれている文字列で参照されなければなりません(must)。

members

範囲(pl.)とカンバス(pl.)との組合せリスト。範囲に他の範囲(pl.)とカンバス(pl.)の両方が含まれていて、異なるタイプの資源の順序が重要な場合は、範囲には、membersプロパティーを用いるべきです(should)。プロパティーの値は、カンバス(pl.)、カンバス(pl.)の部分、または、他の範囲(pl.)の配列です。配列の個々のアイテムはオブジェクトでなければならず(must)、それには@id、@type、およびlabelのプロパティーがなければなりません(must)。

範囲には、一般的に1つ以上のカンバス(pl.)または、シーケンスとは異なり、カンバス(pl.)の部分が含まれています。部分は矩形でなければならず、xywh=というフラグメントを用いて付与されます。これによって、例えば、1つの記事が掲載されている新聞の2つのページ内の領域を選択することが可能になります。

様々な範囲(pl.)の表を表示してユーザが選択できるようにするためには、すべての範囲にラベルがなければならず(must)、表の最上部にある範囲は「top」という値のviewingHintを持っているべきです(should)。階層の一番上にある範囲は、シーケンス内のカンバス(pl.)をすべて列挙する必要はなく、その下の範囲(pl.)のリストのみを示すべきです(should)。範囲(pl.)は、それがcanvasesまたはmembersに列挙されている最初のものでない場合は、範囲内の開始すべき最初のカンバスを指示するstartCanvas関係など、この仕様で定義している他のあらゆるプロパティーを持つことができます(may)。

次の項で説明しているとおり、範囲(pl.)は、contentLayerというリンク付けプロパティーを用いた範囲のコンテンツを有するレイヤーにもリンクできます(may)。参照されているレイヤーには、1つ以上のアノテーション・リストが含まれており(それぞれのリストには範囲内のカンバス(pl.)内の領域をターゲットとしたアノテーションが含まれている)、コンテンツ資源が提供されます。これによって、例えば、複数のページに分かれている1件の新聞記事を示している範囲を、その記事のテキストにリンクすることができます。表示用のクライアントは、どのカンバスが表示されているかに関わらず、記事のテキストをすべて表示するためにこれを利用するかもしれません。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/manifest",
  "@type": "sc:Manifest",
  // Metadata here ...

  "sequences": [
    // Sequences here ...
  ],

  "structures": [
    {
      "@id": "http://example.org/iiif/book1/range/r0",
      "@type": "sc:Range",
      "label": "Table of Contents",
      "viewingHint": "top",
      "members": [
        {
          "@id": "http://example.org/iiif/book1/canvas/cover",
          "@type": "sc:Canvas",
          "label": "Front Cover"
        },
        {
          "@id": "http://example.org/iiif/book1/range/r1",
          "@type": "sc:Range",
          "label": "Introduction",
          "contentLayer": "http://example.org/iiif/book1/layer/introTexts"
        },
        {
          "@id": "http://example.org/iiif/book1/canvas/backCover",
          "@type": "sc:Canvas",
          "label": "Back Cover"
        }
      ]
    },
    {
      "@id": "http://example.org/iiif/book1/range/r1",
      "@type": "sc:Range",
      "label": "Introduction",
      "ranges": ["http://example.org/iiif/book1/range/r1-1"],
      "canvases": [
        "http://example.org/iiif/book1/canvas/p1",
        "http://example.org/iiif/book1/canvas/p2",
        "http://example.org/iiif/book1/canvas/p3#xywh=0,0,750,300"
      ]
    },
    {
      "@id": "http://example.org/iiif/book1/range/r1-1",
      "@type": "sc:Range",
      "label": "Objectives and Scope",
      "canvases": ["http://example.org/iiif/book1/canvas/p2#xywh=0,0,500,500"]
    }
  ]
}

非推奨に関する注意
1つのmembersプロパティーの方が望ましいと考え、canvasesとrangesのプロパティーはバージョン3.0で削除する可能性があります。その時までは、クライアントがmembersプロパティーを見かけた場合は、canvasesおよび/またはrangesがあったとしても、このプロパティーを用いるべきです。しかし、公開用システムは、プレゼンテーションAPIバージョン2.0準拠クライアントが、membersを用いていて、canvasesとrangesを用いたフォールバックを提供していない場合は、予期する結果は得られないだろうということを知っているべきです。公開用システムは、カンバス(pl.)と範囲(pl.)の両方が含まれている1つの順序付きリストを持つことが重要な時にのみ、membersを用いるべきです。この非推奨に関するフィードバックを募集しています。

5.7. レイヤー

推奨されるURIのパターンは次のとおりです。

{scheme}://{host}/{prefix}/{identifier}/layer/{name}

レイヤーは、対象とするカンバスを問わず、ある本の特定の文章の翻訳を構成するすべてのアノテーションなどの、一緒にまとめるべきアノテーション・リストのグルーピングを表します。レイヤー構文がないと、カンバス(pl.)にまたがったどのアノテーションでグループを構成するかを決定することができません。これにより、クライアントは、ユーザの好みに従って、レイヤーのすべてのアノテーションを表示/非表示できるユーザ・インターフェースを提供できます。

レイヤーにはURIがなくてはならず(must)、それはHTTP URIであるべきです(should)。それにはlabelがなければならず(must)、その他の記述、リンク付け、または権利のプロパティーを持つことができます(may)。

個々のアノテーション・リストは1つ以上のレイヤーの部分となることができます(may)。アノテーション・リストがレイヤーの一部である場合は、アノテーション・リストの応答でwithin関係を用いてこれを記述しなければなりません(must)。また、マニフェストの応答のアノテーション・リストへの参照に含めることもできます(may)。マニフェストの応答では、レイヤーの記述は、最初に使用した後に削除でき(may)、URIのみが文字列で提供されます。クライアントは、そのURIに基づいて、提供されている最初の記述を参照すべきです。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/list/l1",
  "@type": "sc:AnnotationList",
  "within": {
    "@id": "http://example.org/iiif/book1/layer/transcription",
    "@type": "sc:Layer",
    "label": "Diplomatic Transcription"
  }
}

レイヤーにHTTP URIがある場合には、逆参照できます(may)。表現が利用できる場合には、この仕様のJSON表現のすべての要件に従わなければなりません(must)。レイヤーのすべてのプロパティーが表現に含まれているべきです(should)。

アノテーション・リストは、otherContent配列のレイヤーから、リストがカンバスから参照されるのと同じ方法で参照されます。アノテーション・リストはURIでのみ提供されるべきですが(should)、Canvasの例のように、リストに関するより多くの情報を持つオブジェクトであることもできます(may)。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/layer/transcription",
  "@type": "sc:Layer",
  "label": "Diplomatic Transcription",
  // Other properties here ...

  "otherContent": [
    "http://example.org/iiif/book1/list/l1",
    "http://example.org/iiif/book1/list/l2",
    "http://example.org/iiif/book1/list/l3",
    "http://example.org/iiif/book1/list/l4"
    // More AnnotationLists here ...
  ]
}

5.8. コレクション

推奨されるURIのパターンは次のとおりです。

{scheme}://{host}/{prefix}/collection/{name}

コレクション(pl.)は、表示に利用できるマニフェスト(pl.)を列挙し、物理的なオブジェクトが含まれている構造、階層、または精選されたコレクション(pl.)を記述するために用いられます。コレクション(pl.)には、ツリーのリーフ・ノード(leaf nodes)においてマニフェスト(pl.)を用いてオブジェクトの階層を形成するために、他のコレクション(pl.)とマニフェスト(pl.)の両方を含めることができます(may)。コレクションのオブジェクトは、主により大きなものを扱いやすい要素に細分化するためにコレクションを用いる場合などに、他のコレクションのオブジェクト内にインラインで組み込むことができますが(may)、コレクション(pl.)内にマニフェスト(pl.)を組み込んではなりません(must not)。組み込まれたコレクションには、記述を利用できる独自のURIもあるべきです(should)。

URIのパターンは、他の資源タイプと同じ構造に従いますが、これによって、「collection」という識別子を持つマニフェストやオブジェクトの存在が妨げられることに注意してください。階層内のリンクを辿ることで他のすべてのコレクション(pl.)を発見できる最上位のコレクション(それが存在してる場合には)をtopと名付けることも推奨されています(recommended)。

マニフェスト(pl.)やコレクション(pl.)は、複数のコレクション内に出現可能です(may)。例えば、ある機関は、現代作品用に1つ、歴史的作品用に1つ、新聞用に1つ、本用に1つの4つのコレクション(pl.)を定義するかもしれません。この時、現代の新聞のマニフェストは、現代のコレクションと新聞のコレクションの両方に出現するでしょう。または、その機関は、2つの別個の新聞コレクション(pl.)を持ち、それぞれを現代と歴史のコレクションのサブコレクションとして参照することも選択できます。

意図されるコレクション(pl.)の用途は、クライアントが以下を行えるようにすることです。

初期設定時に、定義済みマニフェスト(pl.)を読み込むこと。
検索結果などの、表示用のマニフェスト(pl.)を受け取ること。
関連するマニフェスト(pl.)のリストまたは階層を可視化すること。
利用できるマニフェスト(pl.)のリストや階層によるナビゲーションを提供すること。

そのため、コレクション(pl.)にはラベルがなければならず(must)、ユーザが相互作用を行っている構造を理解できるように、クライアントが表示すべきmetadataとdescriptionのプロパティーが含まれているべきです(should)。コレクションにこれらのプロパティーがない場合は、クライアントはコレクションをユーザに直接表示する必要はありません。

コレクション(pl.)には、メンバーシップを表現するためのリスト・ベースのプロパティーが3つあります。

collections

現在のコレクションのサブコレクション(pl.)への参照。参照されるコレクションには、それぞれ適切な@id、@typeおよびラベルがなければならず(must)、全体を組み込むこともできます(may)。

manifests

参照されるマニフェスト(pl.)には、それぞれ適切な@id、@typeおよびラベルがなければなりません(must)。

members

コレクションの順序が重要な場合は、コレクション資源とマニフェストを交互配置させる(interleave)ためにmembersを使用できます。これは、本のコレクションに単巻作品と多巻作品が含まれている場合(つまり、viewingHintが「multi-part」であるコレクション(pl.))や、元の順序が重要なアーカイブ資料をモデル化する時に特に有用です。membersリスト内の個々のエントリーはオブジェクトでなくてはならず(must)、@id、@typeおよびlabelが含まれていなければなりません(must)。エントリーがコレクションである場合は、viewingHintもなければなりません(must)。

collections、manifests、membersのうちの少なくとも1つが応答に存在しているべきです(should)。メンバー資源がない、空のコレクションは許されますがお勧めしません。

コレクション・ドキュメントの例

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/collection/top",
  "@type": "sc:Collection",
  "label": "Top Level Collection for Example Organization",
  "viewingHint": "top",
  "description": "Description of Collection",
  "attribution": "Provided by Example Organization",

  "collections": [
    {
      "@id": "http://example.org/iiif/collection/sub1",
      "@type": "sc:Collection",
      "label": "Sub-Collection 1",

      "members": [  
        {
          "@id": "http://example.org/iiif/collection/part1",
          "@type": "sc:Collection",
          "label": "My Multi-volume Set",
          "viewingHint": "multi-part"
        },
        {
          "@id": "http://example.org/iiif/book1/manifest1",
          "@type": "sc:Manifest",
          "label": "My Book"
        },
        {
          "@id": "http://example.org/iiif/collection/part2",
          "@type": "sc:Collection",
          "label": "My Sub Collection",
          "viewingHint": "individuals"
        }
      ]
    },
    {
      "@id": "http://example.org/iiif/collection/part2",
      "@type": "sc:Collection",
      "label": "Sub Collection 2"
    }
  ],

  "manifests": [
    {
      "@id": "http://example.org/iiif/book1/manifest",
      "@type": "sc:Manifest",
      "label": "Book 1"
    }
  ]
}

非推奨に関する注意
1つのmembersプロパティーの方が望ましいと考え、collectionsとmanifestsのプロパティーはバージョン3.0で削除する可能性があります。その時までは、クライアントがmembersプロパティーを見かけた場合は、collectionsおよび/またはmanifestsがあったとしても、このプロパティーを用いるべきです。しかし、公開用システムは、プレゼンテーションAPIバージョン2.0準拠クライアントが、membersを用いていて、collectionsとmanifestsを用いたフォールバックを提供していない場合は、予期する結果は得られないだろうということを知っているべきです。公開用システムは、コレクション(pl.)とマニフェスト(pl.)の両方が含まれている1つの順序付きリストを持つことが重要な時にのみ、membersを用いるべきです。この非推奨に関するフィードバックを募集しています。

5.9. ページ付け

場合によっては、コレクション内のアノテーション・リストやマニフェスト(pl.)のリストが非常に長かったり、作成コストが高かったりすることがありえます。応答が動的に生成される時には、後者のケースが発生する可能性は特に高い可能性があります。このような場合には、サーバーはページ付けプロパティーを用いて応答を分割できます。応答の長さはサーバーの裁量に委ねられますが、サーバーは、クライアントが処理するのが難しいような過度に長い応答を作成しないように注意すべきです。

応答を複数のページに分割する場合には、ページ付き資源はfirstページ資源にリンクされていなければならず(must)、類似するリスト・プロパティー(コレクションにcollections、レイヤーにotherContent)が含まれていてはなりません(must not)。例えば、ページ付きレイヤーは、その最初のページとしてアノテーション・リストにのみリンクされます。資源は、最後のページが分かっている場合には、そのページにもリンクすることができます(may)。

リンクされているページ資源は、withinを用いて、含んでいるページ付き資源を逆参照されるべきです(should)。それに続くページ資源(次ページ)がある場合は、それに対するnextリンクがなければなりません(must)。それに先行するページ資源がある場合は、それに対するprevリンクがあるべきです(should)。

ページ付き資源は、そのページ群に含まれている紙葉資源の合計を記述するために、totalプロパティーを使用できます(may)。これは、レイヤー内のアノテーションの合計またはコレクション内のマニフェスト(pl.)の合計でしょう。逆に、ページ資源は、含んでいるページ付き資源に対して0から数えた、ページ内の最初の資源のインデックスにstartIndexプロパティーを含めることができます(may)。

リンクされているページ資源は、様々な権利や記述のプロパティーなどの、ページ付き資源内の様々なプロパティーを持つことができます(may)。クライアントは、表示用のlogoやattributionなどの、これらのプロパティーから派生するあらゆる要件を考慮しなければなりません(must)。

ページ付きレイヤーの例

50万近くのアノテーションを持つ長いテキスト化データを表すレイヤーで、個々のアノテーションがカンバス上の一語を表していると思われる例は次のとおりです。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/layer/transcription",
  "@type": "sc:Layer",
  "label": "Example Long Transcription",

  "total": 496923,
  "first": "http://example.org/iiif/book1/list/l1"
}

そして、対応する最初のアノテーション・リストは次のとおりです。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/list/l1",
  "@type": "sc:AnnotationList",

  "startIndex": 0,
  "within": "http://example.org/iiif/book1/layer/transcription",
  "next": "http://example.org/iiif/book1/list/l2",

  "resources": [
    // Annotations live here ...
  ]
}

なおもカンバス(pl.)からアノテーション・リストに直接リンクされていると予想されることに注意してください。例えば、特定のカンバスはレイヤー内の最初の2つのアノテーション・リストを参照しているかもしれません。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/canvas/c1",
  "@type": "sc:Canvas",

  "height": 1000,
  "width": 1000,
  "label": "Page 1",

  "otherContent": [
    "http://example.org/iiif/book1/list/l1",
    "http://example.org/iiif/book1/list/l2"
  ]
}

ページ付きコレクションの例

約930万のオブジェクトを持つ大きなコレクションの例は次のとおりです。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/collection/top",
  "@type": "sc:Collection",
  "label": "Example Big Collection",

  "total": 9316290,
  "first": "http://example.org/iiif/collection/c1"
}

そして、対応するマニフェスト(pl.)の最初のページは次のとおりです。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/collection/c1",
  "@type": "sc:Collection",

  "within": "http://example.org/iiif/collection/top",
  "startIndex": 0,
  "next": "http://example.org/iiif/collection/c2",

  "manifests": [
    // Manifests live here ...
  ]
}

6. 高度な関連付け機能

以下の項では、IIIFプレゼンテーションAPIを用いてオブジェクトの表現を構築するための既知のユースケースを記述しており、クライアントは、それらに遭遇することを予期すべきです(should)。他にもユースケースが存在している可能性があり、それらは、必要な追加フィールドに対するオープン・アノテーションのコンテキスト・ドキュメント・マッピングを用いてエンコードしなければなりません(must)。

6.1. セグメント

資源の一部またはセグメントを抽出できることは重要です。特に非常に一般的な要件は、資源をカンバスの一部と関連付けたり、画像の一部をカンバス全体またはその一部と関連付けたりすることです。次に、テキスト化データはXMLファイルで提供されることが多いため、カンバスと関連付けるために適切なページを抽出することや、カンバスの一部と関連付けるために行を抽出することは、既存の素材の再利用にとって等しく有用です。簡単なケースでは、これらは、URIフラグメントで達成できます。

画像とカンバスのセグメントが両方ともある場合、縦横比は同じであるべきですが(should)、違う場合もありえる(may)ことに注意してください。その場合には、エージェントは、画像のセグメントを、カンバスで提供されている大きさに合わせて拡大・縮小すべきです(should)。

静止画像とカンバス(pl.)のセグメントは、どちらもURIの後に矩形のバウンディング・ボックスを追加することで選択できます。下記の例のように、フラグメントは#xywh=という形式を取らなければならず(must)、4つの数値は、画像またはカンバスのバウンディング・ボックスの左上隅のx yの座標と、その後に幅と高さが続きます。したがって、上記のセグメントは、幅が300ピクセル、高さが50ピクセルであり、100,100という位置で始まります。この構文では整数のみが許されており、そのため、小さいカンバス(pl.)の指定の正確さには限界がありえることに注意してください。

http://www.example.com/iiif/book1/canvas/p1#xywh=100,100,300,50

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    // Crop out scanning bed
    "@id": "http://example.org/iiif/book1/res/page1.jpg#xywh=40,50,1200,1800",
    "@type": "dctypes:Image",
    "format": "image/jpeg"
  },
  // canvas size is 1200x1800
  "on": "http://example.org/iiif/book1/canvas/p1"
}

IIIF画像APIサービスを用いた画像資源では、上記のように、フラグメントではなく、画像APIパラメータを用いることをお勧めします(recommended)。下記の構造によって、シンプルなクライアントが画像を直接(セグメント付きURL)利用できるようになり、IIIF画像APIを実装しているクライアントは、APIを用いて適切なURIを構築するために必要な情報を得ることができるようになります。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource": {
    "@id": "http://www.example.org/iiif/book1-page1/50,50,1250,1850/full/0/default.jpg",
    "@type": "oa:SpecificResource",
    "full": {
      "@id": "http://example.org/iiif/book1-page1/full/full/0/default.jpg",
      "@type": "dctypes:Image",
      "service": {
        "@context": "http://iiif.io/api/image/2/context.json",
        "@id": "http://example.org/iiif/book1-page1",
        "profile": "http://iiif.io/api/image/2/level2.json"
      }
    },
    "selector": {
      "@context": "http://iiif.io/api/annex/openannotation/context.json",
      "@type": "iiif:ImageApiSelector",
      "region": "50,50,1250,1850"
    }
  },
  "on": "http://www.example.org/iiif/book1/canvas/p1#xywh=0,0,600,900"      
}

XMLファイルのセグメントはXPathsで抽出できます。フラグメントは次のとおりに構造化しなければなりません(must)。

http://www.example.com/iiif/book1/res/tei.xml#xpointer(/xpath/to/element)

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    "@id": "http://example.org/iiif/book1/res/tei.xml#xpointer(//line[1])",
    "@type": "dctypes:Text",
    "format": "application/tei+xml"
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=100,100,500,300"
}

6.2. 組み込みコンテンツ

外部のテキスト化データを参照するのではなく、アノテーション自身にそれを記述する方が簡単なことがよくあります。同様に、テキスト・ベースのコメントを、コメントをカンバスに関連付けているアノテーションに含めることも有益かもしれません。

コンテンツは、参照するのではなく、下記のパターンを用いてアノテーション・ブロック内に組み込むことができます(may)。

{"resource": {"@type": "cnt:ContextAsText", "chars": "text here"}}

メディア・タイプはformatフィールドで提供されるべきで(should)、あらゆるメディア・タイプが可能ですが、互換性を最大限に高めるために、text/plainまたはtext/htmlを用いることをお勧めします(recommended)。

コンテンツの言語を記述することが望ましい場合は、@languageではなくlanguageプロパティーで付与しなければなりません(must)。

この機能の例は次のとおりです。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/p1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    "@type": "cnt:ContentAsText",
    "chars": "Here starts book one...",
    "format": "text/plain",
    "language": "en"
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=100,150,500,25"
}

6.3. 代替資源の選択

一般的な要件は、様々な光源で撮影された、または、様々な時間に撮影されたなどの、そのページを表す複数の画像の選択を行えることです。これは、「oa:Choice」というオブジェクトを資源として持つことにより達成でき、その後、選択するオプションに参照付けを行います。1つのdefaultと、さらに、選択できるitemが少なくとも1つなければなりません(must)。ユーザがオプションの中から選択できるように、画像には、ビューアがユーザに表示するためのlabelがあるべきです(should)。

他の様々なタイプの資源間の選択に同じ構成を適用できます。これは、オープン・アノテーション仕様の多重性の項で記述されています。

defaultかitemのどちらかに「rdf:nil」という値を付与できます(may)。これは、有効なオプションは何も表示しないことであるということを意味します。これには、ラベルが関連付けられてはならず(must not)、ビューアは「Nothing」または適切なラベルを自由に選んで用いるべきです。

これは、様々な状態の画像をカンバスに関連付けることによって、折り込みページやその他のページの動的な機能をモデル化するために使用できます。これは、画像の性質によって、状態を変更するために画像全体を切り替えるか、適切なセグメント情報が分かっている場合には画像の中の変更しなければならない部分のみを切り替えるかのいずれかで実行できます。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    "@type": "oa:Choice",
    "default":{
      "@id": "http://example.org/iiif/book1/res/page1.jpg",
      "@type": "dctypes:Image",
      "label": "Color"
    },
    "item": [
      {
        "@id": "http://example.org/iiif/book1/res/page1-blackandwhite.jpg",
        "@type": "dctypes:Image",
        "label": "Black and White"
      }
    ]
  },
  "on": "http://example.org/iiif/book1/canvas/p1"
}

6.4. 矩形ではないセグメント

SVG(Scalable Vector Graphics)標準は、矩形ではないカンバスや画像資源の領域を記述するために用いられます。SVGは、もちろん長方形を記述できますが、これは推奨されず(not recommended)、代わりに、上記のIIIF画像APIまたはxywhバウンディング・ボックスを用いるべきです(should)。これは、高度なユースケースと認識されており、クライアントはそれをサポートできないかもしれません。

このパターンでは、アノテーションの資源は、fullフィールドで参照されている完全な画像と、selectorフィールドに組み込まれているSVG(SVGが必要な画像の部分を選ぶため)を持つ「oa:SpecificResource」です。SVGドキュメントは、コメントやテキスト化データを組み込むのと同じContentAsTextアプローチを用いて組み込まれます。

下記の例のように、画像のセクションがカンバスの一部にマッピングされている場合は、onのターゲットは、SVGのビューポート(viewport)が置かれるべき矩形のバウンディング・ボックスでなければなりません(must)。カンバス全体がターゲットの場合は、SVGのビューポートは、カンバス全体をカバーしていると見なされます。ビューポートとバウンディング・ボックスまたはカンバスの大きさが同じでない場合は、その領域カバーするようにSVGを拡大・縮小しなければなりません(must)。その結果、XとYの大きさが異なる拡大・縮小比率になる可能性があります。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    "@type": "oa:SpecificResource",
    "full": {
      "@id": "http://example.org/iiif/book1/res/page1.jpg",
      "@type": "dctypes:Image"
    },
    "selector": {
      "@type":["oa:SvgSelector","cnt:ContentAsText"],
      "chars": "<svg xmlns=\"...\"><path d=\"...\"/></svg>"
    }
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=100,100,300,300"
}

6.5. スタイル

CSS(Cascading Style Sheets)標準は、提供された資源をクライアントがどのようにユーザに表示すべきかを記述するために用いられます。CSSの情報は、上記と同じContentAsTextアプローチを用いてアノテーション内に組み込まれます。スタイルシートは、複数のスタイルを含み、アノテーション間で再利用できるため、HTMLドキュメントにリンクされているスタイルシートと同じ方法でアノテーションに直接結び付けられます。スタイルのクラスの名前は、またもやhtmlのクラス属性と同じ方法でスタイルを指定すべき資源に付与されますが、ここでは、オブジェクトのクラスとの混同を避けるためにstyleを用います。

下記の例では、文章は赤色になるはずです。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "stylesheet":{
    "@type": ["oa:CssStyle", "cnt:ContextAsText"],
    "chars": ".red {color: red;}"
  },
  "resource":{
    "@type": "oa:SpecificResource",
    "style": "red",
    "full": {
      "@type": "cnt:ContentAsText",
      "chars": "Rubrics are Red, ..."
    }
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=100,150,500,30"
}

6.6. 回転

CSSは、カンバスとの位置調整が正しく行われていない画像を回転するためにも使用できます。下記の例では、画像は、カンバス内の幅が500で高さが30の空間に配置された後に、クライアント・アプリケーションにより、左上隅を中心として反時計回りに45度回転されます。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "stylesheet":{
    "@type": ["oa:CssStyle", "cnt:ContextAsText"],
    "chars": ".rotated {transform-origin: top left; transform: rotate(-45deg);}"
  },
  "resource":{
    "@type": "oa:SpecificResource",
    "style": "rotated",
    "full": {
      "@id": "http://example.org/iiif/book1/res/page1-detail.png",
      "@type": "dctypes:Image"
    }
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=100,150,500,30"
}

あるいは、画像がIIIF画像APIで提供されていれば、サーバーに画像を回転させる方がより便利でしょう。これは、オープン・アノテーション拡張の付録で詳細に説明している、画像API用にカスタマイズされたセレクターを用います。回転の目的のために、下記の例でそのパターンを示します。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    "@id": "http://example.org/iiif/book1-page1/full/full/90/default.jpg",
    "@type": "oa:SpecificResource",
    "full": {
      "@id": "http://example.org/iiif/book1-page1/full/full/0/default.jpg",
      "@type": "dctypes:Image",
      "service": {
        "@context": "http://iiif.io/api/image/2/context.json",
        "@id": "http://example.org/iiif/book1-page1",
        "profile": "http://iiif.io/api/image/2/level2.json"
      }
    },
    "selector": {
      "@context": "http://iiif.io/api/annex/openannotation/context.json",
      "@type": "iiif:ImageApiSelector",
      "rotation": "90"
    }
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=50,50,320,240"
}

6.7. コメント・アノテーション

カンバスに関するコメントであるアノテーションの場合、コンテンツ資源をカンバスに描くこととは対照的に、区別を明確にするための動機には様々な種類があります。コンテンツに関するアノテーション(コメント、注、説明など)では、motivationは「oa:commenting」であるべきですが(should)、オープン・アノテーション仕様で提供されているリストのものであればどれでもかまいません(may)。

描画のアノテーションとは異なり、他の動機を用いたコメントやアノテーションは、自身のアイデンティティとして割り当てられ、@idプロパティーで提供されるURIを持つべきです(should)。そのURIを逆参照した時には、アノテーションの表現が返されるべきです(should)。これは、コメントにアノテーションを付与するためのアノテーションをさらに可能にするためで、例えば、それに返答したり、組織的な目的または発見目的でそれにタグ付けを行うためです。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "oa:commenting",
  "resource":{
    "@id": "http://example.org/iiif/book1/res/comment1.html",
    "@type": "dctypes:Text",
    "format": "text/html"
  },
  "on": "http://example.org/iiif/book1/canvas/p1"
}

他の資源は、マニフェスト(pl.)(オブジェクトに関するコメント)、シーケンス(その特定の順序に関するコメント)、範囲(pl.)(セクションに関するコメント)、アノテーション(ターゲットとするアノテーションへの返答)などの、それらに関して述べられているコメントを持つこともできます。クライアントがこれらのアノテーションを発見できるように、ターゲット資源から参照されるAnnotationListにそれを含めることができます。これは、otherContentパターンを再利用することで達成されます。あらゆる資源は、この方法でアノテーションのリストと関連付けることができます。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/manifest",
  "@type": "sc:Manifest",
  // ...

  "otherContent": [
    {
      "@id": "http://example.org/iiif/book1/list/book1",
      "@type": "sc:AnnotationList"
    }
  ]
}

6.8. ホットスポット・リンク

アノテーションは、マニフェスト内でも、外部コンテンツに対しても、資源間のリンクを作成するために用いることもできます。これは、異なるカンバス内のデジタル化された新聞記事の続きへのリンクや、カンバス内の図形について説明している外部ウェブ・ページへのリンクに使用できます。

ホットスポット・リンク(Hotspot linking)は、「oa:linking」というmotivationでアノテーションを用いて達成されます。クリックした時にリンクを機能させるべきカンバス領域は、他のアノテーションと同じ方法でonフィールドで指定します。リンクする資源は、resourceフィールドで提供します。リンクされている資源は、別のカンバスやカンバスの領域でもありえます(may)。リンクされている資源を、新しいタブで開くのか、新しいウィンドウで開くのか、現在のビューを置き換えて開くのかのユーザ体験は、実装次第です。

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id":"http://www.example.org/iiif/book1/annotation/anno1",
  "@type":"oa:Annotation",
  "motivation":"oa:linking",
  "resource": {
    "@id":"http://www.example.org/page-to-go-to.html",
    "@type":"dctypes:Text",
    "format":"text/html"
  },
  "on":"http://www.example.org/iiif/book1/canvas/p1#xywh=500,500,150,30"
}

7. HTTPリクエストと応答

この項では、APIに推奨される(recommended)リクエストと応答の相互作用について記述しています。RESTとシンプルなHATEOASのアプローチを取ると、相互作用によって資源の記述が読み出され、記述から得られるリンクを辿ることで追加の呼び出しを行えます。すべてのリクエストにHTTP GETメソッドを用います。資源の作成と更新についてはこの仕様ではカバーしていません。

7.1. リクエスト

4項のそれぞれのエントリーは、様々な資源で従うべきURIのパターンを推奨しています。これらのパターンに従うことは必須ではなく(NOT REQUIRED )、クライアントは、独自にURIを構築してはならず(must not)、代わりに、読み出された記述の中のリンクを辿らなければなりません(must)。

APIによって利用可能となる資源に推奨される(recommended)基底URI(追加情報が加えられる)は次のとおりです。

{scheme}://{host}{/prefix}/{identifier}

その場合のパラメータは次のとおりです。

名前	説明
scheme	サービスの呼び出しにおけるhttpまたはhttpsのプロトコルの使用を示します。
server	サービスが存在するホスト・サーバー(および、オプションでポート)。
prefix	サービスに対するホスト・サーバーのパス。この接頭辞はオプションですが、ホスト・サーバーが複数のサービスをサポートしている時には有用でありえます。接頭辞には、スラッシュで区切った複数のパス・セグメントを含むことができますが(may)、他のすべての特殊文字はエンコードしなければなりません(must)。
identifier	オブジェクトまたはコレクションの識別子。文字列で表されます。これは、アーク、URN、その他の識別子でありえます。特殊文字は、URIエンコードされなければなりません(must)。

個々の資源は、この最上位のパターンより下のURIを持っているべきで(should)、それは、資源を識別するために「/」と追加情報を加えた形式になります。様々な資源タイプに対して、これらのURIに推奨されるパターンを以下の項で提供しており、付録Aで要約しています。

ウェブ・サーバーの設定にアクセスできないファイルシステムでJSONドキュメントが管理されている状況では、クライアントに正しいコンテンツ・タイプ応答ヘッダーが確実に送信されるように、URI末尾に「.json」と記述することを提案します。これは下記の推奨されるURIのパターンに従っていませんが、この仕様でも妨げられません。

7.2. 応答

すべての応答のフォーマットはJSONです。下記の項では、返される構造について説明しています。

応答のコンテンツ・タイプは、application/json(通常のJSON)、

Content-Type: application/json

または「application/ld+json」(JSON-LD)でなければなりません(must)。

Content-Type: application/ld+json

クライアントが明確にJSON-LDコンテンツ・タイプを望んでいる場合は、Acceptヘッダーでそれを指定しなければならず(must)、そうでない場合は、サーバーは通常のJSONコンテンツ・タイプを返さなければなりません(must)。

HTTPサーバーは、クライアントがリモート・サイトからAJAXでマニフェスト(pl.)をダウンロードできるようにするために、可能な限りCross Origin Access Control(しばしば「CORS」と呼ばれる)を送信すべきです(should)。そのヘッダー名はAccess-Control-Allow-Originで、ヘッダーの値は*であるべきです(should)。

Access-Control-Allow-Origin: *

非常に反復性の高いデータ構造に対して大きな性能向上が見込まれるため、サーバーは応答を圧縮すべきです(should)。

CORSと条件付きコンテンツ・タイプヘッダーを有効にするための秘訣は、Apache HTTPサーバー実装ノートで提供されています。

8. 認証

プレゼンテーションAPIで利用できる記述へのアクセスを限定することが必要でありえます。記述と相互作用は主にドメイン間でXmlHttpRequestsを用いたウェブ・ブラウザにより行われるため、最も適したユーザ認証およびアクセス承認方法には、いくつかの留意事項があります。取ることができるアプローチは認証仕様で記述されており、ユーザを識別するためにリクエストに追加するトークンをリクエストする必要があります。このトークンは、他のAPIで定義されている他のリクエストにも利用できるかもしれません。

マニフェスト内に画像APIサービス記述を含むことができ、その中に、画像コンテンツとの相互作用に必要な認証APIのサービスへのリンクを含むこともできます。マニフェスト内に認証APIサービスを初めて含む時には、それは完全な記述でなければなりません(must)。以後は、参照は単なるサービスのURLであるべきで(should)、クライアントは、URLとのマッチングにより完全な記述から詳細を調べることが期待されます。クライアントはマニフェストの認証サービス記述が期限切れである状況を予測しなければなりません(must)。真の情報源は、画像情報ドキュメント、または認証APIサービスを参照している他のシステムです。

付録

A. 推奨されるURIのパターンの要約

資源	URIのパターン
Collection	{scheme}://{host}/{prefix}/collection/{name}
Manifest	{scheme}://{host}/{prefix}/{identifier}/manifest
Sequence	{scheme}://{host}/{prefix}/{identifier}/sequence/{name}
Canvas	{scheme}://{host}/{prefix}/{identifier}/canvas/{name}
Annotation	{scheme}://{host}/{prefix}/{identifier}/annotation/{name}
AnnotationList	{scheme}://{host}/{prefix}/{identifier}/list/{name}
Range	{scheme}://{host}/{prefix}/{identifier}/range/{name}
Layer	{scheme}://{host}/{prefix}/{identifier}/layer/{name}
Content	{scheme}://{host}/{prefix}/{identifier}/res/{name}.{format}

B. メタデータ要件の要約

フィールド	意味
	必須
	推奨
	オプション
	不可

記述プロパティーと権利プロパティー

	label	metadata	description	thumbnail	attribution	license	logo
Collection
Manifest
Sequence
Canvas
Annotation
AnnotationList
Range
Layer
Image Content
Other Content

技術プロパティー

	@id	@type	format	height	width	viewingDirection	viewingHint	navDate
Collection
Manifest
Sequence
Canvas
Annotation
AnnotationList
Range
Layer
Image Content
Other Content

リンク付けプロパティー

	seeAlso	service	related	rendering	within	startCanvas
Collection
Manifest
Sequence
Canvas
Annotation
AnnotationList
Range
Layer
Image Content
Other Content

ページ付けプロパティー

	first	last	total	next	prev	startIndex
Collection
Manifest
Sequence
Canvas
Annotation
AnnotationList
Range
Layer
Image Content
Other Content

構造プロパティー

	collections	manifests	members	sequences	structures	canvases	resources	otherContent	images	ranges
Collection
Manifest
Sequence
Canvas
Annotation
AnnotationList
Range
Layer
Image Content
Other Content

プロトコルの挙動

	@idが逆参照可能
Collection
Manifest
Sequence (first)
Sequence (second+)
Canvas
Annotation
AnnotationList
Range
Layer
Image Content
Other Content

C. マニフェスト応答の例

URL: http://example.org/iiif/book1/manifest

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@type": "sc:Manifest",
  "@id": "http://example.org/iiif/book1/manifest",

  "label": "Book 1",
  "metadata": [
    {"label": "Author", "value": "Anne Author"},
    {"label": "Published", "value": [
        {"@value": "Paris, circa 1400", "@language": "en"},
        {"@value": "Paris, environ 14eme siecle", "@language": "fr"}
        ]
    }
  ],
  "description": "A longer description of this example book. It should give some real information.",
  "navDate": "1856-01-01T00:00:00Z",

  "license": "http://example.org/license.html",
  "attribution": "Provided by Example Organization",
  "service": {
    "@context": "http://example.org/ns/jsonld/context.json",
    "@id": "http://example.org/service/example",
    "profile": "http://example.org/docs/example-service.html"
  },
  "seeAlso":
    {
      "@id": "http://example.org/library/catalog/book1.marc",
      "format": "application/marc",
      "profile": "http://example.org/profiles/marc21"
    },
  "rendering": {
    "@id": "http://example.org/iiif/book1.pdf",
    "label": "Download as PDF",
    "format": "application/pdf"
  },
  "within": "http://example.org/collections/books/",

  "sequences": [
      {
        "@id": "http://example.org/iiif/book1/sequence/normal",
        "@type": "sc:Sequence",
        "label": "Current Page Order",
        "viewingDirection": "left-to-right",
        "viewingHint": "paged",
        "canvases": [
          {
            "@id": "http://example.org/iiif/book1/canvas/p1",
            "@type": "sc:Canvas",
            "label": "p. 1",
            "height":1000,
            "width":750,
            "images": [
              {
                "@type": "oa:Annotation",
                "motivation": "sc:painting",
                "resource":{
                    "@id": "http://example.org/iiif/book1/res/page1.jpg",
                    "@type": "dctypes:Image",
                    "format": "image/jpeg",
                    "service": {
                        "@context": "http://iiif.io/api/image/2/context.json",
                        "@id": "http://example.org/images/book1-page1",
                        "profile": "http://iiif.io/api/image/2/level1.json"
                    },
                    "height":2000,
                    "width":1500
                },
                "on": "http://example.org/iiif/book1/canvas/p1"
              }
            ],            "otherContent": [
              {
                "@id": "http://example.org/iiif/book1/list/p1",
                "@type": "sc:AnnotationList",
                "within": {
                    "@id": "http://example.org/iiif/book1/layer/l1",
                    "@type": "sc:Layer",
                    "label": "Example Layer"
                }
              }
            ]
        },
          {
            "@id": "http://example.org/iiif/book1/canvas/p2",
            "@type": "sc:Canvas",
            "label": "p. 2",
            "height":1000,
            "width":750,
            "images": [
              {
                "@type": "oa:Annotation",
                "motivation": "sc:painting",
                "resource":{
                    "@id": "http://example.org/images/book1-page2/full/1500,2000/0/default.jpg",
                    "@type": "dctypes:Image",
                    "format": "image/jpeg",
                    "height":2000,
                    "width":1500,
                    "service": {
                        "@context": "http://iiif.io/api/image/2/context.json",
                        "@id": "http://example.org/images/book1-page2",
                        "profile": "http://iiif.io/api/image/2/level1.json",
                        "height":8000,
                        "width":6000,
                        "tiles": [{"width": 512, "scaleFactors": [1,2,4,8,16]}]
                    }
                },
                "on": "http://example.org/iiif/book1/canvas/p2"
              }
            ],
            "otherContent": [
              {
                "@id": "http://example.org/iiif/book1/list/p2",
                "@type": "sc:AnnotationList",
                "within": "http://example.org/iiif/book1/layer/l1"  
              }
            ]
          },
          {
            "@id": "http://example.org/iiif/book1/canvas/p3",
            "@type": "sc:Canvas",
            "label": "p. 3",
            "height":1000,
            "width":750,
            "images": [
              {
                "@type": "oa:Annotation",
                "motivation": "sc:painting",
                "resource":{
                    "@id": "http://example.org/iiif/book1/res/page3.jpg",
                    "@type": "dctypes:Image",
                    "format": "image/jpeg",
                    "service": {
                        "@context": "http://iiif.io/api/image/2/context.json",
                        "@id": "http://example.org/images/book1-page3",
                        "profile": "http://iiif.io/api/image/2/level1.json"
          },
                    "height":2000,
                    "width":1500
                },
                "on": "http://example.org/iiif/book1/canvas/p3"
              }
            ],
            "otherContent": [
              {
                "@id": "http://example.org/iiif/book1/list/p3",
                "@type": "sc:AnnotationList",
                "within": "http://example.org/iiif/book1/layer/l1"               
              }
            ]
          }
        ]
      }
    ],
  "structures": [
    {
      "@id": "http://example.org/iiif/book1/range/r1",
        "@type": "sc:Range",
        "label": "Introduction",
        "canvases": [
          "http://example.org/iiif/book1/canvas/p1",
          "http://example.org/iiif/book1/canvas/p2",
          "http://example.org/iiif/book1/canvas/p3#xywh=0,0,750,300"
        ]
    }
  ]
}

D. 実装ノート

クライアントは、一部の実装ではトップレベルで@graphプロパティーを追加でき、これにはオブジェクトが含まれていることを知っているべきです(should)。これはJSON-LDシリアル化の副作用であり、サーバーは、クライアントへの送信を実行する前にこれを削除すべきです(should)。実際にこれに遭遇した場合には、クライアントは、JSON-LD圧縮アルゴリズムとJSON-LDフレーミングの提供されるフレームを用いてそれを削除することで、正しい表現を生成できるでしょう。
.../canvas/1のように、推奨されるURI構造の{name}パラメータが数値で始まる場合は、特定の技術スタックを利用している開発者は不便に感じるでしょう。特に内部でRDF/XMLを利用しているRDFベースのスタックは、<canvas:1>が有効なXML要素ではないため、共有の.../canvas/接頭辞を抽出できず、1をCURIEとして用いるでしょう。作成者は、先頭文字としてアルファベットを追加することを検討するかもしれません。

E. バージョン付け

バージョン2.0から、この仕様はセマンティック・バージョニングに従っています。実施方法の詳細については、APIのバージョン付けのノートを参照してください。

F. 謝辞

このドキュメントの作成に、アンドリューWメロン財団の助成による寛大な支援をいただきました。

継続的な関与、革新的なアイデア、およびフィードバックに関し、IIIFのメンバーに感謝申し上げます。

G. 変更履歴

日付	説明
2016-05-12	バージョン2.1 (Hinty McHintface) 変更履歴を表示
2014-09-11	バージョン2.0 (Triumphant Giraffe) 変更履歴を表示
2013-08-26	バージョン1.0 (名称なし)
2013-06-14	バージョン0.9 (名称なし)

このドキュメントのステータス

目次

1. はじめに

1.1. 対象と範囲

1.2. ユースケースの動機づけ

1.3. 用語

2. 資源タイプの概要

2.1. 基本的なタイプ

Manifest(マニフェスト)

Sequence(順序)

Canvas(カンバス)

Content(コンテンツ)

2.2. 付加的なタイプ

Collection(コレクション)

Annotation(アノテーション)

AnnotationList(アノテーション・リスト)

Layer(レイヤー)

Range(範囲)

3. 資源プロパティー

3.1. 記述プロパティー

label(ラベル)

metadata(メタデータ)

description(記述)

thumbnail(サムネイル)

3.2. 権利・ライセンス・プロパティー

attribution(帰属)

license(ライセンス)

logo(ロゴ)

3.3. 技術プロパティー

@id

@type

format(フォーマット)

height(高さ)

width(幅)

viewingDirection(表示方向)

viewingHint(表示用ヒント)

navDate(ナビゲーションの日付)

3.4. リンク付けプロパティー

related(関連付け)

rendering(表示)

service(サービス)

seeAlso(をも見よ参照)

within(内部)

startCanvas(開始カンバス)

contentLayer(コンテンツ・レイヤー)

3.5. ページ付けプロパティー

first(最初)

last(最後)

total(合計)

next(次)

prev(前)

startIndex(開始インデックス)

4. JSON-LDに関する留意点

4.1. URI表現

4.2. プロパティーの繰り返し

4.3. プロパティー値の言語

4.4. プロパティー値内のHTMLマークアップ

4.5. リンクト・データのコンテキストと拡張

5. 資源構造

5.1. マニフェスト

5.2. シーケンス

5.3. カンバス

5.4. 画像資源

5.5. アノテーション・リスト

5.6. 範囲

ranges

canvases

members

5.7. レイヤー

5.8. コレクション

collections

manifests

members

5.9. ページ付け

ページ付きレイヤーの例

ページ付きコレクションの例

6. 高度な関連付け機能

6.1. セグメント

6.2. 組み込みコンテンツ

6.3. 代替資源の選択