EGT Format

Evidence-Graded Timeline Specification

Version 1.0 · Status: Draft · Last updated: 2026-05-19

Evidence-Graded Timeline (EGT)

Specification, version 1.0 Status: Draft for review Last updated: 2026-05-19

1. Purpose

EGT is a portable file format for evidence-graded timeline papers — investigative, historical, or policy documents that combine a chronological narrative with explicit confidence grading and citations.

The format is designed to:

Separate what is known from what is claimed from what is argued.
Be authored by humans in a plain-text editor.
Be rendered consistently across different platforms (web, print, PDF, slide decks, e-readers) by independent renderers.
Be validatable by tooling (linters, CI checks, schema validators).

EGT is not a layout format. It is a content-and-evidence format. Visual presentation is delegated to renderers.

2. File format and extension

Canonical interchange format: JSON (RFC 8259).
Recommended authoring format: YAML 1.2 (a strict superset of JSON).
Schema: A single JSON Schema (draft 2020-12) document is the source of truth and validates both YAML and JSON files.

File extensions

Form	Extension	MIME type (proposed)
YAML	`.egt.yaml` or `.egt.yml`	`application/egt+yaml`
JSON	`.egt.json`	`application/egt+json`

Renderers MUST accept either form. Conversion between YAML and JSON is lossless.

Encoding

Files MUST be UTF-8.

3. Top-level document structure

An EGT document is a single object (map) with the following top-level keys.

Key	Required	Type	Purpose
`egt`	yes	string	Format version. Must be `"1.0"` for this spec.
`metadata`	yes	object	Document-level metadata.
`tldr`	yes	string (multi-line)	The punchline.
`cast`	no	array of objects	People and institutions referenced.
`phases`	no	array of objects	Optional grouping of timeline entries.
`timeline`	yes	array of objects	The chronological spine.
`interpretation`	no	array of objects	Labeled opinion blocks.
`recommendations`	no	array of objects	Policy/action items.
`sources`	yes	array of objects	Numbered bibliography.
`methodology`	no	string (multi-line)	How confidence was assigned.

Unknown top-level keys MUST be ignored by renderers (forward compatibility).

4. Field reference

4.1 `egt`

egt: "1.0"

The format version. Renderers MUST refuse to render documents whose major version they do not support.

4.2 `metadata`

metadata:
  title: "How the Netherlands Helped Pakistan — and Then Iran — Build Nuclear Weapons"
  subtitle: "..."          # optional
  eyebrow: "Evidence-Graded Timeline · Nuclear Proliferation"  # optional
  authors:                 # optional
    - name: "Johb Doe"
      email: "john.doe@example.com"
      affiliation: "..."   # optional
  scope:                   # optional
    from: "1972"
    to: "2026"
  created: "2026-05-19"    # ISO 8601 date, optional
  updated: "2026-05-19"    # ISO 8601 date, optional
  language: "en"           # ISO 639-1, optional, default "en"
  license: "CC-BY-4.0"     # SPDX identifier, optional
  doi: "..."               # optional

title is required. All other fields are optional.

4.3 `tldr`

A multi-paragraph string giving the document's core conclusion. Required.

tldr: |
  Between 1972 and 1975, Pakistani metallurgist A. Q. Khan stole
  URENCO centrifuge designs while working at a Dutch subcontractor.

  The failure was structural: weak vetting, ignored whistleblowers,
  geopolitical pressure, and weak export controls.

Renderers SHOULD format paragraph breaks (blank lines) appropriately.

4.4 `cast`

An array of people, institutions, or other named entities referenced in the document.

cast:
  - name: "A. Q. Khan"
    role: "Pakistani metallurgist (1936–2021); the central figure."
  - name: "Frits Veerman"
    role: "FDO photographer (1944–2021); whistleblower."

Each entry has a name (required) and role (required, one-line description).

4.5 `phases` (optional)

For long timelines, entries may be grouped into phases. Phases do not contain entries directly — they reference entries by ID.

phases:
  - id: "p1"
    title: "Phase 1 · The Netherlands (1972–1975)"
    entries: ["e1", "e2", "e3", "e4", "e5", "e6", "e7"]

If phases is absent, the timeline is presented as a single flat sequence in document order.

If phases is present, every entry in timeline SHOULD be referenced by exactly one phase. Renderers MAY warn on orphans.

4.6 `timeline`

The chronological spine. Required, non-empty.

timeline:
  - id: "e1"
    date: "1972-05"
    dateLabel: "May 1972"
    headline: "Khan joins FDO in Amsterdam"
    body: |
      Fresh from a PhD in metallurgy at Leuven, Khan begins work at FDO,
      a subcontractor to Ultra-Centrifuge Nederland (UCN), part of URENCO.
    confidence: fact
    sources: ["s1", "s3"]
    notes: "Optional editorial notes, hidden from default renderers."

Fields per entry:

Field	Required	Type	Notes
`id`	yes	string	Unique within the document. Lowercase letters, digits, hyphens, underscores.
`date`	yes	string	ISO 8601 calendar date. May be year-only (`"1975"`), year-month (`"1975-12"`), or full date (`"1975-12-15"`). Used for sorting and filtering.
`dateLabel`	no	string	Display label. If absent, renderers SHOULD format `date` appropriately.
`headline`	yes	string	One-line event title.
`body`	yes	string (multi-line)	The substantive content.
`confidence`	yes	enum	One of `fact`, `conjecture`, `opinion`. See §5.
`sources`	no	array of source IDs	References into `sources[]`. Required when `confidence` is `fact` or `conjecture`. Optional when `opinion`.
`notes`	no	string	Editorial notes. Renderers MAY hide by default.
`tags`	no	array of strings	Free-form topical tags for filtering.

Entries SHOULD be ordered chronologically in the source file. Renderers MAY reorder by date.

4.7 `interpretation` (optional)

Labeled opinion blocks. Used for analysis sections that interpret the timeline without making new factual claims.

interpretation:
  - id: "i1"
    label: "Who was responsible"
    body: |
      The failure was institutional, not personal.
      FDO and URENCO failed at industrial security...
    sources: ["s4"]   # optional; allowed when interpretation cites sources

All interpretation blocks are implicitly confidence: opinion. The confidence field MUST NOT appear on interpretation blocks.

4.8 `recommendations` (optional)

Action items, policy proposals, or similar. Implicitly opinion.

recommendations:
  - id: "r1"
    title: "Pass the Knowledge Security Screening Act now, not in 2027."
    body: |
      The two-year lag is exactly the institutional reflex that produced Khan.
    sources: ["s15"]  # optional

4.9 `sources`

The numbered bibliography. Required.

sources:
  - id: "s1"
    title: "A. Q. Khan Nuclear Chronology"
    publisher: "Carnegie Endowment for International Peace"
    url: "https://carnegieendowment.org/research/2005/09/a-q-khan-nuclear-chronology"
    accessed: "2026-05-19"   # ISO 8601, optional
    author: "..."            # optional
    published: "2005-09"     # optional

Fields per source:

Field	Required	Type	Notes
`id`	yes	string	Unique. Convention: `s1`, `s2`, ... but any matching `^[a-z0-9_-]+$` is allowed.
`title`	yes	string
`url`	no	string (URL)	At least one of `url` or a citation field SHOULD be present.
`publisher`	no	string
`author`	no	string
`published`	no	string	ISO 8601 date or year.
`accessed`	no	string	ISO 8601 date.
`type`	no	enum	`article`, `book`, `report`, `dataset`, `interview`, `legal`, `other`.

4.10 `methodology` (optional)

A short prose block explaining how confidence was graded for this document. Renderers SHOULD display this prominently (e.g., footer).

methodology: |
  This document uses the EGT format v1.0.
  Fact requires corroboration from at least two independent credible sources.
  Conjecture covers plausible but single-sourced or contested claims.
  Opinion covers the author's interpretation.

5. Confidence model

EGT v1.0 defines exactly three confidence levels.

Level	Identifier	Meaning
Fact	`fact`	Documented in two or more independent credible sources; no serious dispute among specialists in the field.
Conjecture	`conjecture`	Single-sourced, contested, or based on inference. Plausible and reported, but not definitively established.
Opinion	`opinion`	The author's interpretation, judgment, or recommendation. Not a claim about what happened.

Rules:

Every timeline entry MUST carry exactly one confidence value.
All interpretation and recommendations blocks are implicitly opinion.
Entries with confidence: fact or confidence: conjecture MUST include at least one source.
Entries with confidence: opinion MAY omit sources.
EGT v1.0 does not permit custom confidence levels. Future versions may add levels under a separate field.

Renderers MUST visually distinguish the three levels (color, icon, badge, label, or equivalent). The exact visual treatment is implementation-defined.

6. Source referencing

Sources are declared once in the top-level sources array with stable IDs.
Timeline entries, interpretation blocks, and recommendations reference sources by ID in their sources array.
A validator MUST reject documents where any referenced source ID does not exist in the sources array.
A validator SHOULD warn on sources declared but never referenced.
The same source MAY be referenced from any number of entries.

7. Identifiers

All id values (entries, interpretation blocks, recommendations, sources, phases) MUST:

Be unique within their respective array.
Match the pattern ^[a-z0-9][a-z0-9_-]*$.
Be stable. Once published, an id SHOULD NOT change, so that external references remain valid.

8. Dates

EGT uses two parallel representations:

date is machine-readable. It MUST be one of: a four-digit year ("1975"), a year-month ("1975-12"), or a full ISO 8601 date ("1975-12-15"). It is used for sorting, filtering, and computation.
dateLabel is human-readable. It is a free-form string that renderers display verbatim. Use this for fuzzy historical dates like "Late 1974", "Mid-1975", or "1975 (timing disputed)".

If dateLabel is absent, renderers SHOULD format date in a locale-appropriate way.

For events whose timing is uncertain, set date to the best-known approximation (the year, the month) and disambiguate in dateLabel.

9. Versioning

EGT follows semantic versioning at the format level.

Major version changes (e.g., 1.0 → 2.0) MAY break backward compatibility.
Minor version changes (e.g., 1.0 → 1.1) add fields but do not break existing documents. Renderers conforming to 1.0 MUST ignore unknown fields.
Patch changes (1.0.0 → 1.0.1) clarify the spec without changing semantics.

The egt top-level field declares the version a document targets. Renderers MUST refuse documents declaring an unsupported major version.

10. Conformance

10.1 Documents

An EGT document is conformant if and only if:

It is well-formed YAML 1.2 or JSON (RFC 8259).
It validates against the EGT JSON Schema for its declared major version.
Every sources reference resolves to an existing source ID.
Every entry in a phases.entries list resolves to an existing timeline entry ID.

10.2 Renderers

A renderer is conformant if and only if:

It accepts both YAML and JSON forms of EGT documents.
It rejects documents that fail document conformance.
It visually distinguishes the three confidence levels.
It preserves all required fields in the rendered output (title, tldr, every timeline entry's headline/body/date, every cited source).
It refuses or warns when asked to render a document declaring a major version it does not support.

Renderers MAY add features beyond the spec (filtering, search, dark mode, etc.) but MUST NOT alter the meaning of any required field.

11. Worked example (skeleton)

egt: "1.0"

metadata:
  title: "How the Netherlands Helped Pakistan — and Then Iran — Build Nuclear Weapons"
  subtitle: "The Nuclear Bomb That Walked Out of Amsterdam"
  authors:
    - name: "Johb Doe"
  scope:
    from: "1972"
    to: "2026"
  updated: "2026-05-19"

tldr: |
  Between 1972 and 1975, A. Q. Khan stole URENCO centrifuge designs in the
  Netherlands. Iran's current centrifuges are direct descendants.

cast:
  - name: "A. Q. Khan"
    role: "Pakistani metallurgist; the central figure."

timeline:
  - id: "e1"
    date: "1972-05"
    dateLabel: "May 1972"
    headline: "Khan joins FDO in Amsterdam"
    body: |
      Fresh from a PhD at Leuven, Khan begins work at FDO.
    confidence: fact
    sources: ["s1"]

  - id: "e6"
    date: "1975"
    dateLabel: "1975 (timing disputed)"
    headline: "The CIA allegedly asks the Netherlands not to arrest Khan"
    body: |
      Ruud Lubbers, in a 2005 radio interview, states that U.S. intelligence
      asked the Dutch to let Khan go. The CIA has never confirmed.
    confidence: conjecture
    sources: ["s7", "s8"]

interpretation:
  - id: "i1"
    label: "The meta-pattern"
    body: |
      The Khan affair was not cunning espionage. It was a system in which
      every incentive pointed toward "do not make trouble."

recommendations:
  - id: "r1"
    title: "Pass the Knowledge Security Screening Act now."
    body: |
      The two-year lag is exactly the institutional reflex that produced Khan.

sources:
  - id: "s1"
    title: "A. Q. Khan Nuclear Chronology"
    publisher: "Carnegie Endowment"
    url: "https://carnegieendowment.org/research/2005/09/a-q-khan-nuclear-chronology"
  - id: "s7"
    title: "CIA asked us to let nuclear spy go, Ruud Lubbers claims"
    publisher: "GlobalSecurity.org"
    url: "https://www.globalsecurity.org/org/news/2005/050809-khan-cia.htm"
  - id: "s8"
    title: "Dutch let Khan go at CIA's request"
    publisher: "Dawn"
    url: "https://www.dawn.com/news/151703/dutch-let-khan-go-at-cia-s-request"

methodology: |
  EGT v1.0. Fact requires two independent sources. Conjecture covers
  plausible but contested claims. Opinion is the author's interpretation,
  quarantined into labeled blocks.

12. Out of scope for v1.0

The following are explicitly deferred to future versions:

Custom confidence levels (e.g., rumor, speculation, well-established).
Embedded media (images, video).
Translations / multi-language documents beyond a single language field.
Editorial workflow metadata (review state, reviewer comments, change history beyond updated).
Rendering hints (renderer-specific layout instructions).
Cross-document linking between EGT papers.

These are valid extensions and may be standardized in EGT 1.1 or 2.0.

13. Reference implementations

To be developed alongside the spec:

egt-validate — CLI validator (reference implementation).
egt-render-html — reference HTML renderer matching the published EGT visual conventions.
JSON Schema (egt-1.0.schema.json) — formal validation.

14. License

The EGT specification is published under CC-BY 4.0. Implementations may be licensed independently.

End of EGT v1.0 specification.