RFC4287のまとめ。並行してAtomPP(APP)のドラフト14もまとめたのだけれども、RFC4287のほうは日本語訳があった。APPドキュメントの新しめの日本語訳が見当たらなかったのでRFC4287の日本語訳はろくに探さずに自分で訳してメモっていたのだけれども、実はRFC4287の日本語訳はすでに公開されていた。まぁ英語の勉強だということで。
overview
- Atom文書の所属する名前空間は http://www.w3.org/2005/Atom
- Feed文書とEntry文書がある。Feed文書は複数のEntryを持てる
- MIMEはapplication/atom+xmlとする
- xml:langとxml:baseという基本的属性はどのAtom要素も持てる。とくに、言語依存性(Language-sensitive)のある要素ではxml:lang要素の指定が重要になる
押さえておきたいのはIRIという概念について。URLはURIであり、絶対URIはIRIである。IRIはi18nされていて、日本語も普通に使える。URIであってURLでないものは、たとえば書籍に付されるISBNコードやid要素で使われることがあるUUIDなど。HTTP通信をするときは、HTTPはIRIを使えないので適切にIRIをURLに置換する必要がある。
コンストラクト
Text, Person, Dateという3つのコンストラクトがある。
「コンストラクト」は、複数の要素に共通する子要素や属性の定義をまとめたものという理解でいいのかな。この後出てくるauthor要素やcontibuter要素はPersonコンストラクトだが、これは違う言葉で言うと「authorクラスはPersonクラスを継承している」と同じ意味か?
Textコンストラクト
人間が読めるテキストで、それゆえ言語依存性がある (xml:lang要素の指定が重要)。
このコンストラクトの要素はtype属性を持てる。type属性の値はtext,html,xhtmlのいずれかで、値が"text"または"html"の場合は子要素を持てない。要素の中身は全て文字列になる。htmlを指定した場合はHTMLのタグを実体参照させる。これならHTMLがXML的に整形式になっていなくても安心。
仕様書の例を見ると、<em>
のように">"を実体参照にしていない。確かに"<"さえエスケープしておけばパース上は問題ないとはいえ、どうも見た目がしっくりこない。まぁ、">"を">"に置換する瞬間も惜しいこともあるかもしれないけど。
type属性の値が"xhtml"の場合は、子要素はxhtml:div要素となる。直下にテキストは置けず、全てxhtml:div要素の子孫要素となる。XHTMLの文法に妥当な範囲で、XHTML名前空間下の任意の要素を置ける。XHTML名前空間の宣言はTextコンストラクタの要素で行っても良いし、Textコンストラクタの要素の子要素(xhtml:div要素)で行っても良い。とくにXHTMLブロックがFeed中に1回しか登場しないなら後者のほうがすっきり書ける。
- Textコンストラクタの要素でXHTML名前空間を宣言する例
<title type="xhtml" xmlns:xhtml="http://www.w3.org/1999/xhtml"> <xhtml:div> Less: <xhtml:em> < </xhtml:em> </xhtml:div> </title>
- Textコンストラクタの要素の子要素でXHTML名前空間を宣言する例
<summary type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml"> This is <b>XHTML</b> content. </div> </summary>
Personコンストラクト
- 人、会社、団体をあらわす
- name要素を1つ持つ (言語依存性あり)
- url要素を0個か1個持てる。中身はIRI参照
- email要素を0個か1個持てる。RFC2822に定められたaddr-spec形式に準拠させる
Dateコンストラクト
- 日付をあらわす
- RFC3339のdate-tyme形式
- 年月日と時分秒の間に大文字の"T"を入れる
- 時分秒のあとにタイムゾーンを書く。不明な場合は大文字の"Z"
- 可能な限り細かい精度で時刻値を出すべき。1日に何度も更新されるのに年月日の情報しか吐かないような実装はウンコ
たとえば、以下のような文字列表現はすべて正しい:
<updated>2003-12-13T18:30:02Z</updated>
<updated>2003-12-13T18:30:02.25Z</updated>
<updated>2003-12-13T18:30:02+01:00</updated>
<updated>2003-12-13T18:30:02.25+01:00</updated>
Atom要素の定義
feed
- 複数のEntryを持てる
- 同じ文字列表現のid要素を持ったentry要素が複数ある場合、それらのentryは同じエントリを表していると考える。実装によっては、同じIDのエントリについてはタイムスタンプが最も新しいもののみを表示するかもしれない。
子要素 | 説明 | コンストラクト | 登場パタン |
---|---|---|---|
author | 著者名 | Person | 1個以上。ただし、すべてのentry要素がauthor要素を持っているなら、0個でもよい |
category | カテゴリ | 0個以上 | |
contributer | 貢献した人 | Person | 0個以上 |
generator | フィードを生成したもの | 0個か1個 | |
icon | フィードのアイコンのIRI | 0個か1個 | |
id | 識別IRI | 1個 | |
link | フィードへのリンク | 0個以上。ただし、rel="self"なlink要素が1つあるべき。AtomフィードをあらわすAtomフィード文書を取り出すためのURIとして使われる。rel="alternate"なlink要素でtype属性とhreflang属性の値が同じものは2つ以上存在してはならない (他言語版代替文書は1言語につき1つまで) | |
logo | フィードのロゴ画像のIRI | 0個か1個 | |
rights | 権利情報 | Text | 0個か1個 |
subtitle | サブタイトルやフィードの説明 | Text | 0個か1個 |
title | フィードのタイトル | Text | 1個 |
updated | 重要な更新がされた日時 | Date | 1個 |
(任意の独自拡張要素) | 0個以上 | ||
entry | エントリ | 0個以上 |
entry
子要素 | 説明 | コンストラクト | 登場パタン |
---|---|---|---|
author | 著者名 | Person | 1個以上。ただし、feed要素直下にauthor要素がある場合や、子のsource要素がauthor要素を持っているなら、0個でもよい |
category | カテゴリ | 0個以上 | |
content | エントリのコンテンツかコンテンツへのリンク | Text | 0個か1個 |
contributer | 貢献した人 | Person | 0個以上 |
id | 識別IRI | 1個 | |
link | エントリへのリンク | 0個以上。ただし、(HTML版へのリンクを表すような) rel="alternate"なlink要素が1つあるべき。AtomフィードをあらわすAtomフィード文書を取り出すためのURIとして使われる。rel="alternate"なlink要素でtype属性とhreflang属性の値が同じものは2つ以上存在してはならない (他言語版代替文書は1言語につき1つまで) | |
published | 初出日時 | Date | 0個か1個 |
rights | 権利情報 | Text | 0個か1個 |
source | entryに紐付けられているfeedの情報 | 0個か1個 | |
summary | 要約 | Text | 0個か1個。ただし、content要素にsrc属性が指定されている場合か、content要素のtype属性がtext/*や*/xml,*/*+xmlでない場合は1個必要。entryの指す先がhuman-readableな形式でないなら、要約が必須ということ |
title | エントリのタイトル | Text | 1個 |
updated | 重要な更新がされた日時 | Date | 1個 |
(任意の独自拡張要素) | 0個以上 |
content
type属性とsrc属性を取る。type属性の値はtext, html, xhtml またはmediatype値で、mediatype値の場合はコンテンツを表すURIをsrc属性に記述する。
子要素はtype属性値がtextかhtmlの場合はテキストのみ。xhtmlの場合はxhtml:div要素。mediatype値の場合はテキストか任意の要素が0個以上。
content要素処理の実装
最初に適用されるルールに則って処理をする。
- type="text"のときは子要素はテキストである。空白文字や改行文字を無視して表示してもよい。
- type="html"のときは子要素は実体参照されたテキストである。適宜HTMLを利用して表示する。実体参照は展開する
- type="xhtml"のときは子要素はxhtml:divが1つである。適宜XHTMLを利用して表示する。実体参照は展開しない
- type属性の値がRFC3023で定義されるメディアタイプのときか*/*+xml、*/xmlなら、指定されたメディアタイプで定義される要素を子要素に持てる。src属性が指定されていないなら、直下には指定されたタイプのXML文書のルート要素が来る
- type属性の値が"text/"で始まるときは、子要素はテキストのみ
- 以上に該当しない場合は、content要素の中身はRFC3548によってBase64エンコーディングされた文字列である。先頭の空白文字は無視する。改行文字(U+000A)で行を分ける
author
- Personコンストラクト
- entry要素の直下にauthor要素がない場合、feed要素直下のauthor要素の値がそのエントリのオーサだとみなす
category
- カテゴリ(タグ)を表す
属性名 | 取りうる値 | 登場パタン | 捕捉 |
---|---|---|---|
term | テキスト | 必須 | カテゴリを表す文字列 |
scheme | URI | 任意 | 分類スキームを表す (カテゴリの名前空間?) |
label | テキスト | 任意 | human-readableなラベル。言語依存性あり。実体参照は展開してテキストとして扱う |
Atomのcategory要素とURI参照が参考になる。
contributer
- Personコンストラクト
- エントリやフィードに貢献した人や他の実体を表す
generator
- デバッグなどに使うために、フィード生成に使われたエージェントを表す
- uri属性にこのエージェントのURIを、version属性にエージェントのバージョンを指定する
- 子要素はテキストのみ。実体参照は展開してテキストとして解釈する
icon
フィードを象徴するアイコン画像のURI。画像の大きさは1:1であって、小さいサイズでも中身がわかるものがよい。
id
- エントリやフィードの永久的で完全に一意な識別子
- RFC3987で定義されているIRIである必要がある
- Atom文書のURLが変わったり、エクスポート/インポートしたり再発行したりしてもid要素の値を変更してはいけない。idの値は関連付けられたリソースと一緒に保存されているべき
id要素値生成の方針
- スキーム名を小文字に
- もしホスト名があるなら、それを小文字に
- 必要に応じてパーセントエンコーディングのみを行い、AからFは大文字に変える
- パス表記では、親ディレクトリや自ディレクトリを指すためのドットを使わないようにする
- デフォルトの権限を定義する必要のあるスキームでは、空文字列をデフォルトにする
- 空文字列で表されるパスと"/"というパスで表される対象が同じスキームの場合は"/"を使う
- ポートを定義するスキームの場合で、もしデフォルト値が必要なら空文字列をデフォルトにする
- 空のフラグメント識別子とクエリを保持する
- NKCやNFKCなどを使って、すべてのIRIコンポーネントが適切に標準化された文字列になっているようにする
- (メモ)Java5.0のjava.utilパッケージにはUUIDというクラスがあり、多分id要素値の生成に使える
link
属性名 | 取りうる値 | 登場パタンと捕捉 | |
---|---|---|---|
href | IRI | 必須 | |
rel | alternate | 代替リソース | 省略時はalternateとみなす |
related | 関連リソース | ||
self | 自分自身 | ||
enclosure | サイズの大きい特別な関連リソース | ||
via | 情報元 | ||
type | メディアタイプ値 | ||
hreflang | RFC3066で定義された言語タグ(en-USとかja-JPとか) | rel="alternate"と一緒に使われたときは、ここで示された言語による翻訳であることを暗示する | |
title | human-readableな情報。言語依存性がある | 実体参照は展開してテキストとして扱う | |
length | リンクされたコンテンツのオクテット長 |
logo
フィードを象徴するビジュアル識別子となる画像。2:1の横長画像であるべき
published
- Dateコンストラクト
- リソースの生成日時
rights
- Textコンストラクト
- 著作権情報
- entry直下にrights要素がない場合、feed直下のrights要素が適用される
- 人間向けの情報を記述する
source
entryをあるfeedから他のfeedに複製するときに、entryに付随させておくべき元feedの情報を表す。
子要素 | 説明 | コンストラクト | 登場パタン |
---|---|---|---|
author | 著者名 | Person | 1個以上。ただし、すべてのentry要素がauthor要素を持っているなら、0個でもよい |
category | カテゴリ | 0個以上 | |
contributer | 貢献した人 | Person | 0個以上 |
generator | フィードを生成したもの | 0個か1個 | |
icon | フィードのアイコンのIRI | 0個か1個 | |
id | 識別IRI | 1個 | |
link | フィードへのリンク | 0個以上。ただし、rel="self"なlink要素が1つあるべき。AtomフィードをあらわすAtomフィード文書を取り出すためのURIとして使われる。rel="alternate"なlink要素でtype属性とhreflang属性の値が同じものは2つ以上存在してはならない (他言語版代替文書は1言語につき1つまで) | |
logo | フィードのロゴ画像のIRI | 0個か1個 | |
rights | 権利情報 | Text | 0個か1個 |
subtitle | サブタイトルやフィードの説明 | Text | 0個か1個 |
title | フィードのタイトル | Text | 1個 |
updated | 重要な更新がされた日時 | Date | 1個 |
(任意の独自拡張要素) | 0個以上 |
subtitle
human-readableなフィードの説明やサブタイトル。いわゆるタグラインか?
summary
- entryの要約、抜粋、引用など
- title要素やcontent要素と同じ内容にしないようにする
title
- Textコンストラクト
- エントリやフィードのタイトル
updated
- Dateコンストラクト
- 重要な修正がされた日時
- すべての修正が必ずしもupdatedの変更を伴うわけではない