Documents‎ > ‎Open Search‎ > ‎

Open Search 仕様書 1.1 ドラフト4版

この文書は、OpenSearch 1.1 Draft 4 Specificationを和訳したものです。
この文書は、原文と同様、Creative Commons Attribution-ShareAlike 2.5 Licenseの元で公開されます。
文書名Open Search 仕様書 1.1 ドラフト4版
原文OpenSearch 1.1 Draft 4 Specification
和訳者塚本 牧生 <tsukamoto@gmail.com>
ライセンスCreative Commons Attribution-ShareAlike 2.5 License（原文に準拠）

Contents

注意 

こればパブリック・レビューのためのドラフトドキュメントです。

概要

このドキュメントはOpenSearch description document（記述文書）、OpenSearch Query element（クエリ要素）、OpenSearch URL template syntax（テンプレートシンタックス）、そしてOpenSearch response element（レスポンス要素）を定義します。これらのフォーマット全体を、"OpenSearch 1.1"または単に"OpenSearch"として参照できるものとします。

検索クライアントは、OpenSearch description document（記述文書）を検索エンジンの公共的なインターフェースについて学ぶために使うでしょう。この記述文書はクライアントが検索リクエストをどう作れば良いかを示すパラメータ化されたURLのテンプレートを含みます。検索エンジンは様々なコンテンツ形式で検索メタデータを結果に加えうるのに、OpenSearchレスポンス要素を使うことができます。

名前空間

この仕様に記述されたXMLデータフォーマットのXML名前空間（XML Namespaces URI）は:

http://a9.com/-/spec/opensearch/1.1/

OpenSearch description document

概要

OpenSearch description document（記述文書）は検索エンジンのWebインターフェースの記述に使われます。

例（Examples）

シンプルなOpenSearch description documentの例: 

 <?xml version="1.0" encoding="UTF-8"?>
 <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
   <ShortName>Web Search</ShortName>
   <Description>Use Example.com to search the Web.</Description>
   <Tags>example web</Tags>
   <Contact>admin@example.com</Contact>
   <Url type="application/rss+xml" 
        template="http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss"/>
 </OpenSearchDescription>

詳細なOpenSearch description documentの例: 

 <?xml version="1.0" encoding="UTF-8"?>
 <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
   <ShortName>Web Search</ShortName>
   <Description>Use Example.com to search the Web.</Description>
   <Tags>example web</Tags>
   <Contact>admin@example.com</Contact>
   <Url type="application/atom+xml"
        template="http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom"/>
   <Url type="application/rss+xml"
        template="http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=rss"/>
   <Url type="text/html" 
        template="http://example.com/?q={searchTerms}&amp;pw={startPage?}"/>
   <LongName>Example.com Web Search</LongName>
   <Image height="64" width="64" type="image/png">http://example.com/websearch.png</Image>
   <Image height="16" width="16" type="image/vnd.microsoft.icon">http://example.com/websearch.ico</Image>
   <Query role="example" searchTerms="cat" />
   <Developer>Example.com Development Team</Developer>
   <Attribution>
     Search data Copyright 2005, Example.com, Inc., All Rights Reserved
   </Attribution>
   <SyndicationRight>open</SyndicationRight>
   <AdultContent>false</AdultContent>
   <Language>en-us</Language>
   <OutputEncoding>UTF-8</OutputEncoding>
   <InputEncoding>UTF-8</InputEncoding>
 </OpenSearchDescription>

タイプ（Type）

OpenSearch description documents配下のタイプで参照されます:

application/opensearchdescription+xml

このタイプのJANA登録は保留中です。

拡張性（Extensibility）

OpenSearch description documentは、すべてコアOpenSearchフォーマットのものと異るXML名前空間に明示的に関連付けられた外部要素と属性で提供される外部マークアップで拡張することができます。可能であれば、外部XML名前空間URIは、それが拡張の趣旨とフォーマットを示すドキュメントを解決すべきです。クライアントは認識できない外部マークアップに出会った際、マークアップがなかったかのように処理を続けるべきです。

OpenSearch記述要素（OpenSearch description elements）

"OpenSearchDescription"要素

OpenSearch description documentのルート要素。

親要素: なし
条件: この要素はドキュメントのルート要素としてきっかり1回だけ登場しなければなりません。

例: 

 <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
    <!--- ... --->
 </OpenSearchDescription>

"ShortName"要素

このサーチエンジンを識別する人間向け（human-readable）の簡潔なタイトルを持たせます。

親要素: OpenSearchDescription
制限: この値は16文字あるいはそれ以下からなるプレーンテキストでなければなりません。この値にHTMLあるいはその他のマークアップを含めてはいけません。
条件: この要素はきっかり1回だけ登場しなければなりません。

例: 

 <ShortName>Web Search</ShortName>

"Description"要素

このサーチエンジンの人間向けの簡潔な説明文をタイトルを持たせます。

親要素: OpenSearchDescription
制限: この値は1024文字あるいはそれ以下からなるプレーンテキストでなければなりません。この値にHTMLあるいはその他のマークアップを含めてはいけません。
条件: この要素はきっかり1回だけ登場しなければなりません。

例: 

 <Description>Use Example.com to search the Web.</Description>

"Url"要素

クライアントが、検索結果や検索のサジェスト、追加のdescription documentといった外部リソースのリクエストを作れるようにするためのインターフェースを記述します。

親要素: OpenSearchDescription
属性:
template - URLテンプレートはOpenSearch URLテンプレートシンタックスにしたがって処理されます。
条件: この属性は必須です。
type - リソースのMIMEタイプが記述されます。
制限: この値は妥当なMIMEタイプでなければなりません。
条件: この属性は必須です。
rel - ドキュメント記述との関連におけるリソースの役割が記述されます。
制限: relの値として適切なトークンを、空白文字区切りのリストとして含めます。許可されるrelの値についてはUrl relの値の使用を参照してください。
デフォルト: "results"
条件: この属性は任意です。
indexOffset - 検索結果の最初のインデックス番号。
制限: この値は整数（integer）でなければなりません。
デフォルト: "1"。
条件: この属性は任意です。
pageOffset - 検索結果セットの最初のページ番号。
制限: この値は整数でなければなりません。
デフォルト: "1"
条件: この属性は任意です。
条件: この要素はきっかり1回またはそれ以上登場しなければなりません。

HTML検索結果のリクエストを記述したURL要素の例: 

 <Url type="text/html"
      template="http://example.com/search?q={searchTerms}&amp;pw={startPage?}" />

要素のインデックスは0から始まる、RSSによる検索結果のリクエストを記述したURL要素の例:

 <Url type="application/rss+xml"
      indexOffset="0"
      rel="results"
      template="http://example.com/?q={searchTerms}&amp;start={startIndex?}&amp;format=rss" />

JSONによる検索サジェストのリクエストを記述したURL要素の例:

 <Url type="application/json"
      rel="suggestions"
      template="http://example.com/suggest?q={searchTerms}" />


OpenSearch description documentそれ自体をリフレッシュするリクエストを記述したURL要素の例: 

 <Url type="application/opensearchdescription+xml"
      rel="self"
      template="http://example.com/osd.xml" />
Url relの値

Rel属性文字列は、1つまたは複数のセマンティック上重要（semantically meaningful）なrel値のトークンの、空白文字区切りのリストです。クライアントはrel属性値が空の時はrel属性が全くないものとして取り扱います。

もしクライアントがいずれかのrel値のトークンのセマンティックな意味を受け入れられない時は、クライアントはそれを含むURLを無視すべきです。

Rel値のトークンは完全修飾（fully qualified）トークン（例えば"http://example.com/rel#foo"）でも、あるいは完全修飾ではない（unqualified）トークン（例えば"results"）でも構いません。

完全修飾トークンは全て、妥当なURLでなければなりません。完全修飾のセマンティックな意味はこの仕様のスコープ外ですが、しかし慣例的にはこのURLは関係性を記述したリソースを示すものと決められています。

完全修飾ではないトークンはすべて、[a-z][a-z\-]+の形の英数小文字からなる文字列でなければなりません。以下に列記されたトークンだけがこの仕様書での定義上意味を持ちます。

Relの値:

"results" (default)
特定の形式での検索結果を求めるリクエストを表します。
"suggestions"
特定の形式での検索サジェスチョンを求めるリクエストを表します。これ以上の詳細はOpenSearch Suggestions拡張を参照してください。
"self"
このdescription documentの正規URLを表します。
"collection"
リソースセットのリクエストを表します。

"Contact"要素

description documentの管理者（maintainer）に届くemailアドレスをもたせます。

親要素: OpenSearchDescription
制限: この値は RFC 2822 のセクション3.4.1 "Addr-spec specification"に適合しなければなりません。
条件: この要素は0、または1回登場します。

例:

 <Contact>admin@example.com</Contact>

"Tags"要素

この検索コンテンツの識別およびカテゴライズのためのキーワードとして使われる単語のセットを持たせます。タグは一語でなくてはならず、空白文字(' ')で区切られます。

親要素: OpenSearchDescription
制限: この値は256文字あるいはそれ以下からなるプレーンテキストでなければなりません。この値にHTMLあるいはその他のマークアップを含めてはいけません。
条件: この要素は0、または1回登場します。

例: 

 <Tags>example web</Tags>

"LongName"要素

このサーチエンジンを識別する人間向け（human-readable）のより長いタイトルを持たせます。

検索クライアントは、この要素がない時にはShortName要素の値を使用すべきです。

親要素: OpenSearchDescription
制限: この値は48文字あるいはそれ以下からなるプレーンテキストでなければなりません。この値にHTMLあるいはその他のマークアップを含めてはいけません。
条件: この要素は0、または1回登場します。

例: 

 <LongName>Example.com Web Search</LongName>

"Image"要素

この検索コンテンツに関連付けて使用できる画像のロケーションを識別するURLを持たせます。

検索クライアントに画像サイズをヒントとして提示することができます。検索クライアントは、検索クライアントは利用可能なスペースにもっとも適した画像を選択し、OpenSearch description documentにリストされたうち最初のものを優先するべきです。縦横比を保つことを推奨します。可能であれば、検索エンジンは"image/x-icon" か"image/vnd.microsoft.icon"（ Microsoft ICON format ）タイプの16x16の画像と、"image/jpeg"か"image/png"タイプの64x64の画像を用意すべきです。

親要素: OpenSearchDescription
属性:
height - この画像の高さを、ピクセルで、持たせます。
制限: 値は負ではない整数値でなければなりません。
条件: この属性は任意です。
width - この画像の幅を、ピクセルで、持たせます。 
制限: 値は負ではない整数値でなければなりません。
条件: この属性は任意です。
type - この画像のMIMEタイプを持たせます。
制限: この値は妥当なMIMEタイプでなければなりません。
条件: この属性は任意です。
制限: この値はURIでなければなりません。
条件: この要素は0、1、またはそれ以上の回数出現します。

例: 

 <Image height="16" width="16" type="image/x-icon">http://example.com/favicon.ico</Image>
 
 <Image height="64" width="64" type="image/png">http://example.com/websearch.png</Image>

"Query"要素

検索クライアントが実行できる検索クエリを定義します。詳細な情報はOpenSearch Query element仕様を参照してください。

OpenSearch decription documentはOpenSearch OpenSearch description documentsは、検索結果を返すと予想されるtype="example"のクエリ要素を、少なくとも一つは含むべきです。検索クライアントは、このクエリ例を検索エンジンが正しく動作しているか確認するために使うことができます。

親要素: OpenSearchDescription
条件: この要素は0またはそれ以上の回数出現します。

例: 

 <Query role="example" searchTerms="cat" />

"Developer"要素

この記述文書の作成者またはメンテナの、人間向けの識別しまたは名前を持たせます。

developerはこの記述文書を作成した個人またはエンティティで、コンテント自身のオーナ、作者、著作権ほゆうしゃであるかもしれませんし、そうでないかもしれません。

親要素: OpenSearchDescription
制限: この値は64文字あるいはそれ以下からなるプレーンテキストでなければなりません。この値にHTMLあるいはその他のマークアップを含めてはいけません。
条件: この要素は0または1回登場します。

例: 

 <Developer>Example.com Development Team</Developer>

"Attribution"要素

検索フィードに含まれるコンテンツの帰属する全てのソースまたはエンティティのリストを持たせます。

親要素: OpenSearchDescription
制限: この値は256文字あるいはそれ以下からなるプレーンテキストでなければなりません。この値にHTMLあるいはその他のマークアップを含めてはいけません。
条件: この要素は0または1回登場します。

例: 

 <Attribution>Search data copyright Example.com, Inc.</Attribution>

"SyndicationRight"要素

この検索エンジンが提供する検索結果について、問合せ可否、表示可否、再配布可否の程度を示す値を持たせます。

親要素: OpenSearchDescription
値: この値は以下の文字列の一つを持たなければなりません（大文字、小文字は区別されません）:
"open" -
検索クライアントは検索結果をリクエストできます。
検索クライアントは検索結果をエンドユーザーに表示できます。
検索クライアントは検索結果を他の検索クライアントに送信できます。
"limited" -
検索クライアントは検索結果をリクエストできます。
検索クライアントは検索結果をエンドユーザーに表示できます。
検索クライアントは検索結果を他の検索クライアントに送信することはできません。
"private" -
検索クライアントは検索結果をリクエストできます。
検索クライアントは検索結果をエンドユーザーに表示することはできません。
検索クライアントは検索結果を他の検索クライアントに送信することはできません。
"closed" -
検索クライアントは検索結果をリクエストすることはできません。
デフォルト: "open"
条件: この要素は0または1回登場します。

例: 

 <SyndicationRight>open</SyndicationRight>

"AdultContent"要素

検索結果が成人向け（adult）を意図されたものを含んでいる時にtrueの値がセットされる真偽（boolean）値を持たせます。

"成人向け"コンテンツを制定するユニバーサルに適用できるガイドラインはないので、検索エンジンは検索結果が全ての閲覧者にとって不適切なものを含む可能性がないかを示す努力を誠実に行うべきです。

親要素: OpenSearchDescription
値:
"false"、"FALSE"、"0"、"no"、そして"NO"の値をFALSEとみなします; これ以外の文字列は全てTRUEとみなします。
デフォルト: "false"
条件: この要素は0または1回登場します。

例: 

 <AdultContent>false</AdultContent>

"Language"要素

検索エンジンが指定された言語での検索結果をサポートすることを示す文字列を持たせます。

OpenSearch description document は"Language" 要素を検索エンジンがサポートする言語ごとに持たなければなりません。もし検索エンジンがいずれの言語でのクエリーもサポートするのであれば、OpenSearch description documentは"*"の値を持つLanguage要素を持たなければなりません。検索クライアントはOpenSearch URLテンプレートの"language"テンプレートパラメータで利用可能な言語から選択することができます。

親要素: OpenSearchDescription
制限: この値は RFC 3066 で定義された、 XML 1.0 Language Identification に従ったものでなければなりません。追加事項として、"*"の値は、検索エンジンは検索結果について特定の言語に制限していないことを示します。
デフォルト: "*".
条件: この要素は0、1、またはそれ以上の回数登場します。

例: 

 <Language>en-us</Language>
 
 <Language>*</Language>

"InputEncoding"要素

検索エンジンが指定された文字エンコードでの検索リクエストをサポートすることを示す文字列を持たせます。

OpenSearch description documentは"InputEncoding"要素を検索エンジンがサポートする文字エンコードごとに持たなければなりません。検索クライアントはOpenSearch URLテンプレートの"inputEncoding" template parameterを、現在の検索リクエストで利用が要求されているエンコードを識別するのに使用することができます。

親要素: OpenSearchDescription
制限: この値は IANA Character Set Assignments で定義された、 XML 1.0 Character Encodingsに従ったものでなければなりません。
デフォルト: "UTF-8".
条件: この要素は0、1、またはそれ以上の回数登場します。

例: 

 <InputEncoding>UTF-8</InputEncoding>

"OutputEncoding"要素

検索エンジンが指定された文字エンコードでの検索結果をサポートすることを示す文字列を持たせます。

OpenSearch description documentは"OutputEncoding"要素検索エンジンがサポートする文字エンコードごとに持たなければなりません。検索クライアントはOpenSearch URLテンプレートの "outputEncoding" template parameter、この検索結果として選択可能なエンコードを識別するのに使用することができます。

親要素: OpenSearchDescription
制限: この値は IANA Character Set Assignments で定義された、 XML 1.0 Character Encodings に従ったものでなければなりません。
デフォルト: "UTF-8".
条件: この要素は0、1、またはそれ以上の回数登場します。

例: 

 <OutputEncoding>UTF-8</OutputEncoding>

Autodiscovery

OpenSearch description documentsを発行する検索エンジンは、"link"要素を使うことで、検索クライアントがOpenSearchインターフェースを見つけるのを助けることができます。OpenSearchをサポートする検索エンジンは、検索結果の各ページに関連するOpenSearch description documentへの参照を含むべきです。

Autodiscovery in RSS/Atom

RSSおよびAtomドキュメントは RFC 4287 のセクション4.2.7に定められた、Atom 1.0の"link"要素を介して、関連するOpenSearch description documentsを参照することができます。

OpenSearch description documentsを参照する時は、リンク要素の"rel"アトリビュートは、値として"search"を持つべきです。このリレーションの値の、IANAへの登録はペンディングされています。Atomのlink要素の再利用は、ネイティブに匹敵する機能性をサポートする他のシンジケーション形式に関する文脈でも推奨されます。

以下の制限が適用されます:

  • "type"アトリビュートは"application/opensearchdescription+xml"の値を持たなければなりません。
  • "rel"アトリビュートは"search"の値を持たなければなりません。
  • "href"アトリビュートはOpenSearch description documentへのものとして解決できるURIをもたなければなりません。
  • "title"アトリビュートは検索エンジンについて記述した、人間の可読な（human-readable）プレーンテキストの文字列を持つでしょう。

OpenSearch autodiscoveryリンク要素を含むAtomベースの検索結果の例:

 <?xml version="1.0" encoding="UTF-8"?>
 <feed xmlns="http://www.w3.org/2005/Atom" 
       xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
   <!-- ... --->
   <link rel="search"
         href="http://example.com/opensearchdescription.xml" 
         type="application/opensearchdescription+xml" 
         title="Content Search" />
   <!-- ... --->
 </feed>


OpenSearch autodiscoveryリンク要素を含むAtomベースの検索結果の例:

 <?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0" 
      xmlns:atom="http://www.w3.org/2005/Atom">
   <channel>
     <!--- ... --->
     <atom:link rel="search"
                href="http://example.com/opensearchdescription.xml" 
                type="application/opensearchdescription+xml" 
                title="Content Search" />
     <!--- ... --->
   </channel>
 </rss>

Autodiscovery in HTML/XHTML

HTMLおよびXHTMLドキュメントからも、 HTML 4.0 <link/>要素 を介して、関連するOpenSearch description documentsを参照できます。

以下の制限が適用されます:

  • "type"アトリビュートは"application/opensearchdescription+xml"の値を持たなければなりません。
  • "rel"アトリビュートは"search"の値を持たなければなりません。
  • "href"アトリビュートはOpenSearch description documentへのものとして解決できるURIをもたなければなりません。
  • "title"アトリビュートは検索エンジンについて記述した、人間の可読な（human-readable）プレーンテキストの文字列を持つでしょう。
  • HTML <head/>要素は"profile"アトリビュートに"http://a9.com/-/spec/opensearch/1.1/"の値を持たなければなりません。

OpenSearch autodiscoveryリンク要素を含むHTMLドキュメントの例: 

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
   <head profile="http://a9.com/-/spec/opensearch/1.1/">
     <!--- ... --->
     <link rel="search"
           type="application/opensearchdescription+xml" 
           href="http://example.com/content-search.xml"
           title="Content search" />
     <link rel="search"
           type="application/opensearchdescription+xml" 
           href="http://example.com/comment-search.xml"
           title="Comments search" />
     <!--- ... --->
   </head>
   <body>
     <!--- ... --->
   </body>
 </html>

OpenSearch URL template syntax

概要

OpenSearch URLテンプレートフォーマットは、検索エンジンが問合せを受けるためのURLのパラメータ形式を表すために使うことができます。

検索クライアントはURLテンプレートを処理し、一般に{name}の形式で表されるテンプレートパラメータの実体を、問合せ時に決定される値で置き換えようとするでしょう。

デフォルトでは、パラメータ名はOpenSearch 1.1テンプレート名前空間に属しているとみなされ、検索パラメータ名のコアセットの定義はこの仕様で提供されます。しかし、検索エンジンと検索クライアントは、XML名前空間プレフィックス（prefix）の規約に基づく拡張メカニズムを使い、新しいパラメータ名を追加することができます。

例

テンプレートパラメータを含む検索URLテンプレートの例: 

 http://example.com/search?q={searchTerms}

任意のテンプレートパラメータを含む検索URLテンプレートの例: 

 http://example.com/feed/{startPage?}

Url要素のコンテキストで見られる、拡張名前空間の任意のテンプレートパラメータを含む検索URLの例: 

 <Url type="application/rss+xml" 
      xmlns:example="http://example.com/opensearchextensions/1.0/"
      template="http://example.com?q={searchTerms}&amp;c={example:color?}"/>

コンテキスト

この仕様は特に、OpenSearch description documentの"Url"要素のコンテキストでのOpenSearch URLテンプレートシンタックスを参照しています。

テンプレートの文法

OpenSearch URLテンプレートの文法は、以下の RFC 2234 を仕様とする拡張BNF（ABNF）ルールのセットで定義されます。

この文書で定義された文法規則は、Uniform Resource Identifier (URI)として定義されたルールのサブセットとして構築されています: 全体のシンタックスは RFC 3986 です。簡潔にするために、 RFC 3986 にすでに記述されているルールはこの文書ではルール名だけで亜参照され、これらのすべてを改めて記述することはしません。

 ttemplate      = tscheme ":" thier-part [ "?" tquery ] [ "#" tfragment ]
 tscheme        = *( scheme / tparameter )
 thier-part     = "//" tauthority ( tpath-abempty / tpath-absolute / tpath-rootless / path-empty )
 tauthority     = [ tuserinfo "@" ] thost [ ":" tport ]
 tuserinfo      = *( userinfo / tparameter )
 thost          = *( host / tparameter )
 tport          = *( port / tparameter )
 tpath-abempty  = *( "/" tsegment )
 tsegment       = *( segment / tparameter )
 tpath-absolute = "/" [ tsegment-nz *( "/" tsegment ) ]
 tsegment-nz    = *( segment-nz / tparameter )
 tpath-rootless = tsegment-nz *( "/" tsegment )
 tparameter     = "{" tqname [ tmodifier ] "}"
 tqname         = [ tprefix ":" ] tlname
 tprefix        = *pchar
 tlname         = *pchar
 tmodifier      = "?"
 tquery         = *( query / tparameter )
 tfragement     = *( fragement / tparameter )

置換ルール

検索クライアントは検索リクエストを実行する前に、すべてのテンプレートパラメータの実体を置き換えなければなりません。

検索エンジンが、あるテンプレートパラメータが任意で、空文字列で置き換えてよいことを示したければ、任意のテンプレートパラメータセクションで記述されている"?"表記を使うべきです。

パラメータ名

パラメータ名は、任意のパラメータ名プレフィックスと、それに続くローカルパラメータ名から成ります。パラメータ名プレフィックスがある場合、":"文字でローカルパラメータ名と区切られています。すべてのパラメータ名はパラメータ名前空間に関連付けられています。無修飾（Unquolified）のパラメータ名の場合は、このローカルパラメータ名は暗黙的にOpenSearch 1.1名前空間に関連付けられています。完全修飾（Fully Qualified）パラメータ名の場合は、このローカルパラメータはパラメータ名プレフィックスを介して明示的に外部の名前空間に関連付けられています。

パラメータ名の大文字、小文字の区別

パラメータ名プレフィックスとローカルパラメータ名は、どちらも大文字と小文字を区別します。

パラメータ名プレフィックス（prefix）

パラメータ名プレフィックスはローカルパラメータ名をパラメータ名前空間に関連付けます。すべてのパラメータ名プレフィックスは、事前にこれを含む要素かその祖先の要素で XML名前空間 プレフィックスとして宣言されていなければいけません。

プレフィックスの選択はOpenSearch description documentの作成者の裁量です。検索クライアントは固有のプレフィックス文字列定数についてなんの仮定も加えるべきではなく、完全修飾パラメータ名を解析する際には、プレフィックス文字列からXML名前空間宣言へのマッピングを排他的に信頼すべきです。

検索クライアントに全く同じように処理される2つの同等なURLテンプレートの例: 

 <Url type="application/rss+xml" 
      xmlns:a="http://example.com/extensions/"
      template="http://example.com?q={a:localname?}"/>
 
 <Url type="application/rss+xml" 
      xmlns:b="http://example.com/extensions/"
      template="http://example.com?q={b:localname?}"/>

無修飾のパラメータ名

無修飾のパラメータ名はローカルパラメータ名のみから成り、パラメータ名プレフィックスを含みません。OpenSearch URLテンプレート内の無修飾のパラメータ名はOpenSearch 1.1名前空間に暗黙的に関連付けられています。

この仕様はすべての無修飾のOpenSearch 1.1パラメータ名の完全なリストを含んでいます。

無修飾のパラメータ名の例: 

 <Url type="application/rss+xml" 
      template="http://example.com/?q={searchTerms}"/>

完全修飾パラメータ名

完全修飾パラメータ名はパラメータ名プレフィックスと、それに続く":"文字、それに続くローカルパラメータ名から成ります。完全修飾パラメータ名はパラメータ名プレフィックスから特定される、これを含む要素かその祖先の要素にXML名前空間宣言が登場する名前空間に関連付けられます。

完全修飾パラメータ名の例: 

 <Url type="application/rss+xml" 
      xmlns:example="http://example.com/opensearchextensions/1.0/"
      template="http://example.com?f={example:format?}"/>

必須のテンプレートパラメータ

必須のテンプレートパラメータはテンプレートパラメータ修飾子を含まないテンプレートパラメータです。検索クライアントは、デフォルト知がわかっていればそれを使うことはできますが、値として空文字列を使うことはできません。

必須のテンプレートパラメータの例: 

 {searchTerms}

任意のテンプレートパラメータ

任意のテンプレートパラメータは、"?"と等しいテンプレートパラメータ修飾子を含むテンプレートパラメータです。検索クライアントは他につかえる値がない場合には、値として空文字列を使うことができます。

任意のテンプレートパラメータの例: 

 {startPage?}

OpenSearch 1.1パラメータ

以下のローカルパラメータ名が、OpenSearch 1.1名前空間で認識されます。このリストは完全なものです; OpenSearch URLテンプレートでは、以下にリストされたローカルパラメータ名だけが無修飾で現れるでしょう。

検索クライアントはこれらのパラメータ名がOpenSearch URLテンプレート内に現れたときに、適切な値に置き換えられるように準備しておくべきです。

"searchTerms"パラメータ

検索クライアントが要求する一つまたは複数のキーワードで置き換えられます。

制限: この値はURLエンコードされなければいけません。

"count"パラメータ

検索クライアントが要求するページあたりの検索結果の個数で置き換えられます。

検索クライアントは、"count"パラメータの値を検索エンジンが尊重しない可能性を予想し、実際のページサイズを計算する際には"itemsPerPage"レスポンス要素の内容を排他的に信頼すべきです。

制限: この値は負ではない整数（integer）値でなければなりません。

"startIndex"パラメータ

検索クライアントが要求する最初の検索結果のインデックスで置き換えられます。

制限: この値は整数値でなければなりません。
デフォルト: Url要素の内容である"indexOffset"で指定される値。

"startPage"パラメータ

検索クライアントが要求する検索結果のセットのページ番号で置き換えられます。

制限: この値は整数値でなければなりません。
デフォルト: Url要素の内容である"pageOffset"で指定される値。

"language"パラメータ

検索クライアントが要求する検索結果として指定する言語を示す文字列で置き換えられます。

OpenSearch description documentは"Language" element要素を検索エンジンがサポートする言語ごとに持たなければなりません。もし検索エンジンがいずれの言語でのクエリーもサポートするのであれば、OpenSearch description documentは"*"の値を持つLanguage要素を持たなければなりません。OpenSearch URLテンプレートの"language"テンプレートパラメータは、検索クライアントに使用可能な言語からの選択を許すために使うことができます。

制限: この値は RFC 3066 を仕様とする、 XML 1.0 Language Identification に従ったものでなければなりません。追加として、"*"は検索クライアントがどの言語での検索結果でも良いと要求することを示します。
デフォルト: "*"

"inputEncoding"パラメータ

検索クライアントが実行する検索リクエストを指定された文字エンコーディングでエンコードすることを示す文字列で置き換えられます。

OpenSearch description documentは"InputEncoding"要素を検索リクエストとして使用できる文字エンコードごとに持たなければなりません。OpenSearch URLテンプレートの"inputEncoding"テンプレートパラメータは、現在の検索リクエストのエンコードに使われているエンコーディングを識別するように検索クライアントに要求するために使うことができます。

制限: この値は IANA Character Set Assignments で定義された、 XML 1.0 Character Encodings に従ったものでなければなりません。
デフォルト: "UTF-8"

"outputEncoding"パラメータ

検索クライアントが要求する検索レスポンスを指定された文字エンコーディングでエンコードすることを示す文字列で置き換えられます。

OpenSearch description documentは"OutputEncoding"要素を検索レスポンスとして使用できる文字コードごとに持たなければなりません。OpenSearch URLテンプレートの"outputEncoding"テンプレートパラメータは、検索クライアントに検索レスポンスで使用可能な文字エンコーディングからの選択を許すために使うことができます。

制限: この値は IANA Character Set Assignments で定義された、 XML 1.0 Character Encodings に従ったものでなければなりません。
デフォルト: "UTF-8"

OpenSearch Query element

概要

OpenSearch Query要素は、検索クライアントが実行できる検索リクエストの使用を定義するために用いることができます。

Query要素属性はURLテンプレートでの検索パラメータに相当します。検索パラメータのコアセットはQuery属性として明示的に定義されている必要があり、カスタムパラメータは必要に応じて名前空間を介して追加することができます。

作成者は、検索クライアントが検索エンジンをテストできるように、OpenSearch description documentごとに少なくとも一つの role="example" Query要素を提供すべきです。検索エンジンは、検索クライアントが現在の検索を再現できるように、検索レスポンスごとに role="request" 要素を含めるべきです。

例

Query要素がOpenSearch description内で、検索クライアントに検索リクエスト例を提供するために使われる例: 

 <Query role="example" searchTerms="cat" />

Query要素がOpenSearchレスポンス内で、検索クライアントに元の検索リクエストをエコーバックするために使われる例: 

 <Query role="request" searchTerms="cat" startPage="1" />

Query要素がOpenSearchレスポンス内で、"OpenSurch"の綴り（spell）を訂正するために使われる例: 

 <Query role="correction" searchTerms="OpenSearch" totalResults="854000" title="Spelling correction" />

Query要素で拡張パラメータを使う例: 

 <Query xmlns:custom="http://example.com/opensearchextensions/1.0/"
        role="example"
        searchTerms="cat"
        custom:color="blue"
        title="Sample search" />

Query要素で拡張roleを使う例: 

 <Query xmlns:custom="http://example.com/opensearchextensions/1.0/"
        role="custom:synonym"
        title="Synonym of 'cat'"
        searchTerms="feline" />

Query要素のセットが、AtomベースのOpenSearchレスポンスのコンテキストで使われる際の詳細な例: 

 <?xml version="1.0" encoding="UTF-8"?>
 <feed xmlns="http://www.w3.org/2005/Atom" 
       xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
   <!--- ... --->
   <opensearch:Query role="request" searchTerms="General Motors annual report" />
   <opensearch:Query role="related" searchTerms="GM" title="General Motors stock symbol" />
   <opensearch:Query role="related" searchTerms="automotive industry revenue" />
   <opensearch:Query role="subset" searchTerms="General Motors annual report 2005"
   <opensearch:Query role="superset" searchTerms="General Motors" />
   <!-- ... -->
 </feed>

"Query"要素

検索クライアントが作成することのできる検索リクエストの仕様を記述します。

属性:
role - このクエリ要素により定義された検索リクエストを検索クライアントがどう解釈すべきかを識別する文字列を持たせます。
制限: 許されるroleの値については、role値の仕様を参照。
条件: この属性は必須です。
title - この検索リクエストを記述した人間向け（human-readable）のテキスト文字列を持たせます。
制限: この値は256文字あるいはそれ以下からなるプレーンテキストでなければなりません。この値にHTMLあるいはその他のマークアップを含めてはいけません。
条件: この属性は任意です。
totalResults - 検索リクエストが作成された場合に見つかると期待される結果の数を持たせます。
制限: この値は負ではない整数（integer）値でなければなりません。
条件: この属性は任意です。
searchTerms - OpenSearch 1.1パラメータとしての"searchTerms"を表す値を持たせます。
制限: "searchTerms"パラメータを参照。
条件: この属性は任意です。
count - OpenSearch 1.1パラメータとしての"count"を表す値を持たせます。
制限: "count"パラメータを参照。
条件: この属性は任意です。
startIndex - OpenSearch 1.1パラメータとしての"startIndex"を表す値を持たせます。
制限: "startIndex"パラメータを参照。
条件: この属性は任意です。
startPage - OpenSearch 1.1パラメータとしての"startPage"を表す値を持たせます。
制限: "startPage"パラメータを参照。
条件: この属性は任意です。
language - OpenSearch 1.1パラメータとしての"language"を表す値を持たせます。
制限: "language"パラメータを参照。
条件: この属性は任意です。
inputEncoding - OpenSearch 1.1パラメータとしての"inputEncoding"を表す値を持たせます。
制限: "inputEncoding"パラメータを参照。
条件: この属性は任意です。
outputEncoding - OpenSearch 1.1パラメータとしての"outputEncoding"を表す値を持たせます。
制限: "outputEncoding"パラメータを参照。
条件: この属性は任意です。

例: 

 <Query role="example" searchTerms="cat" />

Query要素の拡張性

拡張属性が名前空間に関連付けられていれば、Query要素は追加の属性を含むことができます。検索クライアントは拡張属性を、指定された名前空間の同じ名前によるテンプレートパラメータと同じ意味を持つものとして解釈すべきです。

拡張された検索パラメータに相当する拡張属性を含む検索リクエストを表すクエリ要素の例: 

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
                       xmlns:custom="http://example.com/opensearchextensions/1.0/">
  <Url type="text/html"
       template="http://example.com/search?color={custom:color?}" />
  <Query role="example"  custom:color="blue" />
  <!-- ... -->
</OpenSearchDescription>

Role値

role値は任意でプレフィックス（prefix）と、それに続くローカルrole値を続けたものからなる値です。プレフィックスがある時には、これはローカルrole値とは":"文字で区切られます。すべてのroll値は、ローカルrole値の場合は暗黙に、完全修飾role値の場合はprefixを介して明示的に、どちらかの形で名前空間に関連付けられます。

Roleの拡張性

role属性は、プレフィックスにより完全修飾で、宣言済みの名前空間に関連付けられていれば、このドキュメントで指定されたもの以上の値を受け取るかもしれません。クライアントは認識できないrole値に出会っても、Query要素に認識できないroleが含まれていなかった場合と同様に処理を続けるべきです。

Roleのプレフィックス（prefix）

roleのプレフィックスはローカルrole名を名前空間に関連付けます。すべてのプレフィックスは事前に、これを含むQuery要素かその先祖の要素で、XML名前空間として宣言されていなければなりません。

ローカルrole値

ローカルrole値は接頭語が頭についていません。ローカルrole値はOpenSearch 1.1名前空間に関連付けられています。

以下のrole値がOpenSearch 1.1名前空間で認識されます。このリストは完全なものです; OpenSearch 1.1名前空間では、以下にリストされたrole値だけが現れるでしょう。

Role値:

"request"
同じ検索結果のセットの取得を実行できる検索クエリを表します。
"example"
検索エンジンのデモンストレーションを実行できる検索クエリを表します。
"related"
よく似た、しかし異なる検索結果の取得を実行できる検索クエリを表します。
"correction"
スペルコレクションなど、結果セットをより良くするために実行できる検索クエリを表します。
"subset"
検索結果の現在のセットを絞り込むための検索クエリを表します。
"superset"
検索結果の現在のセットを広げるための検索クエリを表します。


ローカルrole値の例: 

 <Query role="related" 
        title="A related search"
        searchTerms="tiger" />

完全修飾（Fully qualified）role値

完全修飾role値はプレフィックスが先に付きます。完全修飾role値はプレフィックスにより識別される、Query要素かその祖先の要素に含まれる名前空間に関連付けられます。

完全修飾role値の例: 

 <Query xmlns:custom="http://example.com/opensearchextensions/1.0/"
        role="custom:synonym"
        title="Synonyms of 'cat'"
        searchTerms="feline" />

OpenSearch response elements

OpenSearchレスポンス要素は、検索エンジンが検索関連のメタデータで既存のXMLフォーマットを拡大するために使うことができます。

OpenSearchレスポンス要素は、典型的なものとしてRSS 2.0やAtom 1.0といったリストベースのXMLシンジゲーション形式の拡大に見ることができますが、しかしこれに限らず他の文脈でも使われるかもしれません。

OpenSearchレスポンスの例

RSS 2.0でのOpenSearchレスポンスの例

RSS 2.0形式での検索結果ページの例: 

 <?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0" 
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:atom="http://www.w3.org/2005/Atom">
   <channel>
     <title>Example.com Search: New York history</title>
     <link>http://example.com/New+York+history</link>
     <description>Search results for "New York history" at Example.com</description>
     <opensearch:totalResults>4230000</opensearch:totalResults>
     <opensearch:startIndex>21</opensearch:startIndex>
     <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
     <atom:link rel="search" type="application/opensearchdescription+xml" href="http://example.com/opensearchdescription.xml"/>
     <opensearch:Query role="request" searchTerms="New York History" startPage="1" />
     <item>
       <title>New York History</title>
       <link>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</link>
       <description>
         ... Harlem.NYC - A virtual tour and information on 
         businesses ...  with historic photos of Columbia's own New York 
         neighborhood ... Internet Resources for the City's History. ...
       </description>
     </item>
   </channel>
 </rss>

Atom 1.0でのOpenSearchレスポンスの例

Atom 1.0形式での検索結果ページの例: 

 <?xml version="1.0" encoding="UTF-8"?>
 <feed xmlns="http://www.w3.org/2005/Atom" 
       xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
   <title>Example.com Search: New York history</title> 
   <link href="http://example.com/New+York+history"/>
   <updated>2003-12-13T18:30:02Z</updated>
   <author> 
     <name>Example.com, Inc.</name>
   </author> 
   <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
   <opensearch:totalResults>4230000</opensearch:totalResults>
   <opensearch:startIndex>21</opensearch:startIndex>
   <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
   <opensearch:Query role="request" searchTerms="New York History" startPage="1" />
   <link rel="alternate" href="http://example.com/New+York+History?pw=3" type="text/html"/>
   <link rel="self" href="http://example.com/New+York+History?pw=3&amp;format=atom" type="application/atom+xml"/>
   <link rel="first" href="http://example.com/New+York+History?pw=1&amp;format=atom" type="application/atom+xml"/>
   <link rel="previous" href="http://example.com/New+York+History?pw=2&amp;format=atom" type="application/atom+xml"/>
   <link rel="next" href="http://example.com/New+York+History?pw=4&amp;format=atom" type="application/atom+xml"/>
   <link rel="last" href="http://example.com/New+York+History?pw=42299&amp;format=atom" type="application/atom+xml"/>
   <link rel="search" type="application/opensearchdescription+xml" href="http://example.com/opensearchdescription.xml"/>
   <entry>
     <title>New York History</title>
     <link href="http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html"/>
     <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
     <updated>2003-12-13T18:30:02Z</updated>
     <content type="text">
       ... Harlem.NYC - A virtual tour and information on 
       businesses ...  with historic photos of Columbia's own New York 
       neighborhood ... Internet Resources for the City's History. ...
     </content>
   </entry>
 </feed>

要素

"totalResults"要素

現在の検索で得られる検索結果の個数。

totalResults要素がページ内に出現しない場合、検索クライアントは現在のページを検索結果の最後のページだとみなすべきです。

制限: この値は負ではない整数（integer）値でなければなりません。
デフォルト: デフォルト値は現在のページの最後の検索結果のオフセットインデックスに等しくなります。
条件: この要素は0または1回登場します。

例: 

 <totalResults>492420</totalResults>

"startIndex"要素

現在の検索結果のセットの最初の検索結果のインデックス。

startIndex要素がページ内に出現しない場合、検索クライアントは現在のページを検索結果の最初のページだとみなすべきです。

制限: この値は整数値でなければなりません。
デフォルト: デフォルト値はOpenSearch description documentの"Url"要素の属性の"indexOffset"に等しくなります。
条件: この要素は0または1回登場します。

例: 

 <startIndex>11</startIndex>

"itemsPerPage"要素

ページあたりに返される検索結果の個数。

itemsPerPage要素がページ内に出現しない場合、検索クライアントは現在のページないのアイテムの個数をデフォルトのページサイズとして使うべきです。

制限: この値は負ではない整数（integer）値でなければなりません。
デフォルト: デフォルト値は現在のページの最後の検索結果の個数に等しくなります。
条件: この要素は0または1回登場します。

例: 

 <itemsPerPage>10</itemsPerPage>

"Query"要素

検索クライアントが実行できる検索クエリを定義します。詳細はOpenSearch Query要素の仕様を参照。

検索結果は、現在の検索レスポンスを生成した、検索結果を再生成するために使うことができるtype="request"のQuery要素を含むべきです。

条件: この要素は0または1回登場します。

例: 

 <Query role="request" searchTerms="cat" />


HTML/XHTMLでのレスポンスメタデータ

OpenSearchレスポンスメタデータは HTML 4.0.1 "meta"要素 を介して、整形式（well-formed）のHTML/XHTMLに含めることができます。

以下のmeta要素は"name"属性値が、OpenSearch 1.1名前空間に関連付けられたプロファイルで認識されます。:

"totalResults" - "totalResults"要素の値に相当します。
"startIndex" - "startIndex"要素の値に相当します。
"itemsPerPage" - "itemsPerPage"要素の値に相当します。

XHTML 1.0形式での検索結果ページの例: 

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head profile="http://a9.com/-/spec/opensearch/1.1/" >
     <title>Example.com Search: New York history</title>
     <link rel="search"
           type="application/opensearchdescription+xml" 
           href="http://example.com/opensearchdescription.xml"
           title="Example.com Web Search" />
     <meta name="totalResults" content="4230000"/>
     <meta name="startIndex" content"1"/>
     <meta name="itemsPerPage" content="10"/>
   </head>
   <body>
      <ul>
        <li>
          <a href="http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html">
            New York History
          </a>
          <div>
            ... Harlem.NYC - A virtual tour and information on 
            businesses ...  with historic photos of Columbia's own New York 
            neighborhood ... Internet Resources for the City's History. ...
          </div>
        </li>
        <!-- ... -->
      </ul>
    </body>
 </html>

Author

DeWitt Clinton <dewitt@opensearch.org>

Contributors

Joel Tesler <tesler@a9.com>, Michael Fagan <mifa@a9.com>, Joe Gregorio <joe@bitworking.org>, Aaron Sauve <aaronsa@microsoft.com>, James Snell <jasnell@us.ibm.com>

License

原文「Specifications/OpenSearch/1.1/Draft 4」はA9.comにより、 Creative Commons Attribution-ShareAlike 2.5 License（Creative Commons 表示 - 継承 2.5ライセンス）で公開されています。
この文書は塚本 牧生が同ライセンス条項に基づき、同文書の翻訳物を、同じくCreative Commons 表示 - 継承 2.5ライセンスの下で公開するものです。

Japanese Translator

塚本 牧生 <tsukamoto@gmail.com>


Comments