IIIF画像API 3.0

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

本バージョン: 3.0.0

最新安定版: 3.0.0

旧バージョン: 2.1.1

編集者:

• Michael Appleby , Yale University
• Tom Crane , Digirati
• Robert Sanderson , J. Paul Getty Trust
• Jon Stroop , Princeton University Library
• Simeon Warner , Cornell University

Copyright © 2012-2020 Editors and contributors. Published by the IIIF Consortium under the CC-BY license, see disclaimer.

目次

• 1. はじめに
  • 1.1. 対象者と範囲
  • 1.2. 用語
• 2. URI構文
  • 2.1. 画像リクエストURI構文
  • 2.2. 画像情報リクエストURI構文
• 3. 識別子
• 4. 画像リクエスト
  • 4.1. 領域
  • 4.2. サイズ
  • 4.3. 回転
  • 4.4. 品質
  • 4.5. フォーマット
  • 4.6. 実装の順序
  • 4.7. 浮動小数点値
  • 4.8. 正規URI構文
  • 4.9. 拡張
• 5. 画像情報
  • 5.1. 画像情報リクエスト
  • 5.2. 技術プロパティー
  • 5.3. サイズ
  • 5.4. タイル
  • 5.5. 優先フォーマット
  • 5.6. 権利
  • 5.7. 追加機能
  • 5.8. リンク付けプロパティー
  • 5.9. 完全な応答
• 6. 準拠レベルとプロファイル・ドキュメント
• 7. サーバー応答
  • 7.1. CORS
  • 7.2. 成功の応答
  • 7.3. エラー状況
  • 7.4. HTTPのバージョン
• 8. 認証
• 9. URIのエンコーディングとデコーディング
• 10. セキュリティに関する留意点
• 11. 付録
  • A. バージョン付け
  • B. 謝辞
  • C. 変更履歴

1. はじめに

このドキュメントは、IIIF(International Image Interoperability Framework、「トリプル・アイ・エフ」と発音)コンソーシアムが定める画像配信APIについて記述しています。IIIF画像APIは、標準的なHTTPやHTTPSのリクエストに応答して画像を返すウェブ・サービスの仕様を定めています。URIによって、リクエストする画像の領域、サイズ、回転、品質特性およびフォーマットを指定できます。また、クライアント・アプリケーションをサポートするために、画像に関する基本的な技術情報をリクエストするようにURIを構成することもできます。このAPIは、文化遺産機関が管理しているデジタル画像リポジトリの画像資源を体系的に再利用可能とするために考案したものですが、いかなる画像リポジトリやサービスにも採用でき、これを利用することで、適切に構成されたURIへの応答として静止画像を読み出すことができます。

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

1.1. 対象者と範囲

このドキュメントは、とりわけ文化遺産機関、博物館、図書館、公文書館のデジタル画像を共有、利用するためのアプリケーションを構築する設計者と開発者を対象としています。ターゲットとしているアプリケーションには次のものが含まれます。

• デジタル画像リポジトリおよび分散型コンテンツ・ネットワーク
• パン／ズーム・ビューア、ブック・リーダーなどの、画像に重点を置いたウェブ・アプリケーション
• 分析や比較のために画像コンテンツを利用するクライアント・アプリケーション

この仕様で取り上げるのは、クライアントによる画像リクエストであり、サーバーによる画像管理ではありません。この仕様は、特定のURI構文に従ったリクエストに対する応答方法についてはカバーしていますが、回転アルゴリズム、トランスコーディング、カラー・マネジメント、圧縮などの実装方法や、既定の構文に準拠していないURIに対する応答方法についてはカバーしていません。これにより、一般的なケースにおける相互運用性をサポートしつつ、特定の制約やコミュニティー固有の慣習が存在する領域においても柔軟な実装が可能となります。

実装では、事前に生成されたファイルを静的なウェブ資源として提供しても、豊かなユーザ体験を実現できます。 動的な画像サーバーの実装では、ベースとなる準拠レベルを超える追加機能を提供できます。

1.2. 用語

基礎となる画像コンテンツという用語は、情報源の画像データを指すために用います。その形式や構造に関する想定はありません。これは、1つ以上の情報源の画像から得られる場合もありますが、動的に生成することもできます。

フル画像という用語は、画像情報ドキュメントで指定されているピクセルの大きさで、基礎となる画像コンテンツの領域全体を指すために用い、これは、画像リクエストの開始点として想定されます。

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

2. URI構文

IIIF画像APIは、次の2つの方法で呼び出すことができます。

• 画像をリクエストする。これは、基礎となる画像コンテンツから得られる。
• 画像サービスに関する情報をリクエストする。これには、特性、利用可能な機能、および関連サービスが含まれる。

どちらも、リクエスト情報を、クエリのパラメータとしてではなく、URIのパス・セグメントで伝えます。これにより、サーバーや標準的なウェブ・キャッシュ基盤が応答をより容易にキャッシュできるようになります。マッチング用のディレクトリ構造内の事前処理済みファイルを用いた最小限の実装も可能です。

リクエストには共通するパラメータが4つあり、他のIIIF仕様もあります。

これらのパラメータの組み合わせにより、画像サービスの基底URIが形成され、基礎となる画像コンテンツが識別されます。これは次のURIテンプレート(RFC6570)に従って構成されます。

{scheme}://{server}{/prefix}/{identifier}

基底URIを逆参照した時には、その相互作用により画像情報ドキュメントが得られるべきです(should)。応答は、303ステータスによる画像情報ドキュメントのURIへのリダイレクションであることが推奨されます(recommended)。実装では、HTTPリクエストのヘッダーとメソッドに応答して、基底URIに対して、この仕様の範囲を超える他の挙動を示すことも可能です(may)。

拡張の余地を残すために、この仕様では、基底URIまたは下記のURI構文のいずれにも適合しないリクエストを受け取った時のサーバーの挙動は定義していません。

2.1. 画像リクエストURI構文

画像リクエスト用のIIIF画像APIのURIは、次のURIテンプレートに準拠していなければなりません(must)。

{scheme}://{server}{/prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}

例えば、次のとおりです。

https://example.org/image-service/abcd1234/full/max/0/default.jpg

画像リクエストURIのパラメータには、region(領域)、size(サイズ)、rotation(回転)、quality(品質)、format(フォーマット)があり、これらによって、返される画像の特性が定まります。これらに関する詳細は、画像リクエストで説明しています。

2.2. 画像情報リクエストURI構文

画像情報リクエスト用のURIは、次のURIテンプレートに準拠していなければなりません(must)。

{scheme}://{server}{/prefix}/{identifier}/info.json

例えば、次のとおりです。

https://example.org/image-service/abcd1234/info.json

情報リクエストのコンポーネントであるscheme(スキーム)、server(サーバー)、prefix(接頭辞)、identifier(識別子)は、画像情報ドキュメントに記述する画像コンテンツに関する上記の画像リクエストと同じでなければなりません(must)。画像情報ドキュメントの詳細は、画像情報の項で説明しています。

3. 識別子

APIは、サーバーが使用またはサポートする識別子の形式に制限を設けません。クライアントの予測不可能な挙動を避けるため、すべての特殊文字(例えば、?や#)にURIエンコードを行わなければなりません(must)。URI構文は、スラッシュ(/)という区切り文字に依存しているため、識別子内のあらゆるスラッシュはURIエンコード(「パーセント・エンコード」とも呼ばれる)されていなければなりません(must)。URIのエンコーディングとデコーディングにおけるさらなる議論を参照してください。

4. 画像リクエスト

IIIF画像APIに準拠したURIを構築するためには、下記のすべてのパラメータが必要です。URI内のパラメータの順序は、下記の順序でなければなりません(must)。パラメータの順序は、サービスが画像コンテンツを処理すべき操作順序のニーモニックでもあります。したがって、リクエストされた画像コンテンツは、最初にフル画像領域として抽出され、その後、リクエストされたサイズへの拡大・縮小、反転および／または回転が行われ、最後にリクエストされた色品質とフォーマットに変換されます。その結果の画像が、URIに対する表現として返されます。

サイズと領域のパラメータのピクセル数は、負でない整数でなければなりません(must)。サイズと領域パラメータ、および回転パラメータのパーセンテージは、正の浮動小数点数か整数でなければなりません(must)。IIIF URIの浮動小数点数の表現の詳細については、浮動小数点値の項を参照してください。

サーバーは、画像の応答でCORSをサポートすべきです(should)。

4.1. 領域

region(領域)パラメータは、基礎となる画像コンテンツのうち、返される矩形部分を定義します。領域は、ピクセル座標、パーセンテージ、またはフル画像を返すべきと指定するfullという値で指定できます。

画像情報ドキュメントで報告されているフル画像全の大きさを超える領域がリクエストされた場合には、サービスは、空白を追加するのではなく、画像の端で切り取った画像を返すべきです(should)。

リクエストされた領域の高さや幅が0であったり、領域が報告されている大きさの境界から完全に外れていたりすれば、サーバーは400(Bad Request)のステータス・コードを返すべき(should)です。

例:

1 region=full .../full/max/0/default.jpg	2 region=square .../square/max/0/default.jpg
3 region=125,15,120,140 .../125,15,120,140/max/0/default.jpg	4 region=pct:41.6,7.5,40,70 .../pct:41.6,7.5,40,70/max/0/default.jpg
5 region=125,15,200,200 .../125,15,200,200/max/0/default.jpg 返される画像が175,185ピクセルであることに注意	6 region=pct:41.6,7.5,66.6,100 .../pct:41.6,7.5,66.6,100/max/0/default.jpg 返される画像が175,185ピクセルであることに注意

4.2. サイズ

size(サイズ)パラメータは、抽出される領域(フル画像の場合もある)が拡大・縮小されるべき大きさを指定します。w,hと^w,hの形式を除き、返される画像は、抽出される領域の縦横比を可能な限り厳密に維持します。サイズに^という接頭辞を付与することにより、抽出される領域の大きさが拡大・縮小される領域の大きさよりも小さい場合に、その領域を拡大できます。

^という接頭辞なしにサイズに対するリクエストを行った結果、抽出される領域の大きさよりも、拡大・縮小される領域の方が大きくなる場合は、400(Bad Request)というステータス・コードのエラーになるべきです(should)。

^という接頭辞付きのサイズに対するリクエストで、拡大が必要な場合に、サーバーが拡大をサポートしていなければ、501(Not Implemented)のステータス・コードになるべきですが(should)、その他のクライアントのリクエストの構文エラーへの応答では400(不正なリクエスト)ステータス・コードが返されるべきです(should)。例えば、^pct:120というサイズに対するリクエストは、サーバーが拡大をサポートしていなければ、501のステータス・コードになるべきです。

すべてのリクエストにおいて、拡大・縮小された領域の大きさは、1ピクセル未満であったり、サーバーの制限を超えたりしてはなりません(must not)。これらのサイズの画像を生成しようとするリクエストはエラーであり、その結果は400(Bad Request)のステータス・コードになるべきです(should)。

例:

1 size=max .../full/max/0/default.jpg 画像が200ピクセルのmaxWidthを持っていると想定していることに注意	1 size=^max .../full/^max/0/default.jpg 画像が360ピクセルのmaxWidthを持っていると想定していることに注意
2 size=150, .../full/150,/0/default.jpg	2 size=^360, .../full/^360,/0/default.jpg
3 size=,150 .../full/,150/0/default.jpg	3 size=,^240 .../full/,^240/0/default.jpg
4 size=pct:50 .../full/pct:50/0/default.jpg	4 size=pct:120 .../full/pct:120/0/default.jpg
5 size=225,100 .../full/225,100/0/default.jpg	5 size=^360,360 .../full/^360,360/0/default.jpg
6 size=!225,100 .../full/!225,100/0/default.jpg 返される画像が150,100ピクセルであることに注意	6 size=^!360,360 .../full/^!360,360/0/default.jpg 返される画像が360,240ピクセルであることに注意

4.3. 回転

rotation(回転)パラメータは、反転と回転を規定します。先頭の感嘆符(「!」)は、回転が適用される前に垂直軸に基づいて画像が反転されるべきであることを示します。数値は、時計回りの回転角度を表し、0から360までの浮動小数点数でありえます。

範囲外であったり、サポートされていない回転の値は、400(Bad Request)のステータス・コードになるべきです(should)。

ほとんどの場合、回転によって、返される画像の幅と高さが変わります。サービスは、サイズ・パラメータによる指定と返される画像ファイルの大きさが異なっていても、領域とサイズ・パラメータでリクエストされたすべての画像コンテンツが含まれている画像を返すべきです(should)。画像コンテンツは、回転の結果として拡大・縮小されるべきではなく(should not)、回転した画像コンテンツの角と返される画像のバウンディング・ボックス(bounding box)の間に余分な空間があるべき(should)ではありません。

回転角度が90度の倍数でない場合は、クライアントはpngなどの透過をサポートするフォーマットの画像をリクエストし、サーバーは背景が透明の画像を返すことを推奨します(recommended)。APIには、クライアントが特定の背景色やその他の塗りつぶしパターンをリクエストする機能はありません。

例:

1 rotation=0 .../full/max/0/default.jpg	2 rotation=180 .../full/max/180/default.jpg
3 rotation=90 .../full/max/90/default.jpg	4 rotation=22.5 .../full/max/22.5/default.png
5 rotation=!0 .../full/max/!0/default.jpg	6 rotation=!180 .../full/max/!180/default.jpg

4.4. 品質

quality(品質)パラメータは、カラー、グレースケール、黒白のいずれで画像が配信されるかを決定します。

defaultの品質は、コレクションの個々の画像の品質が不明である準拠レベル0の実装をサポートするために存在しています。これは、どの品質が利用できるのかを知るためにしか役立たない予備的な画像情報リクエストを避けられるという点で、クライアントが品質以外のリクエストのパラメータ値をすべて知っている場合に利便性を提供することにもなります(例えば、サムネイルをリクエストするために、.../full/120,80/90/{quality}.png)。

準拠レベルに関係なく、defaultを超える追加品質を提供するサービスでは、画像情報リクエストへの応答のextraQualitiesプロパティーにその品質を列挙しなければなりません(must)。サポートされていない品質の値を持つ画像に対するリクエストには、400(Bad Request)のステータス・コードを返すべきです(should)。

画像のcolor品質に対するリクエストには、画像を返さなければなりません(must)。この画像は、サーバーが用意できる色情報がグレースケールや2値のピクセルのみであれば、それのみで構成できます。そのような場合、サーバーはextraQualitiesのリストにcolorを含めるべきではありませんが(should not)、color品質に対するリクエストの結果はエラーになってはなりません(must not)。同様に、グレースケール品質に対するリクエストに、2値のピクセルのみで構成される画像を返すこともできます。

例:

1 quality=default .../full/max/0/default.jpg	2 quality=color .../full/max/0/color.jpg
3 quality=gray .../full/max/0/gray.jpg	4 quality=bitonal .../full/max/0/bitonal.jpg

4.5. フォーマット

返される画像のフォーマットは、一般的なファイル名拡張子を反映した、URI末尾の接尾辞として表されます。

フォーマットの値がサポートされていなければ、400(Bad Request)のステータス・コードになるべきです(should)。

例:

1. .../full/max/0/default.jpg
2. .../full/max/0/default.png
3. .../full/max/0/default.tif

4.6. 実装の順序

URIのパラメータの順序は、基礎となる画像コンテンツに画像操作が行われる順序のニーモニックです。同じパラメータを異なる順序で適用すると異なる画像が配信されることが多いため、画像サービスを実装する際に、これを考慮することは重要です。

パラメータは、画像操作の順序が次のとおりであるものとして解釈すべきです。

Region THEN Size THEN Rotation THEN Quality THEN Format(Region その次が Size その次が Rotation その次が Quality その次が Format)

回転パラメータに反転(!)が含まれていれば、回転の前に反転が適用されます。

1 region=125,15,120,140 size=90, rotation=!345 quality=gray .../125,15,120,140/90,/!345/gray.jpg

4.7. 浮動小数点値

パーセンテージで指定されたサイズと領域のパラメータ、および回転パラメータでは、正の浮動小数点数の値が許されています。可能な場合は、整数の値を用いるべきです(should)。浮動小数点値を用いる場合、10進数と「.」のみで構成(例えば、+0.9ではなく0.9)しなければならず(must)、1未満の場合は先頭を0で表す(例えば、.9ではなく0.9)べきであり(should)、末尾にゼロを含めない(例えば、0.90ではなく0.9)ようにすべきです(should not)。計算途中には浮動小数点数を使用でき、端数の処理方法は実装固有です。

4.8. 正規URI構文

異なるパラメータの組み合わせを用いて同じ画像をリクエストできます。クライアントが使いやすい形式でリクエストを表現できれば便利ですが、正規のURI構文の方が望ましい理由がいくつかあります。

• 固定的な、ファイル―システム・ベースの実装が可能となり、これにはコンテンツを入手できるURIが1つだけ存在する。
• 用いるURIがシステムとセッションとの間で同じであれば、クライアントとサーバー側の両方でキャッシュが著しく効率的になる。
• リクエストされた非正規のURI構文から正規の形式を直接用いた正規の構文へのリダイレクトを避けることにより、応答時間を改善できる。

上記の要件をサポートするために、可能であれば、クライアントは次の正規のパラメータ値を用いて画像リクエストURIを構成すべきです(should)。画像サーバーは、クライアントを非正規のURIから正規のURIにリダイレクトさせることができます(may)。

クライアントが画像をリクエストした時には、サーバーは、そのリクエストに対する正規URIを示すリンク・ヘッダーを応答に追加できます(may)。

Link: <http://iiif.example.com/server/full/400,300/0/default.jpg>;rel="canonical"

サーバーはこのリンク・ヘッダーを画像情報の応答に含めることもできますが(may)、読み出されるJSON表現にこれが含まれているため、その必要はありません。

4.9. 拡張

IIIF画像APIは、領域、サイズおよび回転のパラメータに新たなパラメータのパターンを追加するか、品質およびフォーマットのパラメータに新たな値を追加することにより、画像情報リクエストURI構文内で拡張できます。既存のパラメータの範囲を超えるリクエスト情報は、クエリのパラメータとして画像サーバーに渡すことができます。拡張機能は、追加機能の項のガイドラインに従って、画像情報ドキュメントに記述すべきです(should)。

5. 画像情報

サーバーは画像情報に対するリクエストをサポートしなければなりません(must)。応答は、フル画像に関する技術プロパティーが含まれているJSONドキュメントです。また、権利情報や画像に関連するサービスを含むこともできます。

5.1. 画像情報リクエスト

画像情報に対するリクエストは、次のURIテンプレートに準拠していなければなりません(must)。

{scheme}://{server}{/prefix}/{identifier}/info.json

応答の構文はJSON-LDです。Acceptヘッダーが含まれているリクエストをサーバーが受け取ると、内容交渉の規則に従って応答すべきです(should)。リクエストのAcceptヘッダーで提供されるコンテンツ・タイプには、profileやcharsetなどのパラメータが含まれる場合がある(may)ことに注意してください。

リクエストにAcceptヘッダーが含まれていない場合は、応答のHTTP Content-Typeヘッダーには、profileパラメータをコンテキスト・ドキュメント(http://iiif.io/api/image/3/context.json)として指定したapplication/ld+json(JSON-LD)という値が含まれているべきです(should)。

Content-Type: application/ld+json;profile="http://iiif.io/api/image/3/context.json"

サーバー設定の詳細が原因でContent-Typeヘッダーのapplication/ld+jsonを生成できない場合、Content-Typeヘッダーは、profileパラメータのないapplication/json(通常のJSON)になるべきです(should)。

Content-Type: application/json

サーバーは、画像情報の応答でCORSをサポートすべきです(should)。

5.2. 技術プロパティー

JSONの応答には、画像コンテンツで利用可能な機能を記述するいくつかの技術プロパティーがあります。

widthとheightのプロパティーはフル画像のサイズを示し、タイルのリクエストを構築するために必要です。

maxWidth、maxHeight、maxAreaのパラメータは、画像にサポートされているサイズの限界を画像サーバーが表す方法を提供します。maxWidthのみ、またはmaxWidthとmaxHeightが指定されている場合は、クライアントは、それより大きな長さのリクエストは拒否されると予期すべきです。maxAreaが指定されている場合は、クライアントは、それより大きなピクセル領域のリクエストが拒否されると予期すべきです。maxWidth / maxHeightとmaxAreaのパラメータは独立しており、サーバーはどちらか一方または両方の限界を実装できます。サーバーは、sizesまたはtilesのプロパティーで指定されたサイズが、表されているサイズの限界の範囲内にあることを保証しなければなりません(must)。クライアントは、表されているサイズの限界を上回るリクエストを行うべきではありません(should not)。

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "maxHeight": 2000,
  "maxWidth": 3000,
  "maxArea": 4000000
}

5.3. サイズ

JSONの応答にはsizesプロパティーを含むことができ(may)、これは、フル画像の表現に対する望ましいheightとwidthの組み合わせを記述するために用います。

sizes配列内のJSONオブジェクトは、以下の表のプロパティーを持っています。これらのサイズに対する画像リクエストは、fullの領域パラメータ、正規のw,hフォームのサイズ・パラメータ、および0という回転率を持っているべきです(should)。したがって、jpgというフォーマットでdefaultという品質を持つ画像の完全なURLは、{scheme}://{server}/{prefix}/{identifier}/full/{width},{height}/0/default.jpgでしょう。

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "sizes": [
    { "width": 150, "height": 100 },
    { "width": 600, "height": 400 },
    { "width": 3000, "height": 2000 }
  ]
}

5.4. タイル

JSONの応答は、視覚的につなぎ合わせることができる、一貫した高さと幅を持つ画像領域の(連続する解像度上の)集合を記述したtilesプロパティーを持つことができます(may)。

tiles配列内のJSONオブジェクトは、以下の表のプロパティーを持っています。widthとheightは、サイズ・パラメータを埋めるために用い、画像リクエストの領域パラメータを計算するためにscaleFactorsと一緒に用いるべきです。これに関しては実装ノートで詳細に説明しています。

tiles配列内のオブジェクトはそれぞれ、widthとheightの一意の組み合わせを持っていなければならず(must)、明示的に指定されていない場合は、height = widthです。

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "tiles": [
    { "width": 512, "scaleFactors": [ 1, 2, 4, 8, 16 ] }
  ]
}

5.5. 優先フォーマット

JSONの応答は、この画像サービスの1つ以上のフォーマットのパラメータ値を列挙したpreferredFormatsプロパティーを持つことができます(may)。これにより、公開者はクライアントがリクエストするフォーマットのプレファレンスを表し、例えば、webpなどのより効率的なフォーマットの利用を奨励したり、ライン・アートやグラフィックス用にロスレスのwebpやpngなどの画像コンテンツにより良い結果をもたらすフォーマットを提案したりすることができます。

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "extraFormats": [ "webp" ],
  "preferredFormats": [ "webp", "png" ]
}

5.6. 権利

rightsプロパティーは、プレゼンテーションAPIと同じセマンティクスと要件を持っています。

この画像の公開者が、表示時に追加情報の表示を求める場合は、リンク付けプロパティーの項で説明しているように、プレゼンテーションAPIのマニフェストでその情報を提供すべきです。

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "rights": "http://rightsstatements.org/vocab/InC-EDU/1.0/"
}

5.7. 追加機能

JSONの応答には、画像サービスを介して利用できる追加機能を記述するプロパティーを含むこともできます(may)。

次の機能は、extraFeaturesプロパティーで用いるために定義しています。

sizeByWもsizeByWhもサポートしないサーバーは、sizesプロパティーで記述されている、または、画像情報ドキュメントのtilesプロパティーで暗示されている画像サイズを提供すれば良いだけであり、それによって、静的なファイル実装が可能となります。

sizeUpscalingをサポートするサーバーは、maxWidthまたはmaxAreaを指定しなければなりません(must)(技術プロパティーを参照)。

サポートされている機能、フォーマット、品質の集合は、外部プロファイル・ドキュメントで宣言されているものと、extraQualities、extraFormats、およびextraFeaturesのプロパティーで追加されたものの和集合です。機能が、プロファイル・ドキュメントにもextraFeaturesプロパティーにも存在していなければ、クライアントは、その機能はサポートされていないと見なさなければなりません(must)。

extraQualities、extraFormats、extraFeaturesのプロパティーで用いられる追加の文字列、またはこの仕様では定義していない、画像情報で用いられる追加のプロパティーは、追加のコンテキスト・ドキュメントを用いてRDFの述語にマッピングすべきです(should)。これらの拡張は、最上位の@contextプロパティーに追加すべきです(should)(技術プロパティーを参照)。スコープ付きコンテキストとして知られている、述語固有のコンテキスト定義のJSON-LD 1.1の機能を用いて、拡張間の衝突を最小限に抑えなければなりません(must)。コミュニティーでの利用を目的とした拡張は、拡張レジストリに登録すべきですが(should)、登録は必須ではありません。

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "extraFormats": [ "gif", "pdf" ],
  "extraQualities": [ "color", "gray" ],
  "extraFeatures": [ "canonicalLinkHeader", "rotationArbitrary", "profileLinkHeader" ]
}

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

JSONの応答には、ビューアで追加機能を提供するサービスなど、外部資源を参照するリンク付けプロパティーを含むことができます(may)。リンク付けプロパティーは、プレゼンテーションAPIと同じセマンティクスと要件を持っています。

partOf、seeAlso、およびserviceのJSONオブジェクトには、次の表で示すプロパティーがあります。

{
  "@context": [
    "http://iiif.io/api/image/3/context.json"
  ],
  "id": "https://example.org/image-service/abcd12345/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "seeAlso": [
    {
      "id": "https://example.org/image1.xml",
      "label": { "en": [ "Technical image metadata" ] },
      "type": "Dataset",
      "format": "text/xml",
      "profile": "https://example.org/profiles/imagedata"
    }
  ],
  "partOf": [
    {
      "id": "https://example.org/manifest/1",
      "type": "Manifest",
      "label": { "en": [ "A Book" ] }
    }
  ],
  "service": [
    {
      "@id": "https://example.org/auth/login",
      "@type": "AuthCookieService1",
      "profile": "http://iiif.io/api/auth/1/login",
      "label": "Login to Example Institution"
    }
  ]
}

5.9. 完全な応答

以下に、すべての必須プロパティーとオプションのプロパティーを含んだ画像情報の応答を示します。

{
  "@context": [
    "http://example.org/extension/context1.json",
    "http://iiif.io/api/image/3/context.json"
  ],
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level1",
  "width": 6000,
  "height": 4000,
  "maxWidth": 3000,
  "maxHeight": 2000,
  "maxArea": 4000000,
  "sizes": [
    { "width": 150, "height": 100 },
    { "width": 600, "height": 400 },
    { "width": 3000, "height": 2000 }
  ],
  "tiles": [
    { "width": 512, "scaleFactors": [ 1, 2, 4 ] },
    { "width": 1024, "height": 2048, "scaleFactors": [ 8, 16 ] }
  ],
  "rights": "http://rightsstatements.org/vocab/InC-EDU/1.0/",
  "preferredFormats": [ "png", "gif"],
  "extraFormats": [ "png", "gif", "pdf" ],
  "extraQualities": [ "color", "gray" ],
  "extraFeatures": [ "canonicalLinkHeader", "rotationArbitrary", "profileLinkHeader" ],
  "service": [
    {
      "id": "https://example.org/service/example",
      "type": "Service",
      "profile": "https://example.org/docs/example-service.html"
    }
  ]
}

6. 準拠レベルとプロファイル・ドキュメント

画像情報ドキュメントは、profileプロパティーの値として準拠レベルを含めることで、APIがサポートされている範囲を指定しなければなりません(must)。準拠レベルは、画像API準拠ドキュメントに列挙されており、以下の表で示しているもののうちの1つでなければなりません(must)。準拠レベルは、すべての要件が満たされる最も高い準拠レベルであるべきです(should)。 準拠レベルはそれぞれ、画像情報の項で論じているように、そのレベルに必要な一連の機能を記述するプロファイル・ドキュメントに対応しています。サーバーは、様々な識別子を持つ画像に様々な準拠レベルを宣言できます(may)。

準拠レベルは、画像と画像情報の両方の応答において、rel="profile"というパラメータのプロファイル・ドキュメントのURIを用いて、HTTP Linkヘッダー(RFC5988)で提供することもできます。完全なヘッダーは次のようなものでありえます。

Link: <http://iiif.io/api/image/3/level1.json>;rel="profile"

このヘッダーをApacheのHTTPサーバーで設定するための秘訣は、Apache HTTPサーバー実装ノートで示されています。

7. サーバー応答

サーバーは、画像API資源の検索用にHTTP GETメソッドをサポートしなければなりません(must)。サーバーはCORSのプリフライト・リクエストのパターンの一部としてHTTP OPTIONSメソッドをサポートすべきであり(should)、実装でHTTP HEADメソッドもサポートすることをお勧めします(recommended)。

7.1. CORS

サーバーは、Access-Control-Allow-Originヘッダーやプリフライト・リクエストのパターンなど、CORS仕様の関連要件に従うことにより、画像API資源の再利用をサポートすべきです(should)。これらの挙動を可能とするための秘訣は、Apache HTTPサーバー実装ノートで提供されています。

7.2. 成功の応答

リクエストがうまく処理された時には、サーバーは200(成功)または3xx(リダイレクト)のステータス・コードでHTTP応答を送信できます。ステータス・コードが200の時のエンティティ・ボディは、リクエストされた画像または情報ドキュメントでなければなりません(must)。ステータス・コードが301、302、303または304の時のエンティティ・ボディには制限はありませんが、空であることが推奨されます(recommended)。ステータス・コードが301、302または303の時は、Location HTTPヘッダーにリクエストを満たす画像のURIを含むように設定しなければなりません(must)。これにより、サーバーが正規のURIを1つ持つことができ、応答のキャッシュが促進されます。ステータス・コード304は、HTTPの仕様どおりに処理されます。クライアントは、これらのすべての状況に遭遇するものと想定すべきで(should)、初期応答のエンティティ・ボディに必ず画像データが含まれていると想定してはなりません(must not)。

7.3. エラー状況

サーバーがリクエストを解析し、エラーを検出する順序は規定していません。リクエストは、最初のエラーに遭遇した時に失敗となる可能性が高く、下記リストで提供している一般的なコードを用いて適切なHTTPステータス・コードを返します。エラー応答の本文に、人間が読めるエラーの記述がプレーン・テキストかhtmlのいずれかで含まれていることが推奨されます(recommended)。

7.4. HTTPのバージョン

同じクライアントからの多数の同時リクエストに応答する必要性が予測される実装では、接続の開閉の繰り返しを回避するために、HTTP/2を介してAPIを使用できるようにすべきです(should)。これにより、HTTP 1.1を介したサイトごとの同時接続数に関するブラウザの制限も回避されます。

8. 認証

一般的に、画像はウェブ・ページやアプリケーションの二次資源です。ウェブ・ページの場合、画像はHTMLのimgタグに組み込まれており、HTTPリクエストを追加することで読み出されます。ユーザがウェブ・ページを読み込むことができない時には、ユーザを別のページにリダイレクトし、認証の機会を提供することができます — そして、これは一般的に受け入れられている挙動です。画像などの二次資源の場合にはこれはできず、ユーザには壊れた画像アイコンが提供されるだけです。

新たな認証メカニズムも、承認ビジネス・ロジックに対する役割も提案しません。代わりに、認証の要件とプロセスは、IIIF固有のコンテキストの外であっても、IIIFに対応したアクセス管理ワークフロー内で処理されることが期待されます。IIIF認証仕様を参照してください。

9. URIのエンコーディングとデコーディング

このAPIのURI構文は、エンコードしてはならない(must not)スラッシュ(/)区切り記号に依存しています。クライアントは、特殊文字(下記のto-encodeの集合： パーセントとRFC3986のコロンを除くgen-delims)と、リクエストのコンポーネント内のUS-ASCII集合以外の文字をパーセント・エンコードしなければなりません(must)。例えば、URIの識別子部分に含まれているあらゆるスラッシュをパーセント・エンコードしなければなりません(must)。その他のコンポーネントには特殊文字が含まれていないため、エンコーディングは識別子にのみ必要です。他の文字をパーセント・エンコードしても曖昧さは生じませんが、必要性がないのです。

to-encode = "/" / "?" / "#" / "[" / "]" / "@" / "%"

任意のエンコードが行われた識別子を処理できないサーバーは、クライアントが文字のエンコードを全く行わないと思われる画像識別子のみを提供するように最善を尽くすべきで(should)、したがって、識別子の文字を、文字、数、下線文字に制限することが推奨されます(recommended)。

10. セキュリティに関する留意点

このAPIは、そのコンポーネントに関連するURI構文とセマンティクスを定義しています。URIの構成には、URI内の機密情報の露出やユーザの閲覧／表示行動の漏洩の可能性を除き、セキュリティに関する留意事項はほとんどありません。

このAPIを実施するサーバ・アプリケーションは、DoS攻撃や、DNS偽装による認証脆弱性の可能性を考慮すべきです。アプリケーションは、オーバーフロー攻撃、インジェクション攻撃やディレクトリ・トラバーサル攻撃を避ける方法で、慎重に受信リクエスト(URI)の解析・サニタイズを行わなければなりません。

早期のURIのサニティー・チェック(長さ、末尾のGET、不正な文字、範囲外のパラメータ)と、適切な応答コードを用いた拒絶を推奨します(recommended)。

11. 付録

A. バージョン付け

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

B. 謝辞

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

C. 変更履歴