OPDS Catalog 1.1 格式說明

簡介

Open Publication Distribution System 中文翻譯作開放出版發行系統，是一種基於 Atom 用來對電子出版物 (主要用於電子書) 作格式化的規範。透過 OPDS 可以提供電子出版物整合、發布、查詢和取得的功能。完整的規範可以在此網站查看。OPDS 繼承自 Atom。

命名空間

OPDS 目前發展到版本 1.1，1.2 為 Draft；OPDS 1.1 的規範使用到的命名空間與 Prefix 如下：

名稱	命名空間	Prefix
OPDS 1.1	http://opds-spec.org/2010/catalog	opds:
Atom 1.0	http://www.w3.org/2005/Atom	atom:
DCTERMS	http://purl.org/dc/terms/	dc:

MIME Type

MIME Type 雖然基於 Atom，不過由於 OPDS 的文件依據不同類型內容共定義了四種，如下：

文件類型	MIME Type
OPDS Catalog Entry Document	application/atom+xml;type=entry;profile=opds-catalog
OPDS Catalog Feed Document	application/atom+xml;profile=opds-catalog
Acquisition Feed	application/atom+xml;profile=opds-catalog;kind=acquisition
Navigation Feed	application/atom+xml;profile=opds-catalog;kind=navigation

文件類型

OPDS Catalog 定義兩種文件，分別為 OPDS Catalog Entry Document 和 OPDS Catalog Feed Document。

OPDS Catalog Feed Document

OPDS Catalog Feed Document 應該要包含一個連結 rel=”start” 以指向 OPDS Catalog Root

OPDS Catalog Feed Document 又定義兩種 Feed，分別為 Acquisition Feed 和 Navigation Feed

OPDS Catalog Root

OPDS Catalog Root 必須是最外層的 OPDS Catalog Feed Document 且只能有一個 Root，可以是 Navigation Feed 或 Acquisition Feed。

Navigation Feed 用來導向其他的 Feed，繼承 Atom 定義，粗體部分為 OPDS 定義，Navigation Feed 定義如下：

Element	必要	多筆	資料型態	說明
`<author>`	Δ	O	atomPersonConstruct	作者，`<feed>` 必須要包含至少一個 `<author>`，除非之下的所有 `<entry>` 都有包含 `<author>`
`<category>`	X	O	`<category>`	分類
`<contributor>`	X	O	atomPersonConstruct	貢獻者
`<generator>`	X	X	`<generator>`	產生者
`<icon>`	X	X	純文字	圖示，寬高比應該為 1:1
`<id>`	O	X	純文字	唯一識別 ID
`<link>`	X	O	`<link>`(OPDS 擴充)	連結，`<feed>` 應該包含一個連結指向自己 (ref=”self”) `<feed>` 應該包含一個連結指向 OPDS Catalog Root(ref=”start”)
`<logo>`	X	X	純文字	圖示，寬高比應該為 2:1
`<rights>`	X	X	atomTextConstruct	版權資訊
`<subtitle>`	X	X	atomTextConstruct	副標題
`<title>`	O	X	atomTextConstruct	標題
`<updated>`	O	X	atomDateConstruct	最後更新時間
`<entry>`	X	O	`<entry>`	包含的項目可以是 Navigation Feed 或 Acquisition Feed 的連結，但不可以是 OPDS Catalog Entry。`<entry>` 中應該包含 `<content>` 來描述連結 `<entry>` 包含之 `<link>` 的 rel 應該使用 OPDS Catalog Relations 定義，無合適才用 rel=”subsection”

指向 Navigation Feed 的連結 type 應該為 application/atom+xml;profile=opds-catalog;kind=navigation

Acquisition Feed

Acquisition Feed 用來列出可取得的項目，繼承 Atom 定義，粗體部分為 OPDS 定義，Acquisition Feed 定義如下：

Element	必要	多筆	資料型態	說明
`<author>`	Δ	O	atomPersonConstruct	作者，`<feed>` 必須要包含至少一個 `<author>`，除非之下的所有 `<entry>` 都有包含`<author>`
`<category>`	X	O	`<category>`	分類
`<contributor>`	X	O	atomPersonConstruct	貢獻者
`<generator>`	X	X	`<generator>`	產生者
`<icon>`	X	X	純文字	圖示，寬高比應該為 1:1
`<id>`	O	X	純文字	唯一識別 ID
`<link>`	X	O	`<link>`(OPDS 擴充)	連結，`<feed>` 應該包含一個連結指向自己 (ref=”self”) `<feed>` 應該包含一個連結指向 OPDS Catalog Root(ref=”start”)
`<logo>`	X	X	純文字	圖示，寬高比應該為 2:1
`<rights>`	X	X	atomTextConstruct	版權資訊
`<subtitle>`	X	X	atomTextConstruct	副標題
`<title>`	O	X	atomTextConstruct	標題
`<updated>`	O	X	atomDateConstruct	最後更新時間
`<entry>`	X	O	`<entry>`(OPDS Catalog Entry)	包含的項目

指向 Acquisition Feed 的連結 type 必須為 application/atom+xml;type=entry;profile=opds-catalog

Complete Acquisition Feed

OPDS Catalog 可以提供一個 Complete Acquisition Feed，以讓外部抓取，規則如下：

提供所有的刊物且不應該分頁，除非資料量很大。
所有刊物必須依照 <updated> 排序。
如果無分頁的話必須包含 <fh:complete> 之 Element，分頁的話依據 RFC5005 之規則。
應該使用定義於 RFC2616 之 Content-Encoding 壓縮資料。
包含之 Entry 必須是 Complete Catalog Entry。

OPDS Catalog Relations

連結到OPDS Catalog Feed Document的連結應該要使用OPDS Catalog Relation之定義來表示文件意義：

rel	文件類型	說明
start	OPDS Catalog Root	OPDS Catalog Root
subsection	Navigation Feed	無其他更合適的 OPDS Catalog Relation 可用時才使用
http://opds-spec.org/sort/new	Acquisition Feed	最新刊物，應該依時間排序，應該在 Navigation Feed 或 OPDS Catalog Root 才使用
http://opds-spec.org/sort/popular	Acquisition Feed	熱門刊物，應該依熱門度排序，應該在 Navigation Feed 或 OPDS Catalog Root 才使用
http://opds-spec.org/featured	Acquisition Feed	特別刊物，例如促銷，應該在 Navigation Feed 或 OPDS Catalog Root 才使用
http://opds-spec.org/recommended	Acquisition Feed	推薦刊物，應該依推薦度排序，應該在 Navigation Feed 或 OPDS Catalog Root 才使用
http://opds-spec.org/shelf	Acquisition Feed	使用者書櫃，例如購買之刊物
http://opds-spec.org/subscriptions	Acquisition Feed	使用者訂閱
http://opds-spec.org/facet	Acquisition Feed	過濾或排序條件，必須在 Navigation Feed 才使用
http://opds-spec.org/crawlable	Acquisition Feed	提供被抓取的位址，應該要是 Complete Acquisition Feed

當以上 Relation 與 RFC 5988 中都無合適時，<entry> 之 <title> 或 <link> 之 title 應該用來描述此關連。

OPDS Catalog Entry Document

OPDS Catalog Entry Document 又分為 Partial 和 Complete Catalog Entry 兩種，

指向 OPDS Catalog Entry Document 的連結 type 應該為 application/atom+xml;profile=opds-catalog;kind=acquisition

Partial Catalog Entry

Partial Catalog Entry 只提供最重要的資訊以減少資料量，繼承 Atom 定義，粗體部分為 OPDS 定義，Partial Catalog Entry 定義如下：

Element	必要	多筆	資料型態	說明
`<author>`	Δ	O	atomPersonConstruct	作者，`<entry>` 必須要包含至少一個 `<author>`，除非之下的 `<source>` 或者此 `<feed>` 有包含 `<author>`
`<category>`	X	O	`<category>`	分類，如果有的話應該包含此資訊
`<content>`	X	X	`<content>`	內容，`<content>` 和 `<summary>` 應該至少包含其中一個，同時具有時不應該提供 `<contnet>`
`<contributor>`	X	O	atomPersonConstruct	貢獻者，如果有的話應該包含此資訊
`<id>`	O	X	純文字	唯一識別 ID，可以有相同 ID 的 `<entry>`，但更新時間必須不同，表示不同版本
`<link>`	X	O	`<link>`(OPDS 擴充)	連結，如果沒有 `<content>` 就必須包含一個連結 (ref=”alternate”)，且多個具有ref=”alternate” 的連結，type 和 hreflang 的屬性不能都相同必須包含一個連結指向 Complete Catalog Entry(ref=”alternate”) 必須包含一個獲取連結 (ref 為 Acquisition Relations 定義)
`<published>`	X	X	atomDateConstruct	發布時間
`<rights>`	X	X	atomTextConstruct	版權資訊，如果有的話應該包含此資訊
`<source>`	X	X	`<source>`	資料來源，當資料來源是從別的 `<feed>` 拷貝過來時，應用此Element提供原始 `<feed>` 資訊
`<summary>`	Δ	X	~~atomTextConstruct~~ 純文字	摘要~~，如果`<content>`是外部資源(具有src屬性)或內容是Base64編碼時，必須要有`<summary>`~~ 必須是type=”text”，`<content>`和`<summary>`應該至少包含其中一個，同時具有時應該只提供`<summary>`不應該和`<content>`或`<title>`重複
`<title>`	O	X	atomTextConstruct	標題
`<updated>`	O	X	atomDateConstruct	最後更新時間

Acquisition Feed 中的 Entry 應該要是 Partial Catalog Entry。

Complete Catalog Entry

Complete Catalog Entry 應該要提供完整的資訊，繼承 Atom 定義，粗體部分為 OPDS 定義，Complete Catalog Entry 定義如下：

Element	必要	多筆	資料型態	說明
`<author>`	Δ	O	atomPersonConstruct	作者，`<entry>` 必須要包含至少一個 `<author>`，除非之下的 `<source>` 或者此 `<feed>` 有包含 `<author>`
`<category>`	X	O	`<category>`	分類
`<content>`	X	X	`<content>`	內容，`<content>` 和 `<summary>` 應該至少包含其中一個
`<contributor>`	X	O	atomPersonConstruct	貢獻者
`<id>`	O	X	純文字	唯一識別 ID，可以有相同 ID 的 `<entry>`，但更新時間必須不同，表示不同版本
`<link>`	X	O	`<link>`(OPDS擴充)	連結，如果沒有 `<content>` 就必須包含一個連結 (ref=”alternate”)，且多個具有 ref=”alternate” 的連結，type 和 hreflang 的屬性不能都相同必須包含一個獲取連結 (ref 為 Acquisition Relations 定義)
`<published>`	X	X	atomDateConstruct	發布時間
`<rights>`	X	X	atomTextConstruct	版權資訊
`<source>`	X	X	`<source>`	資料來源，當資料來源是從別的 `<feed>` 拷貝過來時，應用此 Element 提供原始 `<feed>` 資訊
`<summary>`	Δ	X	~~atomTextConstruct~~ 純文字	摘要~~，如果 `<content>` 是外部資源 (具有 src 屬性) 或內容是 Base64 編碼時，必須要有 `<summary>`~~ 必須是 type=”text”，`<content>` 和 `<summary>` 應該至少包含其中一個不應該和 `<content>` 或 `<title>` 重複
`<title>`	O	X	atomTextConstruct	標題
`<updated>`	O	X	atomDateConstruct	最後更新時間

Entry Relations

rel	說明
http://opds-spec.org/acquisition	一般的獲取刊物
http://opds-spec.org/acquisition/open-access	無條件獲取刊物
http://opds-spec.org/acquisition/borrow	借閱刊物
http://opds-spec.org/acquisition/buy	購買刊物
http://opds-spec.org/acquisition/sample	試閱刊物
http://opds-spec.org/acquisition/subscribe	訂閱刊物
http://opds-spec.org/image	刊物圖片(封面)
http://opds-spec.org/image/thumbnail	刊物圖片之縮圖

圖片 Relation 之 type 應該是 image/gif、image/jpeg 或 image/png

元素

<link>

<link> 描述連結，繼承 Atom 定義，粗體部分為 OPDS 定義，<link> 定義如下：

Attribute	必要	說明
href	O	IRI
rel	X	關聯類型，無設定時，預設為 alternate。格式應符合 isegment-nz-nc 或 IRI 且不包含空白。另外，關聯定義可參考 RFC 5988，在 Atom 中特別定義其中 5 個項目： alternate: 目前資源別種顯示方式(例如搭配hreflang 為其他語言版本) related: 相關資源 self: 目前資源 enclosure: 相關資源，但資料內容較大 via: 資源由何處提供 http://opds-spec.org/facet: 只使用在 `<feed>` 之 `<link>`
type	X	類型 rel 如果是 http://opds-spec.org/acquisition 開頭的，必須要有此屬性
hreflang	X	語系
title	X	標題
length	X	連結內容的大小，當 rel 為 enclosure 時，應該要有此屬性
opds:facetGroup	X	過濾或排序條件的群組，當 rel 為 http://opds-spec.org/facet 時，必須要有此屬性
opds:activeFacet	X	是否為正在使用的過濾或排序條件，當 rel 為 http://opds-spec.org/facet 時且為使用時，必須為 true，否則不顯示此屬性，一個群組中一次只能有一個是使用狀態

Atom 原定義 <link> 不包含 Element，而在 OPDS 之定義了以下 Element：

Element	必要	多筆	說明
`<opds:price>`	X	O	價格當 `<link>` 之 rel 為 http://opds-spec.org/acquisition/buy，必須要有此 Element 當 `<link>` 之 rel 為，http://opds-spec.org/acquisition/borrow、http://opds-spec.org/acquisition/sample 或 http://opds-spec.org/acquisition/subscribe 時，可以有此 Element 如果為 Partial Catalog Entry 且有此資訊時應該包含此 Element
`<opds:indirectAcquisition>`	X	O	次要的 Media Type

<opds:price>

<opds:price> 描述 <link> 的價格，<opds:price> 之中定義了以下屬性

Attribute	必要	說明
currencycode	O	貨幣單位，定義於 ISO4217

Element 內容必須是價格數字

<opds:indirectAcquisition>

<opds:indirectAcquisition> 描述 <link> 的次要 Media Type，例如用於購買之 <link> 中，type 可能是 text/html 之購買網頁，可用此屬性描述購買完成後刊物的 Media Type，<opds:indirectAcquisition> 之中定義了以下屬性

Attribute	必要	說明
type	O	Media type

<opds:indirectAcquisition> 定義了以下 Element：

Element	必要	多筆	說明
`<opds:indirectAcquisition>`	X	O	次要的 Media Type

延展性

OPDS 與 Atom 規範一致，允許自訂未定義 Element 和 Attribute，解析或整合者要遵守以下規則：

遇到未定義標記時，不能中斷處理與視為 error。
轉遞 OPDS 時，應該保留未定義標記。

搜索

OPDS Catalog 可以透過 OpenSearch 規範，提供搜索功能，搜索連結必須為 rel=”search” 與 type=”application/opensearchdescription+xml”。

搜索結果之 OPDS Catalog Entry Document 可以包含 OpenSearch 定義元素，例如：<opensearch:totalResults> 或 <opensearch:itemsPerPage>

延伸閱讀

Atom Feed 格式說明