Timeline Format

Overview

Cronolog supports two import/export formats:

When importing a ZIP, image files are read from the paths declared in each event's images[].path field. When importing a JSON file, all images arrays are ignored.

ZIP archive layout

timeline.zip
├── timeline.json          ← manifest (required)
├── images/
│   ├── cover.jpg          ← cover image (optional, path declared in manifest)
│   └── events/
│       ├── 0/             ← first event (index matches event order in manifest)
│       │   ├── photo.jpg
│       │   └── photo2.webp
│       ├── 1/
│       │   └── photo.jpg
│       └── …

Image filenames within each directory are taken from the original blob filenames. The directory index (0, 1, …) corresponds to the event's position in the events array.

JSON schema

Date formats for date_input_raw

Cronolog's date parser accepts a wide range of human-readable formats. The corresponding start_at, end_at, precision, and precision_unit values are derived from the input.

Two-digit years use a rolling pivot: values ≤ the current two-digit year resolve to this century; larger values resolve to the previous century. Approximation prefixes (circa, ca., ~) are stripped before parsing.

Complete example

A minimal but complete timeline.json with two events — one exact date, one date range — and one image attachment.

{
  "format_version": 1,
  "source_timeline_id": 42,
  "exported_at": "2025-11-03T14:22:00Z",
  "timeline": {
    "title": "Life of Francis",
    "description_raw": "A record of my grandmother's life.",
    "visibility": "private",
    "sort_direction": "asc",
    "cover_image": "images/cover.jpg",
    "cover_image_metadata": {
      "focal_x": 0.5,
      "focal_y": 0.3
    }
  },
  "taxonomy_terms": [
    { "name": "Travel" },
    { "name": "Canada", "parent_name": "Travel" }
  ],
  "events": [
    {
      "title": "Moved to Vancouver",
      "description_raw": "She was 19. \"I only had one suitcase.\"",
      "date_input_raw": "1962",
      "end_date_input_raw": null,
      "start_at": "1962-01-01T00:00:00Z",
      "end_at": "1962-12-31T23:59:59Z",
      "precision": "bounded",
      "precision_unit": "year",
      "display_label": "1962",
      "tags": ["Travel", "Canada"],
      "images": []
    },
    {
      "title": "World tour",
      "description_raw": "First time abroad. Three months, twelve countries.",
      "date_input_raw": "July 1971",
      "end_date_input_raw": "September 1971",
      "start_at": "1971-07-01T00:00:00Z",
      "end_at": "1971-09-30T23:59:59Z",
      "precision": "bounded",
      "precision_unit": "month",
      "display_label": "July - September 1971",
      "tags": ["Travel"],
      "images": [
        {
          "path": "images/events/1/passport.jpg",
          "content_type": "image/jpeg",
          "position": 1,
          "metadata": {
            "focal_x": 0.48,
            "focal_y": 0.35,
            "photo_taken_at": "1971-08-15T00:00:00Z"
          }
        }
      ]
    }
  ]
}