rokka チュートリアル——自分でデータを作って、地図で見る

テキストエディタと python3 だけで、文書を一つ作る

テキストエディタと python3 だけで、rokka の文書を一つ作ります。京都を一日 歩いた記録を題材に、一番小さい形から少しずつ足していきます。各段で検証器に 通し、地図で見ます。

できあがりは公開しているビューアで開けます。先に見たい人はこれを押して ください——https://codh.rois.ac.jp/rokka/viewer/?data=examples/tutorial.json

仕様そのものは spec/ROKKA-1.0.md（土台）と spec/DOCHU-1.0.md（dochu 拡張）に あります。ここは手を動かす順だけを書きます。

1. 一番小さい文書

要るのは三つだけです——何の形式か、表題、事象の列。

kyoto.json という名前で作ります。

{
 "format": "rokka/1.0",
 "meta": { "title": "はじめての rokka" },
 "events": [
  { "id": 1,
    "when":  { "text": "9月13日" },
    "where": { "name": "京都駅", "lat": 34.9858, "lng": 135.7588 } },
  { "id": 2,
    "when":  { "text": "9月13日" },
    "where": { "name": "清水寺", "lat": 34.9948, "lng": 135.7850 } }
 ]
}

検証器に通します。

$ python3 -m rokka.validate kyoto.json
WARN  events[0]: what.text がありません
WARN  events[1]: what.text がありません
OK    2 stays / 0 moves / 1 days / located 100% / 主体 0（無し）

OK が出れば適合しています。 WARN は「適合してはいるが、痩せている」と いう助言です——いまの文書は「そこに居た」としか言っておらず、何が起きたかを 言っていません。次でそれに答えます。

2. 地図で見る

置き場を用意しなくても見られます。ファイルを放り込む道があります。

ブラウザで https://codh.rois.ac.jp/rokka/viewer/ を開きます（?data= は付けない）。 取り込みの画面が出るので、kyoto.json を放り込むか、ファイル選択で選びます。 ファイルはブラウザの中で読むだけで、どこへも送られません——公開できない資料 でも、手元から出さずに見られます。何も用意しなくてよいのはこのためで、 サーバを立てる必要はありません。

置き場がある資料なら、URL で渡す道もあります。

https://codh.rois.ac.jp/rokka/viewer/?data=examples/tutorial.json

ビューアはデータの在り処を知りません。?data= に渡された URL を読むだけ なので、自分のサーバに置いたものでも構いません（別のホストなら、そちら側で Access-Control-Allow-Origin を許す必要があります）。

開く画も指せます——&lat=35.0&lng=135.77&zoom=13。緯度経度と縮尺は一部だけ 渡してもよく、読めない値は無視されます。

3. 資料の言葉と、機械の値

rokka は同じことを三つの層で書きます。混ぜないのが肝心です。

層鍵例
資料の言葉text「京都の停車場」「朝、駅に着く」
正規化した名name / cat「京都駅」「参詣」
機械の値start / lat / lng / refs2026-09-13、座標、識別子

what.text を足して、警告に答えます。ついでに why（なぜ）と cite （どこに書いてあるか）も。

  { "id": 1,
    "what":  { "text": "朝、駅に着く" },
    "when":  { "text": "9月13日", "start": "2026-09-13" },
    "where": { "text": "京都の停車場", "name": "京都駅",
               "lat": 34.9858, "lng": 135.7588 },
    "cite":  [{ "source": "自分の手帳", "page": "1" }] }

4. 分類と、その意味の表

同じ種類の事象をまとめたいときは what.cat に代表の言葉を書きます。 既定の語彙はありません——「参詣」でも「visit」でも、あなたが決めた言葉が そのまま分類です。

意味は meta.what の表に書きます。読み手（ビューア）はここを見て記号や色を 決めます。

 "meta": {
  "title": "はじめての rokka",
  "subtitle": "京都を一日歩く",
  "what": {
   "参詣": { "label": "参詣・見物", "icon": "詣", "weight": 2.0, "color": "#d55e00" },
   "移動": { "icon": "→", "weight": 0.6 }
  }
 }

icon は地図の印、weight は印の大きさ、color は色。表に無い分類も 書けます——読み手は言葉そのものを出します。

5. 誰の記録か

who は主体の配列です。名で分けます。

  "who": [{ "name": "私" }]

複数なら [{"name":"私"},{"name":"友人"}]。同じ人は同じ綴りで書きます （名が鍵の代わりになります）。資料の書き方が揺れるなら who[].text に。

6. 旅にする——dochu 拡張

ここまでは土台（rokka/1.0）でした。地点のあいだの移動を書きたいなら、 拡張に切り替えます。

  1. format を dochu/1.0 にする
  2. すべての事象に type（"stay" か "move"）を足す
  3. 移動を両端の地点のあいだに置く
  { "id": 101, "type": "move",
    "who":  [{ "name": "私" }],
    "how":  { "text": "市バスで東山へ", "cat": "市電" },
    "when": { "text": "9月13日" },
    "where": { "from": 1, "to": 2 } }
 "how": {
  "徒歩": { "icon": "歩" },
  "市電": { "label": "市バス", "color": "#0072b2", "dash": "dashed" }
 }

検証器に通すと、移動が数えられます。

OK    3 stays / 2 moves / 1 days / located 100% / 主体 1（私）

7. 地図の下地を選ぶ

既定の下地はれきちず（歴史地図）です。江戸の資料ならそのままでよいのですが、 いまの京都を歩いた記録なら現代の地図が合います。表示の指定は形式の項目では ないので、meta.ext に置きます。

 "meta": { "ext": { "basemap": "osm" } }

画面の設定からも切り替えられます。データに書いておくと、開いた人に最初から その下地で見せられます。

8. 間違えたとき、検証器は何と言うか

実際に出るものを並べます。メッセージは「どう直すか」まで言います。

やりがちな間違い検証器
format を書き忘れるformat が "dochu/1.0" でも "rokka/1.0" でもありません（None）
cite を配列にしない配列ではありません（…）。出どころは一つでも [{"source": …}] と書きます
座標が片方だけlat と lng は両方揃っていなければなりません
type を書き忘れるtype がありません。"stay" か "move" が要ります（土台だけで書くなら format は "rokka/1.0"）
無い地点を指す移動to=99 が type:"stay" の id を指していません
緯度と経度を取り違える緯度が範囲外です（135.7588）。緯度と経度が入れ替わっていませんか
id が重なるid=1 が events[0] と重複しています

WARN と INFO は適合条件ではありません。満たさなくても rokka の文書です ——「痩せている」「見落としかもしれない」という助言です。

9. JSON を書かずに始める——表から

ここまでは JSON を写して直しました。一から起こすなら、表計算の方が早いです。 行が事象、列が要素です。

kyoto-stays.csv（地点）

日付,時刻,場所,緯度,経度,内容,分類,なぜ,誰,典拠,天気
9月13日,,京都駅,34.9858,135.7588,朝、駅に着く,移動,,私,自分の手帳 | 1,曇
9月13日,昼,清水寺,34.9948,135.7850,清水の舞台に上る,参詣,紅葉には早いが人が少ないと聞いて,私,自分の手帳 | 1,晴
9月13日,夕,法観寺（八坂の塔）,34.9977,135.7788,八坂の塔を見る,参詣,,私,自分の手帳 | 2,晴

移動は別の表に書きます（エクセルなら別のタブ）。起点・終点は地点の id ——id の列が無ければ、上から 1, 2, 3… です。

kyoto-moves.csv（移動）

起点,終点,手段,手段の分類,内容,日付
1,2,市バスで東山へ,市電,,9月13日
2,3,産寧坂を下る,徒歩,三年坂から二年坂へ,9月13日
$ python3 -m rokka.table kyoto-stays.csv --moves kyoto-moves.csv \
      --title "はじめての rokka" --subtitle "京都を一日歩く" -o kyoto.json
   日付    → when.text
   時刻    → when.time_text
   場所    → where.name
   緯度    → where.lat
   経度    → where.lng
   内容    → what.text
   分類    → what.cat
   なぜ    → why.text
   誰     → who
   典拠    → cite
  ※天気    → ext.天気
   起点    → from
   終点    → to
   手段    → how.text
   手段の分類 → how.cat
  ※ の列は形式に場所が無いので、その資料の項目（ext）に入れました。行き先を変えるなら --map 列名=行き先
   移動 2 件は、両端の地点から主体を補いました
OK    3 stays / 2 moves / 1 days / located 100% / 主体 1（私）

エクセルなら、分けずにそのまま渡せます。

$ python3 -m rokka.table kyoto.xlsx -o kyoto.json
   地点の表: 地点
   移動の表: 移動
   メモ は地点の表にも移動の表にも見えません（見出しに場所も起点もありません）
   …

一つの帳簿に「地点」「移動」の二枚（＋関係ないシート）が入っていても、 見出しから役を見分けます——起点と終点があれば移動の表、場所や緯度があれば 地点の表。決められないときは黙って選ばず、候補を並べて名指しを求めます （参勤の帳簿は往路と復路で地点の表が二枚あるので、実際にそうなります）。 名指しするなら --sheet 地点 --moves-sheet 移動。

何も入れなくても読めます。 xlsx は zip に入った XML なので、rokka は 標準ライブラリだけで読みます（rokka/xlsxlite.py）——pip install は要りません。openpyxl が要ります

できた JSON は §2 と同じように地図で見られます。座標の無い表でも通ります ——located 0% と出るだけで、同定はあとからエディタで足せます。

この章の表はここにあります——https://codh.rois.ac.jp/rokka/docs/tutorial/kyoto-stays.csv と https://codh.rois.ac.jp/rokka/docs/tutorial/kyoto-moves.csv 。

10. 次に進む

このチュートリアルで作ったもの：https://codh.rois.ac.jp/rokka/viewer/?data=examples/tutorial.json （3 地点 2 移動）。実在の記録ではありません。