Event Page Schema — AI Chronicles

Purpose: This document is the authoritative reference for authoring event pages on ciyuan.website. It defines every frontmatter field, explains what each means, and provides examples. When in doubt, consult this document first.

Quick Reference: Required Fields

Every event page must have these four fields:

+++
tier = "BENJI"           # BENJI | SHIJIA | LIEZHUAN
title = "Event Title"    # Full name of the event
date = "YYYY-MM-DD"       # ISO 8601 date
category = "..."          # See Category Reference below
+++

Everything else is recommended or optional. If a field is missing and you don’t know what to put, leave it out rather than filling it with guesswork.

Frontmatter Fields

Required Fields

tier

Type: String (enum)
Values: BENJI | SHIJIA | LIEZHUAN

The tier mirrors Sima Qian’s Records of the Grand Historian (史记) structure:

Selection test:

• Would AI development have taken a fundamentally different path without this event? → BENJI
• Did this significantly advance the state of the art or shift expert consensus? → SHIJIA
• Does this provide important context, but would not appear in a brief summary? → LIEZHUAN

Examples:

• BENJI: ChatGPT launch (transformed public awareness), Transformer (replaced RNN paradigm)
• SHIJIA: DeepSeek R1 (open-source reasoning breakthrough), AlphaFold 2 (protein structure prediction)
• LIEZHUAN: EU AI Act (important policy but not a technical inflection), individual model releases with incremental improvements

title

Type: String
Format: Full English name, title-case capitalization

Use the most widely recognized name. If the event is a paper, use the official paper title. If it’s a product, use the product name.

Examples:

• "Attention Is All You Need: The Transformer Architecture" (paper title)
• "ChatGPT: The Moment AI Entered Everyday Life" (event page title, more descriptive than just “ChatGPT Launch”)
• "OpenAI o1 Released" (product + release naming)

Anti-patterns:

• ❌ "GPT-4" → ✅ "GPT-4 Released" (distinguish model from capability)
• ❌ "transformer" → ✅ "Transformer Architecture Published" (full event name)

date

Type: String (ISO 8601)
Format: YYYY-MM-DD

Use the date the event was first made public (publication date, release date, announcement date), not the date of the underlying research or internal development.

Examples:

• Paper published on June 12, 2017 → "2017-06-12"
• Product announced on November 30, 2022 → "2022-11-30"
• Policy adopted on March 13, 2024 → "2024-03-13"

category

Type: String (enum)
Values: historical-milestone | model-release | research-breakthrough | governance | capability-unlock | concept

See the Category Reference section below for full definitions and selection criteria.

Recommended Fields

tags

Type: Array of strings
Format: Capitalized names, kebab-case for multi-word terms

Examples:

tags = ['Transformer', 'Attention Mechanism', 'Google Brain', 'NLP']
tags = ['OpenAI', 'Reasoning', 'Chain-of-thought', 'o1']

Limit to 5-8 of the most relevant tags. Tags are used for filtering and search.

translationKey

Type: String
Format: "events/{slug}" (must match the filename without .md)

Used by Hugo’s i18n system to look up translated content. Set this to the event’s filename slug. If you are not using multilingual content, this field is optional.

tianashi_en

Type: String (plain text, no Markdown)
Purpose: Historical context — the conditions that made this event possible or necessary.

Content: What was the state of the field, hardware, funding, and intellectual climate at the time? What prior work does this build on? Who were the key players?

Length: 1-3 sentences.

Examples:

"By June 2017, GPU parallel computing was reshaping the hardware foundations of 
AI research; Google's TPUs were already in internal deployment, Nvidia's 
Pascal P100 had become the new standard for training compute; LSTM/RNN had 
dominated NLP for nearly a decade — the Transformer stood at the intersection 
of all these conditions."

(Note: tianashi is the Chinese-language version of the same field.)

commentary_en

Type: String (plain text, no Markdown)
Purpose: Editorial interpretation — the historical significance and why it matters.

Content: What was the key intellectual insight? How does this event fit into the larger narrative? What did the field learn? What does this reveal about AI’s trajectory?

Length: 1-3 sentences.

Voice: Write as if a knowledgeable historian is giving a brief verdict. Direct, analytical, slightly detached. Avoid promotional tone.

Anti-patterns:

• ❌ "This was an amazing breakthrough that changed everything!" → ✅ "The key insight was that parallelism was sufficient — recurrence was not necessary."
• ❌ "Many experts believe this is the most important model ever created" → ✅ "o1 was the first model to treat the reasoning process itself as a first-class object for optimization."

(Note: commentary is the Chinese-language version, written in 葛洪曰 style.)

[entities]

Type: Section with sub-arrays
Sub-fields: organizations, people, models, concepts, benchmarks

Each sub-array lists the named entities involved in this event.

Format: Use the most widely recognized canonical name. Capitalize properly.

[entities]
organizations = ["OpenAI", "Google DeepMind"]
people = ["Sam Altman", "Ilya Sutskever"]
models = ["ChatGPT", "GPT-3.5"]
concepts = ["RLHF", "Instruction-following"]
benchmarks = ["AIME", "GPQA Diamond"]

• Empty arrays are fine: benchmarks = [] if no benchmarks are relevant.
• Name consistency: Use the same name across all events. Check data/ontology.yaml for the canonical list of entity names.
• Optional sub-fields: If a category has no entities, you may omit the sub-field entirely (e.g., no benchmarks section if benchmarks is empty).

[relations]

Type: Section with sub-arrays
Sub-fields: builds_on, introduces, enables, responds_to, challenges, part_of

Each entry is a path reference to another event file (without the .md extension) or to a concept/model/benchmark in data/ontology.yaml.

[relations]
builds_on = ["events/transformer-architecture-2017", "events/scaling-laws-2020"]
introduces = ["concepts/rlhf"]
enables = ["events/openai-o1-released", "events/gpt-5-2025"]

Relation types (see data/ontology.yaml for full definitions):

Rules:

• builds_on targets must exist as event files before you reference them.
• enables is for cross-domain foundational relationships (a model enabling a capability unlock, etc.).
• Avoid circular references (A builds_on B and B builds_on A).
• Do not add part_of unless the event genuinely cannot stand alone.

Optional Fields

commentary / commentary_en

Already described above under Recommended Fields. Include both the Chinese (commentary) and English (commentary_en) versions when possible.

tianashi / tianashi_en

Already described above. Include both languages when possible.

Category Reference

historical-milestone

Label: Historical Milestone
Color (UI): #ffb347

Events that permanently changed AI’s trajectory and are visible to the general public. If removed from history, the timeline would look fundamentally different.

Selection: Would the public perception of AI be different without this event?

Examples: ChatGPT launch, AlphaGo victory, EU AI Act adoption.

model-release

Label: Model Release
Color (UI): #00f0ff

Public releases of AI models that set a new state of the art, introduced new architectures, or redefined what was possible.

Selection: Did this model set a new frontier or open a new category?

Examples: GPT-4, Claude 4, Gemini 2.5 Pro, DeepSeek R1.

research-breakthrough

Label: Research Breakthrough
Color (UI): #fcd34d

Papers, findings, or demonstrations that introduced new paradigms, training methods, or architectural approaches.

Selection: Did this change how researchers think about the problem?

Examples: Transformer architecture, Scaling Laws 2020, AlphaFold 2.

governance

Label: Governance
Color (UI): #c084fc

Laws, regulations, international agreements, or institutional responses that changed the legal or normative constraints on AI.

Selection: Did this change the legal or normative constraints on AI?

Examples: EU AI Act, Asilomar AI Principles, US Executive Order on AI.

capability-unlock

Label: Capability Unlock
Color (UI): #6ee7b7

First demonstrations of practical abilities previously beyond AI’s reach — qualitatively new categories of task.

Selection: Could humans now delegate a new class of task to AI after this?

Examples: AlphaFold 2 (protein structure), DALL-E (image generation), GitHub Copilot (code generation).

concept

Label: Concept
Color (UI): #f9a8d4

Abstract ideas, theoretical frameworks, or mental models that shaped how AI is understood, discussed, or built.

Selection: Would AI discourse be impoverished without this concept?

Examples: Scaling Laws, Inference-time Scaling, MoE architecture.

The Overview Section

The ## Overview section (H2 heading) is the human-readable body of the event page. It follows the frontmatter block (+++).

Content guidelines:

• First paragraph: What happened, when, who was involved, and why it was significant at a glance.
• Subsequent paragraphs: Context, mechanics, impact, and significance.
• Closing paragraph: How this event connects to the larger narrative — what it enabled, what it revealed about the field.

Style: Analytical, not promotional. Cite specific data points (dates, numbers, benchmark scores) wherever available. Link to primary sources.

Length: 300-1500 words. BENJI events typically warrant 800+ words; LIEZHUAN events may be shorter.

File Naming Convention

content/events/{slug}.md

• slug = kebab-case, matches the translationKey value
• Must be unique across all events
• Examples: chatgpt-launch-2022.md, transformer-architecture-2017.md, eu-ai-act-2024.md

Writing Process

When adding a new event:

1. Verify it belongs — Check the category and tier criteria above. If unsure, start with SHIJIA/LIEZHUAN; it’s easier to promote an event to BENJI later than to demote it.
2. Check for duplicates — Search the existing 52 events to see if this topic is already covered.
3. Fill required fields first — tier, title, date, category.
4. Add recommended fields — tags, tianashi_en, commentary_en, entities, relations.
5. Write the Overview — Start with a clear first sentence defining what happened.
6. Set relations — Identify builds_on / enables / introduces targets. Verify those files exist.
7. Run lint — Execute scripts/lint_events.py to check for broken links and missing fields.

Common Mistakes to Avoid

1. Missing builds_on targets — Every builds_on reference must point to an existing event file. Run scripts/lint_events.py before submitting.
2. Inconsistent entity names — "openai" and "OpenAI" are different names to the system. Use canonical capitalization from data/ontology.yaml.
3. Circular builds_on chains — A should not build_on B if B also builds_on A.
4. Tier inflation — Not every model release is a BENJI. Reserve BENJI for genuinely civilization-scale inflection points.
5. Commentary without analysis — 葛洪曰 commentary should offer a historical judgment, not just a summary. What does this event reveal? What does it foreshadow?
6. Events without tianashi — The “天时” (historical conditions) is what makes an event intelligible. Without it, the reader doesn’t know why this happened now.

Validation

Run the lint script to validate any new or modified event page:

python scripts/lint_events.py

Expected output: {"broken_links": [], "missing_required": [], ...} with exit code 0.

This schema is maintained at content/events/SCHEMA.md. For the website’s purpose and design philosophy, see content/about/PURPOSE.md.