文法

Playgroundリンク付きの例は、短い完全な .tdsl ファイルとして読める形にしています。各リンクは、同じ本文を source クエリとして Playground に渡します。

最小の年表

timeline "読書メモ" {
    title "読書メモ";
    unit year;
    range 2024..2026;
    calendar proleptic_gregorian;
}

lane "本" as books { kind custom; order 10; }

event books 2025 "Timeline DSLを試す" { id "event:first"; };

Playgroundで開く

.tdsl は、年表全体の timeline、縦軸の lane、時間要素の event / span / event_range を組み合わせます。

timeline と range

timeline "製品ロードマップ" {
    title "製品ロードマップ";
    unit year;
    range 2025..2027;
    calendar proleptic_gregorian;
}

lane "マイルストーン" as milestones { kind custom; order 10; }
event milestones 2026 "公開ベータ" {};

Playgroundで開く

range 2025..2027; は表示・検証の対象範囲です。まずは unit year; と calendar proleptic_gregorian; を固定して、年単位の年表として作るのが分かりやすいです。

lane

lane は年表の縦軸です。as milestones のように短いIDを付け、後続の event、span、event_range から参照します。

lane "マイルストーン" as milestones { kind custom; order 10; }
event milestones 2026 "公開ベータ" {};

order は表示順です。小さい値ほど上に並びます。kind は分類用のメタデータとして扱います。

group

group は複数の lane をまとめ、グループラベルと境界線で視覚的に階層化します（v1.13.0〜）。group "<名前>" { ... } の中に lane を並べます。

timeline "組織の年表" {
    title "組織の年表";
    unit year;
    range 2025..2027;
    calendar proleptic_gregorian;
}

group "開発チーム" {
    lane "フロントエンド" as frontend { kind custom; order 10; }
    lane "バックエンド" as backend { kind custom; order 20; }
}

event frontend 2026 "UI 刷新" { id "event:ui"; };
event backend 2026 "API v2" { id "event:api"; };

Playgroundで開く

グループ名は lane 群の上にラベルとして表示され、境界線で区切られます。group に属さない lane はそのまま独立して描画されるため、既存の年表に後から導入できます（後方互換）。

event

event は1年に置く点イベントです。

timeline "製品ロードマップ" {
    title "製品ロードマップ";
    unit year;
    range 2025..2027;
    calendar proleptic_gregorian;
}

lane "マイルストーン" as milestones { kind custom; order 10; }
event milestones 2026 "公開ベータ" { tags ["release"]; id "event:beta"; };

Playgroundで開く

event <lane-id> <year> "<label>" { ... }; の順で書きます。ラベルは年表上に表示されます。

span

span は存続期間や工程のように、開始年と終了年を持つ項目です。

timeline "小さなプロジェクト" {
    title "小さなプロジェクト";
    unit year;
    range 2025..2028;
    calendar proleptic_gregorian;
}

lane "工程" as phases { kind custom; order 10; }
span phases 2025..2026 "設計" { tags ["phase"]; id "span:design"; };
span phases 2026..2028 "実装" { tags ["phase"]; id "span:build"; };

Playgroundで開く

span <lane-id> <start>..<end> "<label>" { ... }; の順で書きます。

event_range

event_range は戦争、移行期間、障害対応など、出来事として扱いたい期間に使います。

timeline "リリース計画" {
    title "リリース計画";
    unit year;
    range 2025..2027;
    calendar proleptic_gregorian;
}

lane "作業" as work { kind custom; order 10; }
event_range work 2025..2026 "移行期間" { tags ["migration"]; };
event work 2027 "新体制で運用開始" {};

Playgroundで開く

見た目は期間を持つ点で span に近いですが、意味は「期間を持つ出来事」です。時代区分や所属期間は span、作業・事件・戦争は event_range に寄せると読み分けやすくなります。

tags、id、metadata

event、span、event_range の { ... } には共通のメタデータを書けます。

timeline "公開履歴" {
    title "公開履歴";
    unit year;
    range 2024..2026;
    calendar proleptic_gregorian;
}

lane "リリース" as releases { kind custom; order 10; }
event releases 2026 "v1.0公開" {
    tags ["release", "stable"];
    source wd:Q95;
    origin manual;
    id "event:v1";
};

Playgroundで開く

tags は分類、id はレビューや差分追跡で使う安定識別子です。source wd:Q95; はWikidata QIDを出典メタデータとして記録します。origin manual; は手書きデータであることを示します。

import と Wikidata の Web 制約

Wikidataを使う場合は、import wikidata でQIDを取り込み、map で年表要素へ変換します。

timeline "中国王朝" {
    title "中国王朝";
    unit year;
    range -300..300;
    calendar proleptic_gregorian;
}

lane "王朝" as dynasties { kind dynasty; order 10; }

event dynasties -221 "秦の天下統一" { tags ["manual"]; };

import wikidata as wd {
    entity Q7209 as han_dynasty;
    policy merge_by_source;
}

map wd.han_dynasty to span {
    lane dynasties;
    start claim(P571).year;
    end claim(P576).year;
    label label@ja ?? label@en;
    tags ["dynasty", "imported"];
}

Playgroundで開く

ブラウザ版の Playground では、Wikidataのネットワーク取得は行いません。構文確認用として開けますが、import 由来の項目は描画結果から省かれることがあります。Webで確実に表示したい内容は、上の例の event dynasties -221 ... のように静的な event、span、event_range として書いてください。

Wikidataを解決してJSONやHTMLへ出力する場合はCLIを使います。

tdsl build china.tdsl --pretty --output china.json
tdsl render china.tdsl --output china.html

CIでネットワーク取得を避けたい場合は、--offline を付けます。

tdsl build china.tdsl --offline --pretty

map の filter 句

map ブロックには filter 句を書けます。条件に合うエンティティだけをアイテム化し、不要なデータを絞り込みます。

map wd.items to span {
    lane dynasties;
    start claim(P571).year;
    end   claim(P576).year;
    label label@ja ?? label@en;
    filter claim(P31) == "Q7209";
}

filter に使える演算子は ==、!=、<、<=、>、>=、&&、||、!、null、claim() です。複数の filter を並べると AND 条件として扱われます。

文字列マッチング（contains / startswith）

v1.16.0 以降、ラベルに対する文字列マッチング演算子 contains / startswith を使えます。label@<lang> contains "..." でラベルに部分文字列を含むエンティティを、label@<lang> startswith "..." でラベルが指定文字列で始まるエンティティを絞り込めます。

map wd.items to span {
    lane dynasties;
    start claim(P571).year;
    end   claim(P576).year;
    label label@ja ?? label@en;
    filter label@ja contains "王朝";        // ラベルに「王朝」を含む
    filter label@en startswith "Han";       // ラベルが "Han" で始まる
}

! や && / || と組み合わせられます（例: filter !(label@ja contains "候補");）。指定した言語のラベルが存在しないエンティティは false（除外）として扱われ、別言語へ silent fallback はしません。

月・日精度のタイムライン軸表示

v1.7.0 以降、タイムライン軸は月・日単位の精度に対応しています。v1.9.0 では静的な event / span の time / start / end に 日付リテラル YYYY-MM-DD / YYYY-MM を直接書けるようになりました。

timeline "近現代史" {
    title "近現代史";
    unit year;
    range 1900..2000;
    calendar proleptic_gregorian;
}

lane "出来事" as events { kind custom; order 10; }
event events 1945-08-15 "第二次世界大戦終結" {};
event events 1914-07 "第一次世界大戦勃発" {};

日付リテラルを使うとタイムライン軸上で正確な位置に配置されます。月単位（YYYY-MM）を指定した場合は月の先頭日として扱われます。Wikidata クレーム由来の値が月・日精度を持つ場合も同様に正確な位置に配置されます。

map の ??（フォールバック）演算子

label だけでなく start、end、time にも ?? 演算子を使えます。左辺が null のとき右辺を試します。

map wd.items to span {
    lane dynasties;
    start claim(P580).year ?? claim(P571).year;
    end   claim(P582).year ?? claim(P576).year;
    label label@ja ?? label@en;
}

既存の単項式（start claim(P571).year）と完全互換です。複数のプロパティから最初の有効値を取り出したいときに使います。

map の expand ディレクティブ

v1.16.0 以降、map ブロック内に expand claim(P) を書くと、そのエンティティのプロパティ P の non-deprecated な Statement を全件展開し、Statement ごとに 1 アイテムを生成します。expand がない場合は従来どおり最初の Statement だけを参照します。

map wd.elizabeth_ii to span {
    lane offices;
    expand claim(P39);                          // 在任した役職（P39）をすべて展開
    start claim(P39).qualifier(P580).year;       // 各 Statement の開始 qualifier
    end   claim(P39).qualifier(P582).year ?? 9999;
    label label@ja;
}

P39 の Statement が複数あれば複数のスパンが生成されます。qualifier（P580 / P582）を持たない Statement は、start / end が解決できないためそのアイテムをスキップします。

map の整数オフセット演算（+ / -）

map ブロックの時間値式（start / end / time）では、claim 由来の年に整数を加算・減算できます（v1.11.0〜）。アクセサ（.year など）の直後に +N / -N を書きます。

map wd.people to span {
    lane people;
    start claim(P569).year +1;   // 誕生年 + 1
    end   claim(P570).year -5;   // 没年 − 5
    label label@ja ?? label@en;
}

• オフセットは claim 解決後の年に対して適用されます。負数は -N、+0 も有効です。
• ??（フォールバック）と組み合わせられます。オフセットは各 claim 項ごとに付きます: start claim(P580).year ?? claim(P571).year +1;。
• decompile / inspect の出力や Playground の Format でも + N / - N 形式で再現されます。

次に進む

• Quick Start で保存、検証、描画の流れを確認する
• Commands でCLIコマンドを確認する
• CIで検証する でGitHub Actionsに組み込む