GEUL データの単位はドキュメント(DOC)1 つである。ファイル 1 つ(.geul、メディアタイプ application/vnd.geul)がドキュメント 1 つである。

構造

DOC-*            ← ドキュメントを開く (全体の長さ)
  Meta …         ← HEAD: ドキュメントに関するレコード
  SOURCE …       ←   (ドキュメント全体の出典とその QUALIFIER)
BODY             ← HEAD を終え、BODY を開く
  Reference, Value, Edge …
END              ← ドキュメントを閉じる
レコードTAG意味
DOC-1WORD1C01 + 1 WORD全体の長さを 1 WORD で指定してドキュメントを開く
DOC-2WORD1C12 + 2 WORD全体の長さを 2 WORD で
DOC-4WORD1C24 + 4 WORD全体の長さを 4 WORD で
BODY1C301 WORD。HEAD を終えて BODY を始める
END1C401 WORD。ドキュメントを閉じる
  • DOC-* の値は、開くレコードの先頭から END の末尾までの全 WORD 数である。値が収まる最も狭い幅を使う。
  • END は必須である。END の位置が DOC-* の長さと合わなければ拒否する。END なしで入力が終わったら、途中で切れたドキュメントである。
  • デコーダは DOC-* の長さで、ドキュメント全体を一度に読み飛ばせる。
  • 長さを知らないまま開く方法はない。終わりを事前に知れないリアルタイムデータは、長さの分かる単位で区切り、複数のドキュメントで送る。
  • HEAD が空なら BODY を省略する。BODY レコードのないドキュメントは全体が BODY である。BODY は 1 度だけ置く。HEAD にレコード(Meta または HEAD Edge)が 1 つでもあれば BODY を置く。
  • ドキュメントは入れ子にしない。他のドキュメントは IMPORT や指示 Reference で指す。

HEAD と BODY

  • HEAD には Meta と HEAD Edge の 2 つだけを置く。いずれも、それを収めるドキュメントについての叙述である。
    • Meta: ドキュメントの構造・定義・出典・系譜・検証・ポリシー・IMPORT。
    • HEAD Edge: ドキュメント全体の原典を記す根拠 Edge SOURCE(Target 0)、およびその SOURCE を Target とする QUALIFIER(原文ハッシュ、受領時刻、原文範囲など)。QUALIFIER はその SOURCE の後ろに置く。
  • BODY には Reference、Value、Edge だけを置く。個別のレコードの出典は BODY 内の根拠 Edge SOURCE で、信頼度のような他の根拠はそのレコードに付く QUALIFIER で書く。Target が 0 の SOURCE と、HEAD の SOURCE を Target とする QUALIFIER は BODY に置けない。
  • デコーダは HEAD を先頭から読みながら振り分ける。Meta は HEAD である。Target が 0 の SOURCE は HEAD であり、その Edge Id を記憶する。記憶した SOURCE を Target とする QUALIFIER は HEAD である。それ以外のレコードが来たとき、HEAD が空なら BODY が省略されたもの(そのレコードから BODY)、そうでなければ BODY 欠落で invalid である。
  • Edge Id は HEAD と BODY が 1 つの番号空間を使う。 ドキュメント内で一意であり、BODY の Edge と同様に NEXT-LOCAL-ID から受け取る。HEAD Edge の Origin が LOCAL なら、その定義は BODY に置く(LOCAL はドキュメント全体が範囲)。
  • Meta は Payload の中に Value レコードを含められる。含まれた Value は独立したレコードではなく、その Meta の一部である。
  • 宣言(Meta 定義クラス)の範囲はそのドキュメントである。

基本宣言

2 つの宣言はどちらも多くて 1 つである。どのドキュメントに必ず置くべきかは、下の条件が定める。

Meta意味置くべきドキュメント
SPEC-VERSION従う仕様版。残りのレコードをどう読むかを定める。未知の版なら拒否または警告する。v1 ドキュメントの値は 0x0001 である公表ドキュメント。なければデコーダが知っている版で読む
DOC-IDドキュメント自身の識別子。ドキュメントの外からこのドキュメントとその中の対象を指すには必要である.well-known/geul/ 配下の docs/<ドキュメント ID>/・codecs/<Codec ID>/ のバージョンドキュメント(規格ドキュメントを含む)。バージョン一覧 versions.geul と一覧ドキュメント(issuers/)には置かない
  • SPEC-VERSION は、どの版のデコーダでも読めるよう整数 1 つだけを収める(v1 は 1C51 0001)。Value コードに依存しない。
  • DOC-ID は自分自身を指す DOC-POINTER(Issuer、ドキュメント ID、バージョン 0)である。ドキュメント ID は 4 WORD である。コーデックのドキュメントはドキュメント ID を持たないため CODEC-POINTER(Issuer、Codec ID、バージョン 0)を使う。すべての Issuer はドキュメント ID 0x0000000000000000 と 0xFFFFFFFFFFFFFFFF を予約する(Issuer と公表)。
  • DOC-ID のないドキュメントは名前のないドキュメントである。コンテンツハッシュでのみ指せる。

コンテンツハッシュ

ドキュメント 1 揃いはコンテンツハッシュで指す(git のコミット ID と同じ役割)。

  • 開くレコード(DOC-*)から END の直前までの SHA-256 である。16 WORD。
  • 検証クラスの Meta(署名など。セクション 15 で C >= 5、つまり w >= 0x1E50 のレコード)は計算から除く。そのため署名をドキュメント内に置いても循環が生じない。
  • 計算の際、DOC-* の長さは検証レコードを除いた長さに置き換え、幅もその長さに合う最も狭い幅に置き換える。そのため署名を付ける前と後でコンテンツハッシュが同じになる。
  • コンテンツハッシュはドキュメントに記録せず、計算する。他のバージョンを指すときにだけ値として書く(PARENT など)。
  • ドキュメント内の PARENT も計算に入るため、コンテンツハッシュは履歴全体をつなぐハッシュチェーンになる。
  • ドキュメントの外で後から付けた Meta(別のストアの注釈など)は、コンテンツハッシュを変えない(git notes と同じ)。
  • ドキュメントはバイナリが正本である。コンテンツハッシュと署名はバイナリでのみ計算する。

バージョン

名前のあるドキュメント(DOC-ID のあるドキュメント)はバージョンを持つ。

  • バージョン ID は、ドキュメント 1 つの中で公表順に 1 から振る 2 WORD の整数である。0 は「バージョンを記載しない」であり、最新バージョンとして扱う。
  • バージョン ID は公表元が公表するときに割り当てる。バージョン ID とコンテンツハッシュの対応は、公表元が署名したバージョン一覧に置く(公表アドレスとバージョン一覧)。
  • 同じ内容を再び公表しない。既にあるコンテンツハッシュなら、そのバージョン ID を返す。
  • 2 WORD を使い切ったら、新しいドキュメント ID で出す。
  • v2 以降のバージョンは HEAD に PARENT(直前バージョンのコンテンツハッシュ)を書く。コンテンツハッシュに入るため、バージョン同士がハッシュチェーンでつながる。最初のバージョンには置かない。

改訂

GEUL ドキュメントは法令のように改訂される。

  • バージョンは不変である。 公表したバージョンは変更も削除もしない。例外は法的削除と職権削除のみである(TOMBSTONE)。
  • 履歴は消さない。直した内容は新しいバージョンとして出し、元のバージョンを上書きしない(旧法の保存)。書き直したバージョンは REPLACES で元のバージョンにつなぐ。
  • branch、HEAD、reflog のように移り変わるポインタはドキュメントに置かない。ドキュメントの外(ストア・インデックス)で管理する。
  • 新しいバージョンは定義を新設・改訂・削除できる。以前のバージョンとの互換は約束しない。同じ用語の定義が変わることも改訂である(例: 민법(民法)「성년(成年)」20 歳 → 19 歳、형법(刑法)の強姦罪の客体「부녀(婦女)」→「사람(人)」)。
  • LOCAL ID はバージョンを越えるアイデンティティである(条文番号のように)。同じ LOCAL ID は、バージョンが違っても同じ対象を指す。
    • 新設: 新しい LOCAL ID を受け取る。ID に順序の意味はないため、「第X条の2」のような挿入は要らない。新しい番号はバージョン一覧の NEXT-LOCAL-ID から受け取る(auto increment)。
    • 改訂: 同じ LOCAL ID の内容を変える。
    • 削除: その LOCAL ID を新しいバージョンから除く。削除した ID は再び使わない。
    • 移動・分割・統合: 新しい LOCAL ID を受け取り、新しいレコードに QUALIFIER P1365(replaces、値は旧 LOCAL ID)を付けて旧 ID につなぐ。旧 ID は再び使わないため、以前のバージョンのそのレコードを指す。
  • 原典資料からドキュメントを作り直すツールもこの規則を守る。直前のバージョンと同じ叙述には同じ LOCAL ID を与え、変わった叙述や新しく生じた叙述にだけ新しい番号を与える。番号を毎回 1 から振り直してはならない。
  • 引用は版を特定する。バージョンを固定した引用はそのバージョンに、最新(バージョン 0)の引用は解釈時点の現行バージョンに結びつく。過去の事件を扱うドキュメントは、その時点で施行されていたバージョンを固定して引用する。
  • 公表と施行は異なる。公表時刻はバージョン一覧が、施行期間はドキュメントが記す。
    • EFFECTIVE-FROM・EFFECTIVE-UNTIL: バージョン全体の施行期間
    • 条文 Edge の QUALIFIER P580(開始)・P582(終了): 条文ごとに施行日が異なるとき
  • 時点 T に施行中の版は、施行日が T 以前で最も高いバージョンである。 条文ごとの P580・P582 QUALIFIER があれば、それが優先する。有効期間(EFFECTIVE-UNTIL)が過ぎた版は施行中ではない。
  • 経過規定(「従前の規定による」)、行為時法と被告人に有利な新法の選択のように、どの版を適用するかを定める規則は判定(TOULMIN)が担う。施行情報はその材料である。
  • 解釈例・判例が用語の解釈を狭めたり広げたりするのはドキュメントの改訂ではなく判定規則である。解釈を立法で定めた場合(例: 근로기준법(労働基準法)「1주(1 週)」の定義新設)は改訂である。
  • Codec と Codec 番号のバイナリ(wire)レイアウトは改訂しない。Codec 番号でエンコードされたレコードは、コードブックのバージョンを固定せずに読まれるからである。レイアウトを変えるには新しい番号を割り当てる。削除した Codec 番号は他の形式に再び使わない。

diff の保存

バージョンは常にドキュメント全体(スナップショット)で定義する。diff は、そのスナップショットを少なく保存・転送するための形式にすぎない。

  • DOC-ID があり BODY がすべて Edge であるドキュメントだけを diff にできる。DOC-ID を置かないバージョン一覧 versions.geul、一覧ドキュメント(issuers/ のバージョン)、名前のないドキュメントは diff にしない。
  • diff ドキュメントは一般の GEUL ドキュメントであり、HEAD に DELTA-BASE(基準バージョン ID)を置く。
  • 削除は DELTA-REMOVE(除く LOCAL ID の一覧)で、追加と改訂は BODY の Edge で書く。追加・改訂の印は別にない。Edge Id が基準にあれば改訂、なければ追加である。
  • スナップショットの復元は決定的でなければならない(そうでないとハッシュが合わない)。
    1. 基準バージョンのスナップショットを復元する。基準も diff なら再帰で復元する。
    2. HEAD は、diff の HEAD から DELTA-BASE・DELTA-REMOVE を除いたもので丸ごと置き換える。HEAD Edge も一緒に置き換わる(DELTA-REMOVE には書かない)。
    3. BODY は基準の順序を保つ。DELTA-REMOVE の ID は除き、diff BODY の Edge Id が基準にあればその位置で置き換える。
    4. 基準にない Edge Id は、diff に現れた順序で末尾に付ける。
    5. 結果のコンテンツハッシュが、バージョン一覧のこのバージョンのハッシュと同じでなければならない。異なれば invalid である。
  • 削除した LOCAL ID を diff で再び使えば invalid である。抜けた HEAD Edge の Edge Id も再び使わない。
  • コンテンツハッシュ、バージョン一覧、署名はすべて、復元したスナップショットを基準とする。