Единица данных GEUL — один документ (DOC). Один файл (.geul, медиатип application/vnd.geul) — один документ.
Структура
DOC-* ← открывает документ (общая длина)
Meta … ← HEAD: записи о документе
SOURCE … ← (происхождение всего документа и его QUALIFIER)
BODY ← завершает HEAD и открывает BODY
Reference, Value, Edge …
END ← закрывает документ
| Запись | TAG | Значение |
|---|---|---|
| DOC-1WORD | 1C01 + 1 WORD | Открывает документ, задавая общую длину в 1 WORD |
| DOC-2WORD | 1C12 + 2 WORD | Общая длина в 2 WORD |
| DOC-4WORD | 1C24 + 4 WORD | Общая длина в 4 WORD |
| BODY | 1C30 | 1 WORD. Завершает HEAD и начинает BODY |
| END | 1C40 | 1 WORD. Закрывает документ |
- Значение DOC-* — общее число WORD от начала открывающей записи до конца END. Используется самая узкая ширина, в которую значение помещается.
- END обязателен. Если позиция END не совпадает с длиной DOC-*, документ отвергается. Если ввод закончился без END, документ усечён.
- Декодер может пропустить весь документ целиком по длине DOC-*.
- Открыть документ без известной длины нельзя. Данные реального времени, конец которых заранее неизвестен, режутся на единицы известной длины и передаются несколькими документами.
- Если HEAD пуст, BODY опускается. Документ без записей BODY — это целиком BODY. BODY ставится один раз. Если в HEAD есть хотя бы одна запись (Meta или HEAD Edge), BODY ставится.
- Документы не вкладываются. На другой документ указывают через IMPORT или Reference-указатель.
HEAD и BODY
- В HEAD ставятся только Meta и HEAD Edge. Все они — описание документа, который их содержит.
- Meta: структура, определения, происхождение, родословная, проверка, политика, IMPORT документа.
- HEAD Edge: Edge основания SOURCE, фиксирующий источник всего документа (Target
0), и QUALIFIER с этим SOURCE в качестве Target (хеш оригинала, время получения, диапазон оригинала и т. п.). QUALIFIER ставится после этого SOURCE.
- В BODY ставятся только Reference, Value и Edge. Происхождение отдельной записи пишется Edge основания SOURCE внутри BODY, а другие основания, например достоверность, — QUALIFIER, присоединённым к этой записи. SOURCE с Target
0и QUALIFIER, у которого Target — HEAD SOURCE, в BODY ставить нельзя. - Декодер читает HEAD с начала и разделяет записи. Meta — это HEAD. SOURCE с Target
0— это HEAD, и его Edge Id запоминается. QUALIFIER с запомненным SOURCE в качестве Target — это HEAD. Если приходит любая другая запись, то при пустом HEAD BODY опущен (BODY начинается с этой записи), иначе документ недействителен из-за пропущенного BODY. - Edge Id у HEAD и BODY — одно пространство номеров. Он уникален в пределах документа и, как у Edge в BODY, берётся из NEXT-LOCAL-ID. Если Origin у HEAD Edge — LOCAL, его определение ставится в BODY (областью LOCAL является весь документ).
- Meta может содержать в Payload записи Value. Содержащееся Value — не самостоятельная запись, а часть этого Meta.
- Область действия объявлений (Meta класса «объявление») — этот документ.
Базовые объявления
Обоих объявлений не больше одного. В каком документе они обязательны, определяют условия ниже.
| Meta | Значение | Документ, где обязательно |
|---|---|---|
| SPEC-VERSION | Редакция спецификации, которой следует документ. Определяет, как читать остальные записи. Если редакция неизвестна, документ отвергается или выдаётся предупреждение. У документа v1 значение 0x0001 | Опубликованный документ. Если нет, декодер читает по известной ему редакции |
| DOC-ID | Идентификатор самого документа. Нужен, чтобы указывать на этот документ и его объекты извне | Версионный документ в docs/<ID документа>/ и codecs/<Codec ID>/ под .well-known/geul/ (включая документы спецификации). В список версий versions.geul и документы-списки (issuers/) не ставится |
SPEC-VERSIONсодержит только одно целое, чтобы его мог прочитать декодер любой редакции (в v1 —1C51 0001). Он не опирается на код Value.DOC-ID— DOC-POINTER (Issuer, ID документа, версия0), указывающий на сам документ. ID документа — 4 WORD. У документа Codec нет ID документа, поэтому используется CODEC-POINTER (Issuer, Codec ID, версия0). Каждый Issuer резервирует ID документа0x0000000000000000и0xFFFFFFFFFFFFFFFF(Issuer и публикация).- Документ без
DOC-ID— безымянный. На него можно указать только по хешу содержимого.
Хеш содержимого
Один экземпляр документа указывается хешем содержимого (роль такая же, как у ID коммита в git).
- Это SHA-256 от открывающей записи (DOC-*) до записи непосредственно перед END. 16 WORD.
- Meta класса проверки (подписи и т. п.; в разделе 15 записи с
C >= 5, то естьw >= 0x1E50) исключаются из вычисления. Поэтому размещение подписи внутри документа не создаёт цикла. - При вычислении длина DOC-* заменяется длиной без записей проверки, а ширина — самой узкой, подходящей для этой длины. Поэтому хеш содержимого до и после добавления подписи одинаков.
- Хеш содержимого не записывается в документ, а вычисляется. Его значением пишут только при указании на другую версию (
PARENTи др.). PARENTвнутри документа тоже входит в вычисление, поэтому хеш содержимого образует цепочку хешей всей истории.- Meta, добавленные позже вне документа (например, аннотации в отдельном хранилище), хеш содержимого не меняют (как git notes).
- Каноническая форма документа — бинарная. Хеш содержимого и подпись вычисляются только по бинарной форме.
Версия
Именованный документ (документ с DOC-ID) имеет версии.
- ID версии — 2-WORD целое, нумеруемое с 1 в порядке публикации внутри одного документа.
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」 («статья X-2») не нужны. Новый номер берётся из
NEXT-LOCAL-IDсписка версий (auto increment). - Изменение: меняется содержимое под тем же LOCAL ID.
- Удаление: LOCAL ID исключается из новой версии. Удалённый ID повторно не используется.
- Перенос, разделение, объединение: получается новый LOCAL ID, и к новой записи присоединяется QUALIFIER P1365 (replaces, значение — прежний LOCAL ID), связывающий прежний ID. Прежний ID повторно не используется, поэтому он указывает на эту запись в предыдущей версии.
- Введение: получается новый LOCAL ID. У ID нет смысла порядка, поэтому вставки вроде 「제X조의2」 («статья X-2») не нужны. Новый номер берётся из
- Инструмент, заново создающий документ из исходного материала, тоже соблюдает это правило. Утверждениям, совпадающим с предыдущей версией, даётся тот же LOCAL ID, а новый номер получают только изменённые или новые. Нумеровать каждый раз заново с 1 нельзя.
- Цитата определяет редакцию. Цитата с зафиксированной версией привязана к этой версии, цитата последней (версия
0) — к действующей версии на момент интерпретации. Документ о прошлых событиях цитирует версию, действовавшую в то время, фиксируя её. - Публикация и вступление в силу — разные вещи. Время публикации фиксирует список версий, срок действия — документ.
- EFFECTIVE-FROM, EFFECTIVE-UNTIL: срок действия всей версии
- QUALIFIER P580 (начало) и P582 (конец) на Edge статьи: когда у статей разные даты вступления в силу
- Редакция, действующая в момент T, — это самая высокая версия, дата вступления в силу которой не позже T. Если есть QUALIFIER P580 и P582 по статьям, они имеют приоритет. Редакция, у которой истёк срок действия (
EFFECTIVE-UNTIL), не действует. - Правила, определяющие, какую редакцию применять (переходные положения «применяется прежнее правило», выбор между законом времени деяния и более благоприятным для подсудимого новым законом), относятся к вердикту (TOULMIN). Сведения о вступлении в силу — материал для него.
- Сужение или расширение толкования термина разъяснениями и судебными прецедентами — не редакция документа, а правило вердикта. Если толкование установлено законодательно (например, введение определения «1 недели» в Законе о трудовых стандартах Кореи), это редакция.
- Бинарный (wire) макет Codec и номера Codec не пересматривается. Запись, закодированная номером Codec, читается без фиксации версии кодекбука. Чтобы изменить макет, назначается новый номер. Удалённый номер Codec для другого формата повторно не используется.
Хранение diff
Версия всегда определяется как документ целиком (снимок). diff — лишь формат, позволяющий хранить и передавать этот снимок компактнее.
- В виде diff можно хранить только документ, у которого есть
DOC-IDи все записи BODY — Edge. Для списка версийversions.geul, не содержащегоDOC-ID, документов-списков (версийissuers/) и безымянных документов diff не заводится. - Документ diff — обычный документ GEUL, в HEAD которого ставится DELTA-BASE (ID базовой версии).
- Удаление записывается DELTA-REMOVE (список удаляемых LOCAL ID), добавление и изменение — Edge в BODY. Отдельного признака добавления или изменения нет. Если Edge Id есть в базе — это изменение, если нет — добавление.
- Восстановление снимка должно быть детерминированным (иначе хеш не сойдётся).
- Восстанавливается снимок базовой версии. Если база сама diff, она восстанавливается рекурсивно.
- HEAD целиком заменяется на HEAD из diff без
DELTA-BASEиDELTA-REMOVE. HEAD Edge тоже заменяются вместе с ним (вDELTA-REMOVEне записываются). - BODY сохраняет порядок базы. ID из
DELTA-REMOVEудаляются, а если Edge Id из BODY diff есть в базе, запись заменяется на месте. - Edge Id, которых нет в базе, добавляются в конец в том порядке, в котором они встретились в diff.
- Хеш содержимого результата должен совпасть с хешем этой версии в списке версий. Если нет, документ недействителен.
- Повторное использование в diff удалённого LOCAL ID недействительно. Edge Id удалённого HEAD Edge тоже повторно не используется.
- Хеш содержимого, список версий и подписи — всё считается по восстановленному снимку.