Core Concepts

← Back to Documentation Index

Understanding Canonical Timeline starts with its five-layer data model. Every piece of evidence in your investigation lives in one of these layers.

The Five-Layer Data Model

1. Timelines

A timeline is the top-level container for an investigation. It defines:

• Scope: What question is being investigated? What time period?
• Status: The investigation phase — fact-finding, verification, ongoing, or resolved.
• Access: Multi-tenant. Timelines belong to an account. Within an account, access is controlled by role (owner, admin, contributor, reader).

Each timeline contains events, which contain claims, which cite sources. Entities can be linked across timelines.

A timeline is a contract: everything within it is in scope for your investigation. Everything outside is noise.

2. Events

An event is a time-anchored node — something that happened at a specific point in time.

Every event has:

• A title — a concise description (e.g., "Board meeting at HQ")
• A canonical time — the best-known timestamp (ISO 8601)
• A time precision — how certain you are about that time
• A status — the verification state
• An optional description — context and details
• An optional location — geographic coordinates or named place

Events appear in chronological order within their timeline.

Time Precision Levels:

The system also tracks a time_confidence score (0–100) on every event. If you don't know the exact time, be honest about your uncertainty. The tool demands honesty, not fabricated precision.

Event Statuses:

An event can have one of 9 statuses. These communicate the verification state to other curators:

3. Claims

A claim is a factual assertion attached to an event, backed by a source.

Claims are the connective tissue between what happened (the event) and the evidence (the source). Every claim has:

• Claim text — the assertion itself (e.g., "The CEO was present at the board meeting")
• Source — the document or reference that supports (or refutes) this claim
• Claim status — the verification grade
• Confidence score — your quantitative confidence (0–100)

Claim Statuses:

Claims proven false are not deleted. Their status is changed to reflect the contradiction. The revision history preserves every judgment for audit.

Confidence Score:

The confidence score is a number from 0 to 100 (displayed as a percentage). It represents your assessment of the claim's accuracy:

• 0–25: Very low confidence — the claim is highly uncertain
• 26–50: Low confidence — more evidence needed
• 51–75: Moderate confidence — supported by evidence but not definitive
• 76–100: High confidence — well-sourced and verified

Confidence is always the curator's judgment. The system never asserts truth — it records who asserted what, with what confidence, citing what source. This preserves editorial accountability and makes the system usable in adversarial contexts where two curators may grade the same claim differently.

4. Sources

A source is a reference document that supports one or more claims. Sources are the foundation of every investigation's credibility.

Every source has:

• Title — the document's name
• Source type — one of 175+ types (e.g., news_article, court_document, intelligence_report, satellite_imagery, diplomatic_cable, leaked_document)
• Author — who created or published it
• Publication date — when it was published
• URL — a link to the source (if online)
• Checksum — a hash of the uploaded file for integrity verification
• File attachments — uploaded documents (PDFs, images, text files)
• Extracted content — text extracted from uploaded files or crawled URLs
• Raw content — unprocessed source text

Sources can be linked to claims. A single source can support multiple claims across different events.

5. Entities and Relationships

An entity is a named actor — a person, organization, object, or concept relevant to your investigation.

Every entity has:

• Canonical name — the full, official name (e.g., "John D. Rockefeller")
• Aliases — alternative names or code names
• Entity type — one of 170+ types (e.g., person, corporation, government_agency, military_unit, shell_company, front_company, vessel)

Entities can be:

• Linked to events — an entity participated in or was affected by an event
• Related to other entities — directed relationships like works_for, owns, reports_to, involved_in

Relationship properties:

• Direction: from one entity to another (e.g., Alice → works_for → Acme Corp)
• Time scoping: valid_from and valid_to dates — a relationship might only have existed during a specific period
• Confidence: how sure you are about this relationship

The Curation Methodology

Canonical Timeline encodes a structured process for building and verifying chronologies:

1. Scope — Define the timeline boundary. What question are you investigating? What period?
2. Aggregate — Add events with the best available timestamps, using the precision qualifier that matches your certainty.
3. Source — For every factual assertion, attach a verifiable source. The system distinguishes between types of sources and treats them differently.
4. Verify — Grade each claim's accuracy using the status scale and confidence score. The system provides the framework; you determine the facts.
5. Relate — Link entities to events, entities to entities, and events to events. Build the graph.
6. Audit — Every change is recorded in an append-only revision log. Nothing is ever truly deleted.

Key Design Principles

The System Does Not Decide What Is True

Every confidence score, every claim status, every relationship weighting is assigned by a human curator. The system records who asserted what, with what confidence, citing what source, at what time. It never makes the assertion itself.

Time Precision, Not Time Certainty

Real-world events rarely have precise timestamps. The system accepts uncertainty ranges and confidence qualifiers. A tool that demands exact times forces the curator to fabricate precision. This tool forces you to be honest about what you don't know.

Status Scales for Every Object

Statuses are not trivia — they are the operational language of verification. A timeline in fact-finding status signals "expect gaps." An event with alleged status signals "this may not be true." A claim with confidence 45 and status rumored signals "do not rely on this."

Revision as First-Class Infrastructure

Every mutation generates an append-only revision record with before/after snapshots. There is a permanent, queryable record of who changed what and when. This is essential for any system used in legal, journalistic, or intelligence contexts.

Multi-Tenant with Bundled Demos

Accounts are isolated. Each has its own timelines, events, entities, and sources. But demo datasets (Apollo 11, Watergate, Berlin Wall, Operation Ghost Courier) can be activated per-account as read-only templates to explore the application before creating your own data.

Extensible Type System

The 175+ source types, 170+ entity types, and event relationship types are database rows with names, descriptions, colors, and icons — not hardcoded. Accounts can create, hide, and manage their own taxonomies.

Next: Working with Timelines →