Sidecar Files

Sidecar files are standalone JSON metadata files stored alongside your book files on disk. They provide a portable, human-readable backup of book metadata that can be imported into Grimmory or used with other tools.

---

File Format

For a book named MyBook.epub, the sidecar files are:

• MyBook.metadata.json containing all metadata
• MyBook.cover.jpg (optional) containing the cover image

The JSON file follows this structure:

{
  "version": "1.0",
  "generatedAt": "2026-01-15T10:30:00Z",
  "generatedBy": "booklore",
  "metadata": {
    "title": "My Book",
    "authors": ["Author Name"],
    "publisher": "Publisher",
    "publishedDate": "2025-03-15",
    "description": "...",
    "isbn13": "9781234567890",
    "categories": ["Fiction", "Thriller"],
    "language": "en",
    "pageCount": 350
  }
}

Included Fields

• Title, subtitle, authors, publisher, published date, description
• ISBN-10, ISBN-13, page count, language
• Categories, moods, tags
• Series name, number, and total count
• External identifiers (ASIN, Goodreads ID, Google ID, Hardcover ID, ComicVine ID, and others)
• Ratings from each metadata provider (average and count)
• Age rating, content rating
• Audiobook-specific fields (narrator, abridged)
• Comic metadata (for comic books)

Only non-null fields are included in the output.

---

Settings

Configure sidecar behavior in Settings > Metadata Settings under the Metadata Persistence section:

Setting	Description
Write on Update	Automatically write sidecar files when metadata is changed
Write on Scan	Automatically write sidecar files during library scans
Include Cover File	Save a .cover.jpg alongside the JSON file

---

Per-Book Operations

In the Metadata Center, the Sidecar tab shows:

• A sync status badge indicating whether the sidecar is in sync, outdated, conflicting, missing, or not applicable
• The current sidecar JSON content
• Export button to write the sidecar file to disk
• Import button to update Grimmory metadata from an existing sidecar file

---

Library-Wide Operations

In Settings > Library Metadata Settings, each library has bulk sidecar options:

• Export All generates sidecar files for every book in the library
• Import All reads sidecar files from disk and updates Grimmory metadata for all books that have them