AI Use Guide — OpenChronology

What this page helps you do

Two things you can build with AI

OpenChronology is a format for storing and sharing time-based data as portable .chron files. AI chatbots don’t know this format by default — but a single copied block of text is all they need. There are two things people typically want to accomplish:

Generate `.chron` event files

You have a topic — a period of history, a fictional world, a project plan, a family archive — and you want to produce structured, timeline-ready .chron files you can load into any OpenChronology viewer or tool.

→ Jump to file prompts

Build a timeline viewer

You want to embed a timeline on your own website or app — something that reads .chron files and renders them. The AI can write complete viewer code for you, ready to publish to your site.

→ Jump to viewer prompts

What a rendered timeline looks like — events from .chron files

Step 1 — The Context Block

Copy this. Paste it first.

This block primes your AI with everything it needs to know about the OpenChronology format. Paste it at the start of any new conversation, before your actual request. It works for both paths — generating event files and building viewers.

OpenChronology v0.3 — AI Context Block

~700 tokens · Works with ChatGPT, Claude, Gemini, and others

You are helping create OpenChronology .chron files — an open standard for portable chronological data.

WHAT IS A .chron FILE
Each .chron file stores exactly one event as JSON with a .chron extension.
One event = one file. Files are self-contained and independently citable.

MINIMUM VALID FILE  (only 3 fields are required)
{
  "meta": { "schema_version": "0.3" },
  "event": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "content": { "title": "Name of the event" }
  }
}

RULES
- schema_version is always "0.3"
- event.id must be a UUID v4 — generate a fresh, unique one per file
- event.content.title is the only other required field
- All other fields are optional
- Use kebab-case filenames with .chron extension  (e.g. battle-of-hastings.chron)

FULL FIELD REFERENCE

meta:
  schema_version    "0.3"  (required)
  author            "Name" or ["Name1", "Name2"]
  license           "CC-BY-4.0" or other SPDX identifier
  canonical_url     full URL if hosted

event:
  id                UUID v4 string  (required)
  type              "event" | "era" | "milestone" | "record" | "note"  (default: "event")

  content:          (required)
    title           string  (required)
    description     string — narrative text about the event
    description_format  "plain" | "markdown" | "html"  (default: "plain")
    date_label      string — human-readable date for display, e.g. "July 20, 1969"
    tags            ["tag1", "tag2", ...]
    sources         [ { "title": "Source Name", "url": "https://...", "type": "web" } ]
                    source type options: "primary" | "secondary" | "web" | "academic" | "archive"

  temporal:         (include for any dated event)
    start_value     ISO 8601 string: "1969-07-20" or "1969-07-20T20:17:40Z"
                    BCE dates use negative years: "-0044-03-15" = March 15, 44 BC
    end_value       end date for eras or periods (same format as start_value)
    precision       "millisecond" | "second" | "minute" | "hour" | "day" | "month" |
                    "year" | "decade" | "century" | "millennium" | "epoch" | "circa"
    calendar        "gregorian" (default) | "julian" | "islamic" | "hebrew" | "chinese"
    uncertainty     { "type": "range", "margin_value": 50, "margin_unit": "year" }
                    uncertainty type: "range" | "before" | "after" | "no_earlier_than" | "no_later_than"

  spatial:          (include for events with a location)
    body            "earth" (default) | "moon" | "mars" | "venus" | "mercury" | "sun"
                    Use any string for fictional worlds or custom locations
    geometry        { "type": "Point", "coordinates": [longitude, latitude] }
    region          { "name": "Region Name", "admin_level": "country" }

  significance:     (optional — helps timeline viewers prioritize events)
    value           0–1000  (0 = trivial, 500 = notable, 1000 = civilizational)
    temporal_scope  "epochal" | "millennial" | "centennial" | "generational" | "decadal" |
                    "annual" | "seasonal" | "monthly" | "weekly" | "daily" | "hourly"
    geographic_scope "global" | "continental" | "national" | "regional" | "local" | "street"

WORKED EXAMPLE
{
  "meta": {
    "schema_version": "0.3",
    "author": "Your Name",
    "license": "CC-BY-4.0"
  },
  "event": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "type": "milestone",
    "content": {
      "title": "Apollo 11 Moon Landing",
      "description": "Neil Armstrong and Buzz Aldrin became the first humans to walk on the Moon.",
      "date_label": "July 20, 1969",
      "tags": ["space", "nasa", "moon", "cold-war"],
      "sources": [
        {
          "title": "NASA Apollo 11 Mission",
          "url": "https://www.nasa.gov/mission_pages/apollo/apollo-11.html",
          "type": "web"
        }
      ]
    },
    "temporal": {
      "start_value": "1969-07-20T20:17:40Z",
      "precision": "second",
      "calendar": "gregorian"
    },
    "spatial": {
      "body": "moon",
      "region": { "name": "Sea of Tranquility" }
    },
    "significance": {
      "value": 950,
      "temporal_scope": "epochal",
      "geographic_scope": "global"
    }
  }
}

VALIDATION AND TOOLS
- Validate files:  https://chronology.studio/tools/validator.html
- Visualize files: https://chronology.studio/tools/timeline-viewer/
- Author files:    https://chronology.studio/tools/event-author.html
- Full spec:       https://openchronology.org/specification.html
- Reference parser (ESM, browser-ready): https://openchronology.org/src/openchronology.js

Free to use and share. Published under CC-BY-4.0. Embed it in your own tools, guides, or prompts without attribution.

Step 2 — Using It

Three steps to get started

Works with any AI assistant that accepts a free-text prompt. No account, API key, or technical knowledge required.

Open a new conversation in your AI chatbot

Start fresh — any conversational AI works. A new chat ensures nothing interferes with the context you’re about to provide.

Paste the context block as your first message

Copy the entire block above and send it on its own before anything else. You can optionally end it with: Confirm you understand this format and are ready to help. The AI will acknowledge it.

Make your request — use the examples below

In your next message, describe what you want. Use the prompts in the sections below as starting points. The AI will generate complete, valid output you can use immediately.

Path A — Generating .chron files

Example prompts for creating event files

These prompts produce valid .chron files you can load directly into a viewer or the tools at Chronology Studio.

Historical Research

Generate 10 .chron files covering the major events of the French Revolution, from 1789 to 1799. Include dates, descriptions, tags, and significance scores. Output each file separately with a clear filename.

Tip: Ask for a specific era or event count. The AI will spread significance values to reflect relative importance.

Fiction & World-Building

I'm building a fantasy world called Aeryndal. Create .chron files for 8 founding events of the kingdom spanning 1,200 years of in-world history. Use type "era" for multi-century events and "milestone" for pivotal moments.

Tip: Use any string for body — e.g. "aeryndal". The calendar field accepts "gregorian" as a stand-in for custom systems.

Project Management

Convert this project plan into .chron files: [paste your milestones]. Use type "milestone" for deliverables and "era" for phases. Set precision to "day" and tag each event with its project phase.

Tip: Paste a bullet list of milestones directly into your prompt. The AI will extract dates and structure everything correctly.

Family History

Create .chron files for my grandmother's life story from these notes: [paste your notes]. Where exact dates are unknown, use precision "year" or "circa" with an appropriate uncertainty margin.

Tip: The uncertainty field handles approximate dates gracefully — ideal for genealogy and oral history.

Science & Discovery

Generate .chron files for 12 pivotal moments in the history of human spaceflight from Sputnik to today. Include spatial data (body = "earth" for launches, "moon" for lunar events) and cite NASA sources.

Tip: The body field lets you anchor events to specific planets or moons — great for space history.

News & Current Events

I'm building a timeline of [topic] from [start year] to today. Generate .chron files for the 15 most significant events. Include a date_label for each and set geographic_scope based on the event's actual reach.

Tip: geographic_scope drives how a viewer weights events — set it deliberately.

Path B — Building a timeline viewer

Example prompts for building your own viewer

The OpenChronology reference parser is a ready-made ESM module you can point your AI at. These prompts produce complete, self-contained viewer code ready to publish on your own website.

Simple Vertical List

Using the OpenChronology reference parser at https://openchronology.org/src/openchronology.js, build a vanilla JS timeline viewer that fetches an array of .chron file URLs, sorts them by start_value, and renders a vertical list showing date_label and title for each event.

Tip: Good first viewer — readable, fast, works in any browser without a framework.

Horizontal Scrolling Timeline

Build an interactive horizontal timeline using the OpenChronology parser. Events should be positioned proportionally by date on a scrollable axis. Show event dots sized by significance value. On click, expand a card with title and description.

Tip: Ask for it in vanilla JS or React — specify your stack. The parser handles date resolution automatically.

Card-Based Feed

Build a responsive card grid that reads .chron files and displays each event as a card with its title, date_label, description (first 200 characters), and tags as chips. Sort by significance descending. Use CSS Grid.

Tip: Great for curated collections where you want the most important events to surface first.

Styled for Your Brand

Build a timeline viewer using the OpenChronology parser that matches my site's style: [describe your colors, fonts, layout]. Load events from a local array of .chron objects. Each event shows title, date_label, and a collapsible description.

Tip: Describe your visual style or paste a link to your site — the AI will match it.

Best Practices

Tips for better results

Start a fresh conversation each session. Re-paste the context block whenever you start a new chat. Without it, AI models revert to guessing field names and formats.

Ask for files in batches of 5–10. Smaller batches prevent the AI from truncating or rushing the last files in a long list.

Always validate generated files. Drop each file into the Validator at Chronology Studio. It catches missing fields and malformed UUIDs instantly.

Check UUIDs for uniqueness. Some AI models reuse the example UUID from the context block. Ask: “Regenerate any files that share a UUID — every event must have a unique id.”

Approximate dates are better than no dates. Don’t omit temporal just because an exact date is unknown. A precision of “circa” with an uncertainty margin is far more useful in a viewer than a missing date entirely.

For viewer builds, point the AI at the reference parser. The URL https://openchronology.org/src/openchronology.js is in the context block. Using it produces cleaner code than asking the AI to parse .chron files from scratch.

After Generation

What to do with your output

What you do next depends on which path you took.

If you generated .chron files — Path A

Your AI-generated files are ready to use with the tools at Chronology Studio. Everything runs in your browser — nothing is uploaded to a server.

01 — Validate

Validator & Upgrader

Drag in your files for instant schema validation. Catches errors before they reach a viewer.

02 — Visualize

Timeline Viewer Gallery

Four rendering styles — Horizon, Codex, Ledger, Gantt. Drop your files in and see them rendered immediately.

03 — Refine

Event Author

Import any .chron file to edit fields, adjust significance, and re-export — no JSON editing required.

If you built a timeline viewer — Path B

Your AI-generated viewer is ready to go live. Here is how to get it onto the web.

01 — Standalone page

Publish as its own webpage

Save the viewer as an .html file and upload it to any web host. Place your .chron files on the same server or a CORS-enabled domain. Link to it from your site, social profiles, or anywhere you like.

02 — Embed in a page

Add it to an existing site

Using WordPress, Webflow, Squarespace, or similar? Paste the viewer’s HTML and JS into a Custom HTML or Embed block. Most platforms support this directly in their page editor.

03 — Framework integration

Integrate with your tech stack

Working with React, Vue, Next.js, Astro, or another framework? Ask the AI to convert the viewer into a component for your stack. The OpenChronology parser is an ESM module — it drops in cleanly to any modern JS project.

04 — Share the standard

Tell others it’s OpenChronology

Linking back to openchronology.org or noting the standard your viewer uses helps grow the ecosystem — making it easier for others to contribute events, build compatible tools, and preserve timelines for the long term.

Two things you can build with AI

Generate .chron event files

Build a timeline viewer

Copy this. Paste it first.

Three steps to get started

Example prompts for creating event files

Example prompts for building your own viewer

Tips for better results

What to do with your output

If you generated .chron files — Path A

If you built a timeline viewer — Path B

Generate `.chron` event files