Version 0.3

Introduction

OpenChronology is a platform-agnostic standard for storing, sharing, and visualizing chronological data. Unlike legacy timeline formats which focus solely on dates (ISO 8601), OpenChronology treats time as a flexible variable, allowing for the representation of:

• Absolute History — Strictly dated events (Gregorian, Julian).
• Relative Time — Project management (Day 1, Day 5) or video timestamps.
• Fictional Universes — Custom calendars (Stardates, Fantasy Epochs).
• Deep Time — Geologic and cosmic scales.

Universal Portability is the primary goal: an event created in a project management app should be renderable in a historical visualization app without data loss.

1.1 The Document-Per-Event Model

OpenChronology follows a document-per-event architecture. Each event is a standalone, self-contained file — independently citable, linkable, and portable. This is analogous to how the web works: every Wikipedia article is its own URL. Every .chron file is its own citable artifact.

This architecture enables a distributed timeline ecosystem with no central database required. Events live wherever their authors host them, linked by UUID and canonical URL, assembled into timelines by bundle packages or streaming feeds.

A key intended use case is supporting authors, game designers, screenwriters, and world-builders in developing fictional universes — working entirely on a local machine during development, then publishing to the web when ready. All reference types (calendar, universe, asset) support local file paths, absolute file URIs, and remote URLs equally.

1.2 File Family Overview

1.3 Founding Motivation

OpenChronology was born from the 1000 Year Project (1000yearproject.org) — an initiative to document the complete life of a redwood tree from the moment it sprouts to the day it falls, capturing daily photography, environmental sensor data, and eventually full lidar and photogrammetry scans across a millennium.

A redwood alive today may have sprouted before the Magna Carta was signed. Tracking it meaningfully requires a standard that can hold a daily humidity reading and a century of world history with equal precision.

But the same standard that serves a thousand-year tree serves the video game developer building a fictional universe from scratch, the screenwriter mapping a character's journey across decades, the family historian connecting generations across a century, and the project manager tracking a six-week product launch.

File Format

2.1 Reference Resolution

All file references support three addressing modes:

2.2 Date Value Formatting

OpenChronology uses ISO 8601 for all computational date values: YYYY-MM-DD for dates, YYYY-MM-DDTHH:MM:SSZ for datetimes. Negative years represent BCE dates (e.g. -0066-01-01 = 66 BCE).

2.3 Schema Version Compatibility

OpenChronology uses Semantic Versioning. The core compatibility rule: same MAJOR version = compatible. Parsers MUST silently ignore unrecognized fields — this is the mechanism that makes MINOR version compatibility automatic.

The .chron Event File

A .chron file contains exactly one event. It is the atomic, portable unit of the OpenChronology ecosystem. The root object has three blocks: meta, definitions, and event.

{
  "meta": {
    "schema_version": "0.3",
    "author": "String or Array (Optional)",
    "license": "String (Optional)",
    "generator": "String (Optional)",
    "canonical_url": "https://example.com/events/moon-landing.chron",
    "$schema": "https://schemas.openchronology.org/v0.3/core.schema.json"
  },
  "definitions": {
    "universes": { ... },
    "calendars":  { ... },
    "bodies":     { ... }
  },
  "event": { ... }
}

3.1 The meta Block

Only schema_version is required. The canonical_url field is the authoritative hosted URL for this file — it enables cross-file linking and deduplication during merges.

3.2 The definitions Block

Declares the universes, calendars, and bodies referenced by this event. MAY be omitted entirely when using only built-in types. Built-in calendars include: gregorian, julian, islamic, hebrew, chinese, unix, jdn. Built-in universes: real and relative.

External calendars and universes are referenced by URL, file path, or relative path. An inline_fallback field allows a local copy of a calendar definition for offline resilience.

The Calendar Definition File (.chroncal)

A .chroncal file is a standalone JSON document describing a single calendar system — its epoch, structure, and value format. It is independently hosted and referenceable by any number of .chron files.

Calendar structures are either linear (monotonic, non-cyclical — stardates, project counters, geologic time) or cyclic (named months, leap rules — Gregorian, Shire Reckoning, Galactic Standard). Cyclic calendars define their months explicitly; month names become the valid values for temporal.*_value strings.

{
  "meta": {
    "id": "shire-reckoning",
    "version": "1.0.0",
    "display_name": "Shire Reckoning",
    "canonical_url": "https://calendars.tolkienestate.com/shire-reckoning.chroncal"
  },
  "calendar": {
    "epoch": { "reference_universe": "real", "reference_value": "-0600-01-01T00:00:00Z" },
    "structure": { "type": "cyclic", "months": [...], "leap_rule": { ... } },
    "value_format": "YYYY-MMM-DD"
  }
}

The Universe Definition File (.chronverse)

A .chronverse file describes a single universe. The real universe is a built-in and never requires a .chronverse file. All other universes — fictional, relative, or custom — benefit from an external definition.

Universes may declare a default calendar, which events in that universe may inherit, reducing verbosity. They may also declare canon scopes — the authoritative list of valid scope values for relation.canon.scope (e.g. "canon", "legends").

Relative universes are anchored to another universe via an offset and scale factor — enabling fictional chronologies to be mapped against real-world time when an anchor is known (e.g. Star Wars BBY/ABY anchored to 1977-05-25).

{
  "meta": {
    "id": "star-wars-disney",
    "version": "1.0.0",
    "display_name": "Star Wars Galaxy (Disney Canon)",
    "canonical_url": "https://example.com/universes/star-wars-disney.chronverse",
    "$schema": "https://schemas.openchronology.org/v0.3/universe.schema.json"
  },
  "universe": {
    "type": "relative",
    "anchor": {
      "target_universe": "real",
      "offset_value": "1977-05-25T00:00:00Z",
      "scale_factor": 1.0
    },
    "defaults": {
      "calendar": "galactic-standard",
      "calendar_ref": "./calendars/galactic-standard.chroncal"
    },
    "canon_scopes": [
      {
        "id": "canon",
        "display_name": "Disney Canon",
        "description": "All works produced or licensed by Lucasfilm after April 25, 2014."
      },
      {
        "id": "legends",
        "display_name": "Star Wars Legends",
        "description": "Formerly the Expanded Universe — now non-canonical.",
        "superseded_by": "canon"
      }
    ],
    "related_universes": [
      {
        "id": "star-wars-legends",
        "relationship": "variant_of",
        "ref": "https://example.com/universes/star-wars-legends.chronverse"
      }
    ]
  }
}

The Event Object

The event object's type field determines its role. event is the default when type is absent.

6.1 Content & Localization

The content block holds the human-facing data. title is the only required field for non-tombstone events. description_format controls rendering: plain (default), markdown (CommonMark), or html (Full tier only — parsers MUST sanitize). Translations are keyed by BCP 47 locale codes.

"content": {
  "title": "The Council of Elrond",
  "description": "A **pivotal meeting** in Rivendell...",
  "description_format": "markdown",
  "date_label": "25th of Halimath, SR 1418",
  "tags": ["diplomacy", "fellowship"],
  "sources": [
    { "url": "https://en.wikipedia.org/wiki/Council_of_Elrond",
      "title": "Wikipedia — Council of Elrond", "type": "wikipedia" }
  ],
  "translations": {
    "fr": { "title": "Le Conseil d'Elrond", "date_label": "25 Halimath, SR 1418" }
  }
}

6.2 The sources Array

The sources array is the correct location for external citations — Wikipedia articles, official pages, academic papers, archival sources, and any non-.chron URL. Every source requires url, title, and type. An optional description field annotates what the source covers.

6.3 Temporal Data

The temporal block is the computational engine for date resolution. start_value and end_value are calendar-native strings — opaque to parsers until the calendar is resolved. precision expresses confidence: millisecond through epoch, plus circa (which should always pair with an uncertainty block) and custom.

The uncertainty object supports five types: range, before, after, no_earlier_than, no_later_than. An optional confidence field (0.0–1.0) expresses the probability the true date falls within the expressed window.

6.4 Spatial Data

Coordinates follow GeoJSON order: [longitude, latitude, altitude]. Geometry types: Point, Polygon, LineString. The body field references a body identifier — either a built-in or a definition in definitions.bodies.

Built-in body identifiers require no definitions entry: earth (default, WGS84), moon, mars, sun. For custom or fictional bodies, declare a full definition with name, type, and optional crs, image_url, width, height.

6.5 Media

Media items carry a type (video, audio, image, document), a url, and an alt field required for accessibility-compliant renderers. Inside a .chronpkg, asset URLs MAY use the chronpkg:// scheme. Parsers encountering chronpkg:// URLs outside a bundle context MUST NOT throw a fatal error.

6.7 Relations

Relations are Weak References between .chron event files. Every relation requires a target_id — the UUID of the target event. If the target UUID is not present in the current dataset, the parser MUST soft-fail. The target_url field carries the canonical_url of the target .chron file for cross-file resolution.

The optional canon object carries a scope (universe-defined) and a status: canon, legends, disputed, non_canon, or unknown.

6.8 Significance

The significance block drives Level of Detail (LOD) rendering — which events appear at which zoom level. Events without a significance block are always visible at all zoom levels.

value is a 0–1000 score. temporal_scope ranges from epochal through hourly. geographic_scope ranges from global through street. Per-domain metrics support these types: political, military, economic, cultural, scientific, technological, environmental, ecological, demographic, social, medical, religious, personal, narrative, custom.

6.9 Recurrence

Optional. Absence means the event occurs exactly once. frequency.unit values: day, week, month, year, custom — with meaning delegated to the declared calendar. end.type: count (N total occurrences), until (calendar-native end date), or none (perpetual — renderers MUST NOT eagerly expand). Individual instances may be cancelled or modified via the exceptions array.

6.10 Tombstone Events

A tombstone is a minimal record occupying the UUID of a deleted event to prevent re-import during merges. Parsers MUST NOT render tombstone events. Tombstone priority: when merging, a tombstone ALWAYS wins over a non-tombstone with the same UUID regardless of load order. Tombstones MUST NOT be silently stripped from merged output.

A tombstone MUST NOT contain: content, temporal, spatial, relations, recurrence, significance, media, custom_data, or dynamic blocks.

6.11 Deprecated Events

A deprecated event retains all its original data but signals it should be treated with caution. Parsers MUST retain deprecated events in the parsed dataset. The display field controls rendering: visible, distinguished (dimmed or struck-through, default), or hidden (user opts in to show).

Implementation Guidelines

7.1 The Loose Coupling Rule

• Partial Loading — Parsers MUST load an event even if its related events are missing.
• Orphans — Events referencing a missing parent are rendered as top-level items.
• Deduplication — When merging, parsers MUST check id for duplicates. canonical_url SHOULD be used as a secondary deduplication key.
• Tombstone Priority — Tombstone ALWAYS wins over non-tombstone with the same id, regardless of load order.

7.4 Security: Dynamic Formulas

Parsers implementing the dynamic block MUST NOT use eval(), new Function(), exec(), or any mechanism granting formula expressions access to the filesystem, network, or process environment. Parsers MUST use a sandboxed expression evaluator with an explicitly defined function whitelist.

7.5 Display Date Resolution Priority

1. If the active locale's translations entry contains date_label — use it.
2. If the base content block contains date_label — use it.
3. If temporal.format_hint is present — auto-format using pattern, appending era_label.
4. Otherwise — apply renderer default locale-aware formatting.

Transport & Storage Formats

8.1 The Bundle Package (.chronpkg)

A .chronpkg is a ZIP archive — the primary collection format. Directory structure:

bundle.chronpkg  (ZIP archive)
├── manifest.json          ← Required entry point
├── events/
│   └── *.chron
├── calendars/
│   └── *.chroncal
├── universes/
│   └── *.chronverse
├── assets/
│   ├── images/
│   └── datasets/
└── README.md

The manifest.json provides a lightweight index of all contained events. Media assets inside a bundle MAY use the chronpkg:// scheme (resolves relative to assets/). Parsers MUST NOT write chronpkg:// URLs into any storage context outside a bundle archive.

8.2 The Streaming Format (.chronstream)

A .chronstream is Newline-Delimited JSON (NDJSON) — one complete JSON object per line. Line 1 is always the header record; all subsequent lines are event records. The header may declare default_universe and default_calendar that event records inherit, reducing verbosity for homogeneous streams.

Three use cases: API responses for large event datasets, export of geological or fictional timelines with hundreds of thousands of events, and append-only event logs.

Format Comparison

Conformance

9.1 RFC 2119 Key Words

The key words in this specification use the meanings defined in RFC 2119.

9.2 Conformance Tiers

Three tiers, each a strict superset of the one below. Implementations MUST declare which tier they conform to.

9.3 JSON Schema Registry

Machine-readable JSON Schemas (draft/2020-12) are published at schemas.openchronology.org/v0.3/:

Advisory SQL Schema

Non-normative. Implementations are free to store event data in any manner. This schema is provided as a reference for developers building relational database backends. Designed for SQLite, PostgreSQL, and MySQL compatibility.

Design principles: the full event JSON blob is stored in a data column for complete fidelity; indexed columns are projections of frequently-queried fields; temporal values are stored as both calendar-native strings and resolved Unix timestamps; tombstone records MUST be retained — never hard-deleted.

The advisory SQL schema covers seven tables — events, packages, event_relations, event_metrics, event_media, calendars, and universes — with indexes, a tombstone-safe upsert pattern, and example queries.

→ View the Advisory SQL Schema

Changelog