群島舎

shelff JSON仕様

shelffは、PDFファイルのメタデータや読書進捗をJSONファイルとしてiCloud上に保存します。このページでは、shelffが読み書きするJSONファイルの仕様を説明します。

shelffはこれらのJSONファイルを通じてデータを管理しており、他のツールからも同じファイルを読み書きすることで、shelffと連携できます。

概要

shelffは3種類のJSONファイルを使用します。

ファイル 場所 役割
*.pdf.meta.json 各PDFと同じディレクトリ 個別PDFのメタデータ・読書進捗・表示設定
.shelff/categories.json shelffドキュメントルート直下の.shelffディレクトリ カテゴリの定義と順序
.shelff/tags.json shelffドキュメントルート直下の.shelffディレクトリ タグの表示順序

メタデータファイル（*.pdf.meta.json）は、shelffでPDFを最初に開いたときに自動的に作成されます。このときdc:titleにはファイル名が設定されます。

文字エンコーディングはUTF-8です。日付はISO 8601形式で記録されます。

メタデータファイル *.pdf.meta.json

各PDFファイルに対応するメタデータファイルです。PDFファイルと同じディレクトリに、元のファイル名に.meta.jsonを付加した名前で保存されます。

例: my-book.pdf → my-book.pdf.meta.json

例

{
  "schemaVersion": 1,
  "metadata": {
    "dc:title": "プログラミング入門",
    "dc:creator": ["山田太郎"],
    "dc:publisher": "技術出版社",
    "dc:date": "2024",
    "dc:language": "ja",
    "dc:subject": ["プログラミング", "入門"],
    "dc:identifier": "978-4-00-000000-0"
  },
  "reading": {
    "lastReadPage": 42,
    "totalPages": 300,
    "lastReadAt": "2025-03-20T14:30:00Z",
    "status": "reading",
    "finishedAt": null
  },
  "display": {
    "direction": "LTR",
    "pageLayout": "spread-with-cover",
    "crop": {
      "excludeFirstPage": true,
      "odd":  { "top": 0.05, "bottom": 0.04, "left": 0.03, "right": 0.03 },
      "even": { "top": 0.05, "bottom": 0.04, "left": 0.02, "right": 0.04 }
    }
  },
  "collection": { "title": "プログラミング入門シリーズ", "position": 1 },
  "category": "技術書",
  "tags": ["Swift", "入門"],
  "bookmarks": [
    { "page": 3, "label": "重要な図" },
    { "page": 15 },
    { "page": 42 }
  ]
}

トップレベルフィールド

フィールド 型 必須 説明
schemaVersion 整数 はい スキーマバージョン。現在は1
metadata オブジェクト はい 書誌メタデータ（後述）
reading オブジェクト いいえ 読書進捗（後述）
display オブジェクト いいえ 表示設定（後述）
collection オブジェクト いいえ 所属するコレクション（シリーズ・雑誌）。1つのPDFにつき最大1つ
category 文字列 いいえ カテゴリ名（1つのPDFにつき1つ）
tags 文字列の配列 いいえ タグ名の配列
bookmarks オブジェクトの配列 いいえ ユーザー定義のページしおり（後述）

metadataオブジェクト

書誌メタデータです。フィールド名はDublin Core Metadata Termsに基づいたdc:接頭辞付きのキーを使用しています。

フィールド 型 必須 説明
dc:title 文字列 はい タイトル
dc:creator 文字列の配列 いいえ 著者
dc:date 文字列 いいえ 日付。"2024"、"2024-06"、"2024-06-15"のいずれも有効
dc:publisher 文字列 いいえ 出版社
dc:language 文字列 いいえ 言語コード（例: "ja"、"en"）
dc:subject 文字列の配列 いいえ 主題・キーワード
dc:identifier 文字列 いいえ 識別子（ISBNなど）

readingオブジェクト

フィールド 型 必須 説明
lastReadPage 整数 はい 最後に読んだページ番号（1始まり）
totalPages 整数 はい 総ページ数
lastReadAt 文字列 はい 最終閲覧日時（ISO 8601）
status 文字列 いいえ 読書ステータス: "unread" / "reading" / "finished"
finishedAt 文字列 いいえ 読了日時（ISO 8601）

displayオブジェクト

フィールド 型 必須 説明
direction 文字列 はい 読み方向: "LTR"（左→右）/ "RTL"（右→左）
pageLayout 文字列 いいえ ページレイアウト: "single" / "spread" / "spread-with-cover"
crop オブジェクト または null いいえ 余白の調整（後述）。省略またはnullの場合は調整なし

display.cropオブジェクト

ページを表示するときに適用する余白の調整（クロップ）です。PDFファイル自体は変更せず、リーダーが表示時にページの表示範囲へ適用します。

フィールド 型 必須 説明
odd オブジェクト はい 奇数ページ（1, 3, 5, …）の余白幅（後述）
even オブジェクト はい 偶数ページ（2, 4, 6, …）の余白幅（後述）
excludeFirstPage 真偽値 いいえ trueの場合、1ページ目（通常は表紙）には調整を適用しない。省略時はfalse

奇偶は PDF のページ番号（1始まり）で決まり、pageLayoutやdirectionには依存しません。全ページに同じ調整を適用する場合はoddとevenに同じ値を書きます。

odd / even は次の4フィールドを持つオブジェクトです。値はページの MediaBox に対する比率（0.0〜1.0）で、/Rotate適用後の表示上の向きで定義します。

フィールド 型 必須 説明
top 数値 はい 上辺から切り落とす幅（ページ高さに対する比率）
bottom 数値 はい 下辺から切り落とす幅（ページ高さに対する比率）
left 数値 はい 左辺から切り落とす幅（ページ幅に対する比率）
right 数値 はい 右辺から切り落とす幅（ページ幅に対する比率）

各値は0以上で、top + bottom < 1かつleft + right < 1でなければなりません。この条件を満たさない場合、リーダーはエラーにせず「調整なし」として扱います。displayを書き換えるツールはcropを保持してください。

bookmarks配列

ユーザーが任意のページに付与する「しおり」（デジタル付箋）の配列です。PDFに組み込まれたアウトライン（目次）とは別に、読み手が関心のあるページを記録するために使用します。

フィールド 型 必須 説明
page 整数 はい しおりを付けたページ番号（1始まり）
label 文字列 いいえ しおりのラベル。省略時はページ番号などをフォールバック表示してよい

collectionオブジェクト

各PDFが属するシリーズや雑誌を表すオブジェクトです。EPUBのbelongs-to-collection/group-positionに着想を得て、type区分なしの単一コレクションに簡略化しています。

フィールド 型 必須 説明
title 文字列 はい コレクション名
position 数値 いいえ コレクション内の位置。小数も可（例: 0.5 は特別号・半巻）。雑誌など発行日順で並べる場合は省略

カテゴリファイル categories.json

shelffドキュメントルート直下の.shelffディレクトリに保存される、カテゴリの定義ファイルです。各PDFは最大1つのカテゴリに属します。

例

{
  "version": 1,
  "categories": [
    { "name": "技術書", "order": 0 },
    { "name": "小説", "order": 1 },
    { "name": "論文", "order": 2 }
  ]
}
フィールド 型 説明
version 整数 スキーマバージョン。現在は1
categories 配列 カテゴリの配列。各要素はname（文字列）とorder（整数、0始まり）を持つ

タグファイル tags.json

shelffドキュメントルート直下の.shelffディレクトリに保存される、タグの表示順序ファイルです。タグ自体の定義は各PDFのメタデータファイル内のtagsフィールドで行われます。このファイルはタグの表示順序のみを管理します。

例

{
  "version": 1,
  "tagOrder": ["Swift", "SwiftUI", "プログラミング", "読みかけ"]
}
フィールド 型 説明
version 整数 スキーマバージョン。現在は1
tagOrder 文字列の配列 タグの表示順序。この配列に含まれないタグは名前順で末尾に表示される

拡張フィールド

3種類のファイルはいずれもトップレベルに未定義のフィールドを置けます。他のツールやユーザーが独自のデータを保存する場合は、フィールド名にx-接頭辞を付けてください（例: x-calibre-id）。metadataオブジェクト内も同様で、Dublin Core の標準拡張（dcterms:など）はそのまま使えます。readingとdisplayは未定義のフィールドを許可しません。

shelffを含め、これらのファイルを読み書きするツールは、自分が理解しないフィールドを捨てずに書き戻すことが求められます。

JSON Schema

各ファイル形式のJSON Schemaは以下のリポジトリで公開しています。