Getting Started
Working with Data
Tools & Analysis
Revision History
Every change to any object in Canonical Timeline is recorded in an append-only revision log. You can inspect the full history of any timeline, event, claim, source, entity, or relationship.
Why Revision History Matters
In evidence-based work, provenance is everything. The revision history answers:
- Who made a change?
- What changed? (before and after)
- When was the change made?
- Why was it changed? (inferred from context, not explicit)
This is table stakes for any system used in legal, journalistic, or intelligence contexts. It provides accountability, auditability, and the ability to reconstruct any previous state.
Viewing Revision History
For Any Object
Every object detail page has an Audit History button (Clock icon) in the header:
- Navigate to the object's detail page:
- Timelines: timeline detail page header
- Events: event detail page header
- Sources: source detail page header
- Entities: entity detail page header
- Click the Audit History (Clock icon) button.
- The Revision History dialog opens.
The Audit History button is hidden on read-only (sample) objects.
The Revision History Dialog
The dialog shows a chronological list of revisions for the selected object.
Each revision entry shows:
- Timestamp — When the change was made (formatted date and time)
- User — Who made the change
- Change type — Created, Updated, or Deleted
- Before state — The object's state before the change (JSON snapshot)
- After state — The object's state after the change (JSON snapshot)
- Diff view — A visual comparison of what changed between the before and after states
Reading a Revision Entry
Revisions are listed in reverse chronological order (newest first). Each entry captures the complete state of the object as a JSON snapshot:
{
"id": "rev_abc123",
"timestamp": "2024-03-15T14:30:00Z",
"user_id": "user_xyz",
"change_type": "updated",
"object_type": "events",
"object_id": "evt_123",
"previous_state": { "title": "Old Title", "status": "reported", ... },
"new_state": { "title": "New Title", "status": "confirmed", ... }
}The previous_state and new_state fields are complete JSON representations of the object. Comparing them reveals exactly what changed — a field added, modified, or removed.
Understanding Diffs
When viewing a revision:
- Fields that changed are visually highlighted.
- Fields that stayed the same are shown in a muted style.
- Fields that were added appear only in the after state.
- Fields that were removed appear only in the before state.
This allows you to identify, for example, that on March 15 at 2:30 PM, a specific user changed an event's status from reported to confirmed.
What Is Recorded
Revisions are created for:
| Action | Recorded |
|---|---|
| Create | ✅ Initial state recorded |
| Update (any field) | ✅ Before and after states recorded |
| Delete (soft delete) | ✅ Deletion event recorded; data is archived |
| Hard delete | ❌ Not recorded (use soft delete) |
Every mutation — regardless of how it was made (UI, API, or MCP tool) — generates a revision record.
Soft Delete and Recovery
Objects in Canonical Timeline are never truly deleted. When you delete an object:
- The object is soft-deleted — flagged as deleted but the data remains in the database.
- A revision record is created documenting the deletion.
- The object no longer appears in lists or searches.
Soft-deleted objects can be recovered by an administrator through backend operations. Contact your system administrator if you need to recover deleted data.
Revision History for Different Object Types
| Object Type | What's Tracked |
|---|---|
| Timeline | Title, slug, status, summary |
| Event | Title, description, canonical_time, time_precision, status, location_id |
| Claim | claim_text, claim_status, confidence_score, source_id, needs_review |
| Source | Title, source_type, author, published_at, URL, checksum, last_validated_at |
| Entity | canonical_name, aliases, entity_type_id |
| Relationship | from_entity, to_entity, relationship_type, valid_from, valid_to |
| Annotation | Content text |
Using Revision History in Your Workflow
Verifying Changes
If you question why a claim's status changed from verifiable to fact, check the revision history. You'll see who changed it, when, and what the claim looked like before and after. This allows you to follow up with the curator if needed.
Reconstructing Past States
If you need to know what a timeline looked like on a specific date, review the revisions for that date. The before/after snapshots let you reconstruct the timeline's state at any point in time.
Auditing
For compliance or editorial review, the revision history provides a complete audit trail. Every change is attributable and timestamped.
Dispute Resolution
If two curators disagree about a claim's status, the revision history shows the sequence of changes — who changed what and when. This factual record supports evidence-based dispute resolution rather than relying on memory.