GEUL указывает на документ не строкой URL, а ID (Issuer, ID документа, ID версии). Адрес определяется по ID. Эта страница задаёт правила публикации, необходимые для согласованной работы кодировщиков, декодеров и интерпретаторов. Классы Issuer и способы раскрытия определяет Issuer и публикация.

Запись ID

ID, используемые в адресе, записываются в hex.

  • Префикс — строчный 0x. Шестнадцатеричные цифры пишутся заглавными A-F. Интерпретатор приводит адрес, записанный строчными, к заглавным при поиске.
  • Число цифр фиксировано: ширина × 4. Ведущие нули не опускаются, число цифр и есть ширина.
  • При записи адреса Issuer пишется с числом цифр, соответствующим ширине выдачи: 2 WORD — 8 цифр, 4 WORD — 16 цифр, 16 WORD — 64 цифры.
  • При чтении Issuer принимается в любой из форм: 8, 16 и 64 цифры. Длинная запись короткого ID Issuer с ведущими нулями ищется как тот же Issuer (0x00000001 и 0x0000000000000001 — один Issuer, Issuer и публикация).
ОбъектШиринаЧисло цифрПример
Issuer2 WORD80x00000001
Issuer4 WORD160x0000000100000000
Issuer16 WORD640x + 64 цифры
Codec ID2 WORD80x00000AA0
ID документа4 WORD160x0000000000000000
ID версии2 WORD80x00000003
Хеш содержимого16 WORD640x + 64 цифры
  • Codec ID прямого кода GEUL — это его TAG WORD (L=0), записанный как 32-битное значение (TRIPLE 0x0AAL → 0x00000AA0). Kind содержится в TAG, поэтому пересечений нет.
  • Codec формата ISSUER другого Issuer помещается под codecs/ этого Issuer по номеру Codec из записи. Пример: IETF CRC32C — 0x00000007/codecs/0x0000C000/.
  • Codec ID Codec Issuer — это номер Codec из записи (2 WORD). Issuer назначает номера Codec внутри своего <Issuer>/codecs/ без пересечений независимо от Kind (Reference, Value, Edge). Адрес по Kind не делится (папок вроде references/, values/, edges/ нет).
  • Если Kind записи отличается от Kind цели DECLARE в документе этого Codec, интерпретатор считает это ошибкой.
  • Публикация отвергает размещение другого Codec под тем же Codec ID.
  • Правила ID версии (с 1, 0 — последняя, назначает публикующая сторона, при исчерпании — новый ID документа) задаёт Документ.

Адрес публикации

/.well-known/geul/issuers/latest.geul                              Список Issuer, последний
/.well-known/geul/issuers/<ID версии>.geul                         Список Issuer, указанная версия
/.well-known/geul/issuers/versions.geul                            Список версий списка Issuer
/.well-known/geul/<Issuer>/codecs/<Codec ID>/latest.geul           Codec, последний
/.well-known/geul/<Issuer>/codecs/<Codec ID>/<ID версии>.geul      Codec, указанная версия
/.well-known/geul/<Issuer>/codecs/<Codec ID>/versions.geul         Список версий Codec
/.well-known/geul/<Issuer>/docs/<ID документа>/latest.geul         Документ, последний
/.well-known/geul/<Issuer>/docs/<ID документа>/<ID версии>.geul    Документ, указанная версия
/.well-known/geul/<Issuer>/docs/<ID документа>/versions.geul       Список версий документа
/.well-known/geul/<Issuer>/hashes/<хеш содержимого>.geul           Поиск по хешу содержимого

Пример: /.well-known/geul/0x00000002/docs/0x0000000000000000/latest.geul

  • Путь следует .well-known из RFC 8615. geul.org и частная публикация используют один путь, различается только домен. Регистрируемый суффикс один — geul.
  • Список Issuer — это issuers/. Codec, обычные документы и хеши разделяются под папкой Issuer на codecs/<Codec ID>/, docs/<ID документа>/, hashes/. Список Issuer тоже начинается с версии 1 и имеет versions.geul (Документ-список).
  • latest.geul — зарезервированное слово и псевдоним. Он не хранится. Из versions.geul на том же месте находится самая последняя версия, и байты этой версии отдаются как есть. Перенаправления нет. Все latest.geul списка Issuer, Codec и документов устроены одинаково.
  • Канонический адрес одной версии — /<Issuer>/docs/<ID документа>/<ID версии>.geul. У Codec — /<Issuer>/codecs/<Codec ID>/<ID версии>.geul. Другие адреса, отдающие то же содержимое, указывают на канонический адрес через Link: rel=canonical.
  • Адрес с указанной версией и адрес по хешу содержимого неизменны. Неизменные адреса можно помещать в постоянный кэш и CDN. Получатель проверяет их по хешу содержимого из списка версий (или записи блокировки).
  • Чтобы искать по хешу содержимого, нужно знать Issuer. Глобального поиска только по хешу нет.
  • У документа Codec нет ID документа. Он указывает на себя и свою версию через CODEC-POINTER (Issuer, Codec ID, ID версии).
  • ID всегда начинается с 0x. Поэтому зарезервированные имена (issuers, codecs, docs, hashes, latest.geul, versions.geul) и имена, данные человеком, не пересекаются с ID, даже если это слово из одних hex-цифр, например add, cafe.
  • Местоположение (с какого сервера получать) в содержимое документа не помещается. Иначе при смене адреса менялся бы хеш содержимого. Местоположение определяет настройка принимающей стороны.

Форма публикации и поиск

  • Адрес — логический. Публикующая сторона может выдавать отдельные файлы или pack, и если это pack, получить его напрямую по URL-адресу нельзя, он читается интерпретатором GEUL.
  • Независимо от того, хранится ли он как отдельные файлы, pack или zstd pack, он находится по тому же адресу. Адрес вне перечисленных выше 10 форм и несуществующий адрес дают 404 (нет).

Инструмент командной строки geul (gogeul):

geul get <адрес>     выводит чистый бинарный документ GEUL в стандартный вывод
geul show <адрес>    показывает документ в виде текста
  • geul get принимает адреса file:// и https://. Адрес вне 10 форм и несуществующий адрес завершаются 404 (нет).

pkg/resolve библиотеки Go gogeul содержит функцию поиска для каждого адреса. Все они возвращают чистый бинарный GEUL ([]byte). ID версии начинается с 1, поэтому Latest (0) — последняя. Несуществующий адрес — ошибка «нет» (ErrNotFound).

const Latest uint32 = 0

Issuers(ctx, v)               / IssuersVersions(ctx)
Codec(ctx, issuer, codec, v)  / CodecVersions(ctx, issuer, codec)
Doc(ctx, issuer, doc, v)      / DocVersions(ctx, issuer, doc)
Hash(ctx, issuer, hash)

ParseAddr(s string) (Addr, error)   // формы вне 10 — 404 (нет)
Fetch(ctx, Addr) ([]byte, error)    // geul get = ParseAddr → Fetch → стандартный вывод

Указание формата

  • Адрес публикации оканчивается на .geul и является бинарным (application/vnd.geul).
  • Каноническая форма документа — бинарная. Хеш содержимого и подпись вычисляются только по бинарной форме.

Документ-список

Документ-список — один: список Issuer issuers/. Он связывает Issuer и домен (Список Issuer). Он начинается с версии 1 и имеет versions.geul. ID документа этого списка — зарезервированный ID документа 0xFFFFFFFFFFFFFFFF (Issuer geul.org 0x00000000). Каждый Issuer резервирует ID документа 0x0000000000000000 и 0xFFFFFFFFFFFFFFFF (Issuer и публикация).

  • latest.geul — несохраняемый псевдоним. Из versions.geul находится самая последняя версия, и отдаются её байты.
  • PUBLICATION, DEPRECATION и TOMBSTONE в issuers/versions.geul указывают на версию списка через DOC-POINTER (0x00000000, 0xFFFFFFFFFFFFFFFF, ID версии). Поэтому даже при получении через hashes/ известно, чей это список (PUBLICATION).
  • ID документа 0xFFFFFFFFFFFFFFFF ни у какого Issuer не отдаётся по адресу <Issuer>/docs/<ID документа>/ (404). Другой зарезервированный ID документа, 0x0000000000000000, — индексный документ определений терминов этого Issuer, и он помещается под docs/ (Issuer и публикация).
  • В документ-список DOC-ID не ставится. Чей это список, сообщает DOC-POINTER в записи (DOC-ID).
  • Документы и Codec находятся без списка, сразу по ID, вычисленному из записи (Имя документа).

Доменное имя

Доменное имя — не URL-адрес публикации. Адрес, где на месте <Issuer> стоит домен или на месте ID стоит имя, находится вне 10 форм выше и даёт 404 (нет). Перенаправления с имени на адрес по ID тоже нет.

  • Доменное имя — ввод для интерпретатора и CLI. Интерпретатор превращает домен в ID Issuer через BIND в списке Issuer issuers/. Полученный ID остаётся в записи блокировки. Адреса по имени документа нет (Имя документа).
  • Канонический адрес, ключ кэша и объект подписи — адреса по ID.
  • Домен пишется строчными, интернационализированный домен — в форме IDNA (punycode). Завершающая . не ставится.
  • 16-WORD Issuer без реестра и изолированная от сети среда, не достигающая geul.org, доменные имена использовать не могут. Используется ID.

Список Issuer

Список Issuer — документ под /.well-known/geul/issuers/ (последний — issuers/latest.geul). Он связывает Issuer и его имя (домен).

BODY
  BIND   Subject = ISSUER-POINTER(Issuer)   имя = "geul.org"
  …
  • Subject — ISSUER-POINTER (сам Issuer), а имя связывается через BIND.
  • Имя — домен, прошедший подтверждение владения. Оно строчное, а интернационализированный домен пишется в IDNA (punycode). Одно имя связывается только с одним Issuer.
  • Отображаемое человеком имя Issuer (по языкам) присоединяется к тому же Subject описанием LABEL.
  • Подписывает geul.org (GEUL Issuer), при изменении дополняется и не исправляется (то же правило цепочки, что у списка версий).

Имя документа

Адреса по имени документа нет. Документы и Codec находятся по ID.

  • Индекса, превращающего имя документа или имя Codec в ID, нет. Имя документа через BIND в списке версий тоже не ставится (PUBLICATION).
  • Индекс для просмотра человеком строит инструмент (просмотрщик) по инвентарю pack.
  • Канонический адрес, ключ кэша и объект подписи — адреса по ID. IMPORT и цитаты внутри документа делаются только по ID.
  • Читаемый человеком заголовок (по языкам) присоединяется описанием LABEL.

Удалённые документы

  • Адрес версии, отозванной удалением по закону или по должностному решению (TOMBSTONE), тоже даёт 404 (нет), как и другие несуществующие адреса.
  • Версия, для которой рекомендован отказ от использования (DEPRECATION), не даёт 404. Она продолжает отдаваться по адресу этой версии.
  • Удаление остаётся в списке версий записью TOMBSTONE (DOC-POINTER этой версии, категория причины).

Уровни

GEUL выражает в виде документов GEUL и происхождение, и Meta, и списки. Минимум, необходимый для их чтения, встроен в декодер, что разрывает цикл. Каждый уровень опирается только на нижние.

УровеньСодержаниеНа что опирается
Уровень 0Встроенные в декодер правила: фрейминг, хеш содержимого, проверка подписи, Codec записей списка версий (PUBLICATION, DEPRECATION, TOMBSTONE), словарь спецификации Codec (DECLARE, FIELD, ENUM, CODEC), маркер места (0x0000, 0x0010, 0x0020), доверенные ключи, получаемые вне документаНи на что. Поиска не выполняет
Уровень 1Документ списка версийУровень 0
Уровень 2Обычные документы, кодекбуки, документы спецификации Codec, документ ключей проверки IssuerНаходятся через уровень 1, проверяются через уровень 0
  • Ни один уровень не опирается на себя или на вышестоящие.
  • Следует различать то, что выражается на GEUL, и то, что читается только интерпретацией средствами GEUL. Уровень 0 можно выразить на GEUL, но для его интерпретации поиск не требуется.
  • Фиксированное ядро, которое нельзя превратить в документ TOULMIN, как смысл вердикта, тоже помещается здесь (TOULMIN).

Список версий

Публикующая сторона для каждого документа ведёт один документ списка версий (/<Issuer>/docs/<ID документа>/versions.geul, для Codec — /<Issuer>/codecs/<Codec ID>/versions.geul, для списка Issuer — issuers/versions.geul). Формат записей и структуру документа задаёт PUBLICATION.

DOC-*
  SPEC-VERSION
  PARENT          хеш содержимого предыдущего списка версий
  RECORDED-AT     время выпуска этого списка
  NEXT-LOCAL-ID   LOCAL ID, назначаемый следующим
  SIGNATURE       подпись публикующей стороны
BODY
  PUBLICATION     #1  документ@1  хеш содержимого
  PUBLICATION     #2  документ@2  хеш содержимого
  DEPRECATION     #3  документ@1
  …
END
EdgeЗначение
PUBLICATIONПубликует одну версию документа и её хеш содержимого
DEPRECATIONПомечает опубликованную версию рекомендацией отказа от использования. Продолжает интерпретироваться
TOMBSTONEУдаляет опубликованную версию (по закону или по должностному решению). Записывается категория причины
  • Записи только добавляются. Их не исправляют, не удаляют и не переставляют. Устаревание и удаление тоже добавляются записями. Новый список ставит BODY предыдущего списка как есть в начало и добавляет записи, а списки связываются цепочкой хешей PARENT.
  • Это лишь означает, что запись о публикации не исправляется, и не то же самое, что редакция содержимого документа (Документ). Текущее состояние версии вычисляется последовательным применением записей.
  • ID версии идёт с 1 по возрастанию без пропусков. Одно и то же содержимое повторно не публикуется.
  • Последняя версия — самая высокая версия, для которой нет ни рекомендации об отказе, ни удаления.
  • Время в записи не ставится. Временем публикации является RECORDED-AT списка, в котором эта запись впервые появилась.
  • В список версий DOC-ID не ставится. Чей это список, сообщает DOC-POINTER в записи (ID документа, для списка Issuer — зарезервированный ID документа).
  • Список версий не содержит IMPORT и использует только Codec уровня 0. В BODY ставятся только PUBLICATION, DEPRECATION и TOMBSTONE.
  • На прошлые списки версий указывают только по хешу содержимого (<Issuer>/hashes/<хеш содержимого>.geul), а история связывается цепочкой PARENT.
  • Изменяемые адреса — latest.geul и versions.geul. Изменяемый указатель нельзя сделать документом, поэтому он проверяется по подписи полученного списка, RECORDED-AT и PARENT.

Субъект подписи

ПодписьСубъектОбъект
Подпись документаIssuer этого документаХеш содержимого документа (Issuer и публикация)
Подпись спискаПубликующая сторона, назначившая ID версииХеш содержимого списка версий
  • Публикацию на geul.org выполняет geul.org (GEUL Issuer), частную — сам этот Issuer: он назначает ID версий и подписывает список.
  • Автор отвечает за содержимое, публикующая сторона — за номера и порядок.

Проверка

  • Подпись исключается из хеша содержимого, поэтому при её удалении хеш не меняется. Поэтому проверка выполняется не как «если подпись есть, проверить», а как «подпись заданного ключа должна быть». Требуемый ключ определяют настройки доверия интерпретатора и запись блокировки.
  • Интерпретатор сохраняет в записи блокировки хеш содержимого последнего виденного списка. Если этого хеша нет в цепочке PARENT вновь полученного списка, список отвергается (защита от отката и ветвления).
  • Зеркала и изолированные среды копируют цепочку списков версий вместе. Если есть открытый ключ, проверка выполняется офлайн.
  • Полученный документ проверяется по хешу содержимого, откуда бы он ни пришёл. Доверять источнику не требуется.

Разрешение зависимостей

  • Документ записывает зависимые документы через IMPORT-DOC в HEAD.
  • Новая версия не обещает совместимости с предыдущей. Поэтому версии одного документа во всём графе в одну не сводятся (минимальный выбор версий не применяется).
  • Каждый IMPORT-DOC привязан к зафиксированной им редакции. В одном графе могут одновременно находиться несколько редакций одного документа (решение, цитирующее прежний закон, и решение, цитирующее действующий закон). Ссылка разрешается как (документ, версия, LOCAL ID).
  • Импорт последней (версия 0) привязан к последней редакции на момент интерпретации. Если интерпретация выполняется на заданный момент, он привязан к редакции, действовавшей в этот момент (Документ).
  • Импорт, зафиксированный по ID версии, воспроизводим (содержимое ID версии неизменно и проверяется по записи блокировки).

Медиатип

  • Медиатип документа GEUL — application/vnd.geul. Расширение — .geul.
  • Даже при переносе в стандартное дерево application/geul продолжает приниматься application/vnd.geul.

Открытые проблемы

  • Обработка случая, когда ID версии расходятся (один ID версии, разное содержимое) при частной публикации, 16-WORD Issuer и изолированных средах.
  • Состав HEAD списка Issuer issuers/, формат подписи и цепочки. Правила имён для Issuer без домена (4 WORD), обработка споров об именах и предел длины.
  • Момент и формат перехода от полной цепочки к журналу Merkle (доказательства включения и согласованности), когда список вырастет.
  • Meta, записывающий в HEAD Issuer, предоставляющий местоположение.