群島舎

shelff JSON仕様

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

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

概要

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

ファイル 場所 役割
*.pdf.meta.json 各PDFと同じディレクトリ 個別PDFのメタデータ・読書進捗・表示設定
categories.json shelffドキュメントルート カテゴリの定義と順序
tags.json 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"
  },
  "category": "技術書",
  "tags": ["Swift", "入門"]
}

トップレベルフィールド

フィールド 型 必須 説明
schemaVersion 整数 はい スキーマバージョン。現在は1
metadata オブジェクト はい 書誌メタデータ（後述）
reading オブジェクト いいえ 読書進捗（後述）
display オブジェクト いいえ 表示設定（後述）
category 文字列 いいえ カテゴリ名（1つのPDFにつき1つ）
tags 文字列の配列 いいえ タグ名の配列

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"

カテゴリファイル categories.json

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

例

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

タグファイル tags.json

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

例

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

JSON Schema

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