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

Copyright © 2012-2016 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. 正規URI構文
• 5. 画像情報
  • 5.1. 画像情報リクエスト
  • 5.2. 技術プロパティー
  • 5.3. プロファイル記述
  • 5.4. 権利・ライセンス・プロパティー
  • 5.5. 関連サービス
  • 5.6. 完全な応答
• 6. 準拠レベル
• 7. サーバー応答
  • 7.1. 成功の応答
  • 7.2. エラー状況
• 8. 認証
• 9. URIのエンコーディングとデコーディング
• 10. セキュリティに関する留意点
• 11. 付録
  • A. 実装ノート
  • B. バージョン付け
  • C. 謝辞
  • D. 変更履歴

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

このドキュメントの「しなければならない(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}

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

http://www.example.org/image-service/abcd1234/full/full/0/default.jpg

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

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

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

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

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

http://www.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に対する表現として返されます。画像と領域の大きさのピクセル数は、常に整数数で表されます。計算途中には浮動小数点数を使用でき、端数の処理方法は実装固有です。一部のパラメータ(特にパーセンテージ)は浮動小数点数で指定できます。これらは最大10桁の10進数で、10進数と、1.0未満の場合には0で始まる「.」が付いた数字のみであるべきです。

4.1. 領域

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

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

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

例:

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

4.2. サイズ

size(サイズ)パラメータは、抽出される領域が拡大・縮小されるべき大きさを決定します。

結果として得られる高さや幅が0であれば、サーバーは400(不正リクエスト)のステータス・コードを返すべきです(should)。

画像サーバーは、抽出される領域のフル・サイズを超える拡大・縮小をサポートできます(may)。

非推奨に関する注意
maxの方が望ましいと考え、sizeのfullというキーワードは、バージョン3.0で置き換えられる予定です。iiif-discussやGithub issueでのフィードバックを歓迎します。

例:

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

4.3. 回転

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

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

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

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

例:

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

4.4. 品質

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

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

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

例:

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

4.5. フォーマット

返される画像フォーマットは、URI末尾の拡張子として表されます。

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

例:

1. .../full/full/0/default.jpg
2. .../full/full/0/default.png
3. .../full/full/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. 正規URI構文

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

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

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

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

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

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

5. 画像情報

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

5.1. 画像情報リクエスト

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

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

応答の構文はJSON-LDです。応答のコンテンツ・タイプは「application/json」(通常のJSON)か、

Content-Type: application/json

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

Content-Type: application/ld+json

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

サーバーは、情報リクエストに対する応答において、*という値で、Access-Control-Allow-Originヘッダーを送るべきです(should)。以下に構文を示しており、CORS仕様で記述しています。様々なサーバーで提供されるウェブ・アプリケーションでJSONの応答を使用できるようにするためには、このヘッダーが必要です。

Access-Control-Allow-Origin: *

これらの挙動を可能とするための秘訣は、Apache HTTPサーバー実装ノートで提供されています。

5.2. 技術プロパティー

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

注意
sizesリストの仕様と正規URI構文の間には矛盾があります。クライアントは、sizesのエントリーに基づいて画像リクエストを行う時には、正規URI構文を用いるべきです(should)。最大限の互換性を確保するために、サーバーは、縦横比を維持したsizesの値に対し、sizeパラメータのw,とw,hの形式をどちらもサポートすべきです(should)。この矛盾については、この仕様の次のメジャー・バージョンで対応します。

tilesリスト内のオブジェクトは、以下の表のプロパティーを持っています。領域パラメータはwidthとheightで記述し、画像URLのサイズ・パラメータにはscaleFactorsを記入すべきです。これに関しては実装ノートで詳細に説明しています。

タイルのwidth、またはheightが指定されている時のwidthとheightの組み合わせは、tilesリストのメンバー内で一意でなければなりません(must)。

サーバーは、サポートされている品質とフォーマットのすべての組み合わせに対し、sizesとtilesフィールドで指定されているパラメータを持つ画像に対するリクエストをサポートすべきです(should)。

下記は、オプションのsizesとtilesのプロパティーを含む、有効な画像情報応答を示しています。

{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id" : "http://www.example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "protocol" : "http://iiif.io/api/image",
  "width" : 6000,
  "height" : 4000,
  "sizes" : [
    {"width" : 150, "height" : 100},
    {"width" : 600, "height" : 400},
    {"width" : 3000, "height": 2000}
  ],
  "tiles": [
    {"width" : 512, "scaleFactors" : [1,2,4,8,16]}
  ],
  "profile" : [ "http://iiif.io/api/image/2/level2.json" ]
}

5.3. プロファイル記述

画像にサポートされる追加の機能を指定するために、プロファイル・オブジェクトをprofileリストに追加できます。profileリスト内のオブジェクトは、以下の表のプロパティーを持っています。プロファイルがURIから逆参照される場合には、@context、@id、@typeのプロパティーは必須ですが(required)、これらを画像情報の応答に含めるべきではありません(should not)。

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

画像プロファイルのsupportsプロパティーで指定できる機能は次のとおりです。

非推奨に関する注意
sizeByWhListedおよびsizeByForcedWhという機能名の使用は非推奨となりました。これらの名前はバージョン3.0.で削除される予定です。sizeByForcedWhはバージョン2.0で矛盾して定義されました。また、sizeByWhListedは、画像情報ドキュメントにサイズを記述することで暗示されるため、名前付き機能としての必要性はありません。

sizeByWhとsizeByDistortedWhの機能は、サイズパラメータに対し同じ「w,h」という構文を共有していますが、それらは別個の機能を表します。sizeByWhはサポートしているけれどもsizeByDistortedWhはサポートしていないサーバーは、あらゆる拡大・縮小サイズで画像応答を提供しますが(存在していれば、別々のmaxWidth、maxHeight、maxArea、sizeAboveFullの制約の対象)、それは、結果として得られる画像が元の縦横比を保持している場合に限られます。歪んだ画像に対するリクエストに対する応対は行われません。

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

サポートされている機能、フォーマット、品質の集合は、すべての外部プロファイル・ドキュメントで宣言されているものと、組み込みプロファイル・オブジェクトとの和集合です。機能が、組み込みプロファイルのプロファイル・ドキュメントにもsupportsプロパティーにも存在していなければ、クライアントは、その機能はサポートされていないと見なさなければなりません(must)。

formats、qualities、supportsのいづれかに、参照されている準拠レベルで規定されている以外の値がなければ、プロパティーは、空リストとして存在するのではなく、応答から削除されるべき(should)です。

プロファイルのsupportsリストにURIを追加して、この仕様で定義されていない機能をカバーすることができます(may)。クライアントは、認識されないURIを無視しなければなりません(must)。

下記のフラグメントは、レベル2の準拠を超える追加のフォーマット、品質、機能に対するサポートを示すプロファイルです。これにはサイズの限界も含まれています。

{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id" : "http://www.example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "protocol" : "http://iiif.io/api/image",
  //...
  "profile" : [
    "http://iiif.io/api/image/2/level2.json",
    {
      "formats" : [ "gif", "pdf" ],
      "qualities" : [ "color", "gray" ],
      "maxWidth" : 2000,
      "supports" : [
          "canonicalLinkHeader", "rotationArbitrary", "profileLinkHeader", "http://example.com/feature/"
      ]
    }
  ]
}

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

attribution、license、logoという権利とライセンスのプロパティーは、プレゼンテーションAPIと同じセマンティクスと要件を持っています。

すべての権利およびライセンスのプロパティーは、JSON配列で表された値を複数または1つ持つことができます(may)。

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

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

logoプロパティーの値は、画像のURLが含まれている文字列、または、ロゴ画像とロゴに対するIIIF画像APIサービスの両方のURIを示すJSONオブジェクトでありえます。可能ではあるものの、IIIFサービスのロゴ自身がロゴを持たないことが推奨されます(recommended)。ロゴを持つロゴに遭遇したクライアントは、無限である可能性がある集合を表示する必要はありません。

画像APIとプレゼンテーションAPIの両方でattributionやlogoが表されている場合は、それらが同一のものでない限り、クライアントはその両方を表示しなければなりません(must)。

下記は、これらのそれぞれのプロパティーのシンプルな使用例です。

{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id" : "http://www.example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "protocol" : "http://iiif.io/api/image",
  // ...
  "attribution" : "Provided by Example Organization",
  "logo" : "http://example.org/images/logo.png",
  "license" : "http://example.org/rights/license1.html"
  // ...
}

完全な応答の例で、より複雑な例を提供しています。

5.5. 関連サービス

画像と関連付けられたサービスが1つ以上存在できます(may)。詳細についてはサービス・プロファイルの付録を参照してください。

下記は、画像にアクセスするためにユーザが通過しなければならない認証システムのログイン・ページと連携するためのserviceの使用例です。詳細については、認証を参照してください。

{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id" : "http://www.example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "protocol" : "http://iiif.io/api/image",
  // ...
  "service": {
    "@context" : "http://iiif.io/api/auth/0/context.json",
    "@id" : "http://www.example.org/auth/login.html",
    "profile": "http://iiif.io/api/auth/0/login"
  }
}

完全な応答の例で、より複雑な例を提供しています。

5.6. 完全な応答

下記は、すべての必須とオプションの画像情報プロパティーが含まれている応答を示しています。

{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id" : "http://www.example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "protocol" : "http://iiif.io/api/image",
  "width" : 6000,
  "height" : 4000,
  "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]}
  ],
  "attribution" : [
    {
      "@value" : "<span>Provided by Example Organization</span>",
      "@language" : "en"
    },{
      "@value" : "<span>Darparwyd gan Enghraifft Sefydliad</span>",
      "@language" : "cy"
    }
  ],
  "logo" : {
      "@id" : "http://example.org/image-service/logo/full/200,/0/default.png",
      "service" : {
        "@context" : "http://iiif.io/api/image/2/context.json",
        "@id" : "http://example.org/image-service/logo",
        "profile" : "http://iiif.io/api/image/2/level2.json"
      }
  },
  "license" : [
    "http://example.org/rights/license1.html",
    "https://creativecommons.org/licenses/by/4.0/"
  ],
  "profile" : [
    "http://iiif.io/api/image/2/level2.json",
    {
      "formats" : [ "gif", "pdf" ],
      "qualities" : [ "color", "gray" ],
      "supports" : [
        "canonicalLinkHeader", "rotationArbitrary", "profileLinkHeader", "http://example.com/feature/"
      ]
    }
  ],
  "service" : [
    {
      "@context": "http://iiif.io/api/annex/service/physdim/1/context.json",
      "profile": "http://iiif.io/api/annex/service/physdim",
      "physicalScale": 0.0025,
      "physicalUnits": "in"
    },{
      "@context" : "http://geojson.org/contexts/geojson-base.jsonld",
      "@id" : "http://www.example.org/geojson/paris.json"
    }
  ]
}

6. 準拠レベル

画像情報ドキュメントは、profileプロパティーの最初のエントリーとして準拠レベルURIを含めることで、APIがサポートされている範囲を指定しなければなりません(must)。このURIは、すべての要件を満たす最も高い準拠レベルの記述にリンクされています。URIは、画像API準拠ドキュメントで列挙されているものの1つでなければなりません(must)。画像情報の項で論じているとおり、この記述には、プロファイルに必要な機能の集合が含まれています。サーバーは、様々な識別子を持つ画像に様々な準拠レベルを宣言できます(may)。

準拠レベルURIは、HTTP Linkヘッダー(RFC5988)のrel="profile"というパラメータで提供することもできます(may)。例えば、完全なヘッダーは次のようになるかもしれません。

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

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

7. サーバー応答

7.1. 成功の応答

リクエストがうまく処理された時には、サーバーは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.2. エラー状況

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

8. 認証

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

新たな認証メカニズムも、承認ビジネス・ロジックに対する役割も提案しません。代わりに、認証の要件とプロセスは、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)の解析・サニタイズを行わなければなりません。

恣意的に大きな画像リクエスト(ひいてはサーバーをDoS攻撃にさらす)を防止するために、sizeAboveFull機能を実装しているサーバーは、maxWith、maxHeight、maxAreaのうちの1つまたはそれ以上も実装することが推奨されます。

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

11. 付録

A. 実装ノート

• 画像の保存を可能にするユースケースでは、HTTP Content-Dispositionヘッダー(RFC6266)を用いて、提供された識別子とパラメータに基づいて画像識別用の使いやすいファイル名を提供することをお勧めします(recommended)。
• サーバー実装は、PythonのWSGIなどのURIパスをアンエスケープするコンポーネントまたは枠組に依存することができます。そのような状況では、サーバーがリクエストを処理するAPIパラメータと接頭辞の知識があれば、リクエストされたURIは、スラッシュが含まれている可能性がある識別子を処理するために、右から解析できます。
• 認証が完了したかどうかに関わらず、この仕様は、リクエストされた画像やその他の記述メタデータの権利ステータスに関する言明は行いません。権利およびその他の情報に関しては、IIIFプレゼンテーションAPIを参照してください。
• さらにApache HTTPサーバー実装ノートも提供されています。
• リンクト・データの実装では、JSON-LDフレーミング実装ノートで提供されているフレームを用いてinfo.json応答を構築できます。
• w,という正規構文でサイズをリクエストする時に、特定の高さを希望する場合には、以下のアルゴリズムを使用できます。

    # Calculate request width for `w,` syntax from desired height
    request_width = image_width * desired_height / image_height

• フル画像が拡大・縮小されるタイル・サイズの倍数ではない場合には、画像タイルをリクエストする時に、右端と下端の部分的なタイルを考慮に入れて領域とサイズのパラメータを算出しなければなりません。下記のアルゴリズムは、Pythonコードで示しており、終始、インプットと演算は整数を想定しています(つまり、除算では余りを切り捨て)。インプットは、フル画像コンテンツのサイズ(width,height)、倍率s、タイル・サイズ(tw,th)、および左上の角の(0,0)から数えたタイル座標(n,m)です。数の丸め方が実装依存であることに注意してください。

    # Calculate region parameters /xr,yr,wr,hr/
    xr = n * tw * s
    yr = m * th * s
    wr = tw * s
    if (xr + wr > width):
        wr = width - xr
    hr = th * s
    if (yr + hr > height):
        hr = height - yr
    # Calculate size parameters /ws,hs/
    ws = tw
    if (xr + tw*s > width):
        ws = (width - xr + s - 1) / s  # +s-1 in numerator to round up
    hs = th
    if (yr + th*s > height):
        hs = (height - yr + s - 1) / s

• 回転において説明したとおり、リクエストされた画像コンテンツのサイズを確保するために、回転によって、返される画像の幅と高さは変わるでしょう。与えられている最初のサイズと回転に対して、返される画像の大きさを算出するための式を下記に示しています。数の丸め方が実装依存であり、一部の言語では、角度を度からラジアンに変換する必要があることに注意してください。

    # (w,h) are size parameters, n is rotation angle
    w_returned = abs(w*cos(n)) + abs(h*sin(n))
    h_returned = abs(h*cos(n)) + abs(w*sin(n))

B. バージョン付け

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

C. 謝辞

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

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

D. 変更履歴