Guntosha

Overview

shelff uses three types of JSON files.

The metadata file (*.pdf.meta.json) is automatically created when a PDF is first opened in shelff. At that point, dc:title is set to the filename.

All files use UTF-8 encoding. Dates are recorded in ISO 8601 format.

Metadata File *.pdf.meta.json

A metadata file corresponds to a single PDF file. It is stored in the same directory as the PDF, with .meta.json appended to the original filename.

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

Example

{
  "schemaVersion": 1,
  "metadata": {
    "dc:title": "Introduction to Programming",
    "dc:creator": ["Jane Smith"],
    "dc:publisher": "Tech Press",
    "dc:date": "2024",
    "dc:language": "en",
    "dc:subject": ["Programming", "Introduction"],
    "dc:identifier": "978-0-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": "Introduction to Programming Series", "position": 1 },
  "category": "Technical",
  "tags": ["Swift", "Beginner"],
  "bookmarks": [
    { "page": 3, "label": "Important diagram" },
    { "page": 15 },
    { "page": 42 }
  ]
}

Top-level Fields

metadata Object

Bibliographic metadata. Field names use dc:-prefixed keys based on Dublin Core Metadata Terms.

reading Object

display Object

display.crop Object

A non-destructive margin crop applied when rendering pages. The PDF file is never modified; readers apply the crop to the displayed page bounds.

Parity is determined by the PDF page number (1-based) and is independent of pageLayout and direction. For a uniform crop, write the same values to both odd and even.

odd / even are objects with the following four fields. Values are ratios (0.0–1.0) of the page's MediaBox, expressed in the page's displayed orientation (after /Rotate is applied).

Each value must be >= 0, with top + bottom < 1 and left + right < 1. Readers treat a crop that violates these constraints as absent rather than failing. Tools that rewrite display must preserve crop.

bookmarks Array

An array of user-defined page bookmarks (digital "sticky notes"). These are distinct from the PDF's built-in document outline; readers add them to mark pages of interest.

collection Object

An object representing the series or magazine a PDF belongs to. Inspired by EPUB's belongs-to-collection / group-position, simplified to a single collection without a type distinction.

Categories File categories.json

Stored in the .shelff directory under the shelff document root, this file defines the available categories. Each PDF can belong to at most one category.

Example

{
  "version": 1,
  "categories": [
    { "name": "Technical", "order": 0 },
    { "name": "Fiction", "order": 1 },
    { "name": "Papers", "order": 2 }
  ]
}

Tags File tags.json

Stored in the .shelff directory under the shelff document root, this file defines the display order of tags. Tags themselves are defined in the tags field of each PDF's metadata file. This file only manages display ordering.

Example

{
  "version": 1,
  "tagOrder": ["Swift", "SwiftUI", "Programming", "To Read"]
}

Extension Fields

All three files allow additional top-level fields. Third-party tools and users storing custom data should use the x- prefix (e.g. x-calibre-id). The same applies inside the metadata object, where standard Dublin Core extensions such as dcterms: are also welcome. The reading and display objects do not allow additional fields.

Any tool that reads and writes these files, shelff included, must preserve fields it does not understand and write them back unchanged.

JSON Schema

Formal JSON Schema definitions for each file format are available in the following repository.

• github.com/skoji/shelff-schema