Как Codec строит Payload, определяет кодекбук. Кодекбук GEUL — не отдельный формат, а документ GEUL. Один Codec — один документ спецификации.

Расположение документа спецификации

Документы спецификации прямых кодов публикует Issuer GEUL (0x00000000). Документ спецификации — это документ Codec, и ID документа у него нет. Codec ID — это TAG WORD данного Codec (только раздел и позиция Codec в C, Length равен 0), записанный как 32-битное значение.

/.well-known/geul/0x00000000/codecs/0x0000<TAG>/<ID версии>.geul
CodecTAGДокумент спецификации
Reference LOCAL00500x00000000/codecs/0x00000050
Value QUANTITY06600x00000000/codecs/0x00000660
Edge TRIPLE0AA00x00000000/codecs/0x00000AA0
Edge PUBLICATION0B800x00000000/codecs/0x00000B80

Декодер строит адрес документа спецификации только по TAG WORD. Встретив неизвестный Codec, он может получить и прочитать этот документ.

  • <TAG> — 4 hex-цифры (заглавные) целевого TAG WORD. Позиция Length — 0000. Документ Codec один на каждый код. Система Reference 5Q тоже держит отдельный документ на каждый код квантификации (LOCAL Identified 0050, LOCAL Generic 0060). Прямые коды и Codec Issuer используют одно правило адресации <Issuer>/codecs/<Codec ID>/ (Адрес публикации и список версий).
  • У маркера места (0x0000, 0x0010, 0x0020) тоже есть документ спецификации. Payload нет, поэтому есть только DECLARE и нет FIELD. Значение маркера и правила его приёма встроены в декодер (уровень 0). Codec, макет которого ещё не определён, тоже начинается с документа спецификации, содержащего только DECLARE.
  • В документе спецификации в качестве DOC-ID ставится CODEC-POINTER (0x00000000, 0x0000<TAG>, 0). Запись списка версий использует тот же CODEC-POINTER.
  • Правила версий, канонического адреса и подписи — те же, что у обычных опубликованных документов.

Кодекбук и редакция спецификации

  • Документ Codec тоже можно импортировать через IMPORT-DOC. Тогда вместо DOC-POINTER на месте документа ставится CODEC-POINTER. SPEC-VERSION в HEAD документа определяет, какому кодекбуку он следует.
  • Каждый декодер встраивает базовый кодекбук либо получает его по этому адресу.
  • Когда предложение (Prefix 000) принимается как стандарт, макет остаётся прежним, а Prefix меняется на 001 (Обзор). Целевой TAG WORD становится другим, поэтому принятая версия становится новым документом спецификации с другим Codec ID, а документ предложения остаётся неизменным.

Четыре словаря

EdgeCodecЧто делает
DECLARE0x0BBLОбъявляет состав Payload одного Codec. Целевой TAG WORD — 1 WORD
FIELD0x0BCLОдно поле Payload. Принадлежность к DECLARE и ширина
ENUM0x0BDLПридаёт смысл одному кодовому значению поля с простым значением
CODEC0x0BELУказывает один Kind или Codec, принимаемый полем
  • Макеты четырёх Edge встроены в декодер (уровень 0), потому что документ спецификации нужно читать без кодекбука. Для чтения документа спецификации другие документы спецификации не нужны.
  • Все имена (имя Codec, имя поля, имя кодового значения) связываются через BIND.

FIELD

Edge Id           LOCAL
DECLARE           LOCAL (DECLARE, которому принадлежит это поле)
Ширина            1 WORD: 0 = запись, n = простое значение в n WORD, 0xFFFF = остаток простых значений
  • Порядок в документе полей FIELD, указывающих на один и тот же DECLARE, и есть порядок полей Payload.
  • Поле-запись начинается с TAG WORD и читается на его Length.
  • Поле с простым значением — беззнаковое целое, читаемое на заданное число WORD. Значения, требующие интерпретации (знак, дробь, дата), задаются не простым значением, а записью Value.
  • Остаток простых значений (0xFFFF) может быть только один, и после него идут только простые значения фиксированной ширины.
  • Edge Id у Edge не объявляется через FIELD. Он первый элемент любого Edge, поэтому подразумевается. EDGE-ISSUER — первый элемент после Issuer и номера Codec (EDGE-ISSUER-2WORD).
  • Позиция после последовательного чтения полей должна точно совпасть с концом записи.

CODEC

Задаёт формат, принимаемый полем. Целевой WORD использует позицию Codec TAG WORD (раздел KKKK и C) без изменений.

Позиция LengthЗначениеПример
0000Точный Codec0680 SIGNED-DECIMAL, 0050 LOCAL
1111Шаблон: независимо от значения C — весь раздел KKKK (32 позиции). Рекомендуется первая позиция раздела (C = 0)000F весь раздел 0, 060F весь раздел 3
  • Если Kind охватывает несколько разделов, CODEC перечисляется для каждого раздела. Любой Reference — 000F, 020F, 040F; любой Value — 060F, 080F.

  • Для группы, безразличной к квантификации, перечисляются точные Codec. QID Викиданных (безразличный к квантификации) — это пять Codec: 0140, 0150, 0160, 0170, 0180.

  • Если у поля-записи нет CODEC, оно принимает любую запись (кроме маркера места). Если есть хотя бы один, запись должна быть одной из них (закрытый список).

  • Если у поля с простым значением задан один CODEC, это значение интерпретируется как соответствующий Value без TAG.

Необязательные поля и маркер места

Маркер места — группа 1-WORD записей, назначенная первым трём позициям 0x000L~0x002L раздела 0 Reference. Он может стоять на месте поля, только если список CODEC этого поля содержит данный WORD как точную цель.

Цель CODECМаркерЭто поле
0000ABSENT, не записаноНеобязательное поле. Его можно опустить
0010UNKNOWN-VALUE, неизвестноПринимает утверждение, что значение есть, но неизвестно, какое
0020NO-VALUE, нетПринимает утверждение, что значения нет
  • Правило приёма: маркер действителен, только если тот же WORD есть в списке CODEC этого поля как точная цель. Шаблоны (000F, 060F …) и поля без CODEC («любая запись») маркер не принимают. На местах записей HEAD и BODY и на месте Edge Id маркер недействителен.
  • При опускании необязательного поля на его место пишется один WORD 0x0000 (ABSENT). Необязательное поле тоже всегда занимает место. Поэтому представление одной записи единственно, а разбор определяется только позицией.
  • У маркера есть собственный код Reference, он не пересекается с другими записями, и декодер, не знающий спецификации, пропускает его как 1-WORD запись.
  • Три маркера означают разное. ABSENT — высказывание о документе (это место не заполнено), поэтому ничего не утверждает о мире. UNKNOWN-VALUE утверждает, что значение есть (∃x), NO-VALUE утверждает, что значения нет (¬∃x, внутри ограничивающего условия). Пропуск — это «не записано», а не «значения нет».
  • Что именно означает маркер, определяет спецификация принимающего его Codec (TRIPLE, QUALIFIER).

Пример: документ спецификации TRIPLE

BODY документа 0x00000000/codecs/0x00000AA0.

EdgeСодержаниеИмя (BIND)
#1 DECLAREцель 0AA0TRIPLE
#2 FIELDполе #1, записьpredicate
#3 FIELDполе #1, записьsubject
#4 FIELDполе #1, записьobject
#5 FIELDполе #1, простое значение 1 WORDrank
#6~#8 ENUMкодовые значения 0, 1, 2 поля #5normal, preferred, deprecated
#17 CODEC#5 интерпретируется как UNSIGNED-INTEGER (0620)
#18, #22, #23, #19, #24 CODEC#4 — любой Reference (000F·020F·040F) или любой Value (060F·080F)
#20, #21 CODEC#4 принимает также UNKNOWN-VALUE (0010), NO-VALUE (0020)
#25~#27 CODEC#2 — любой Reference (000F·020F·040F)
#28~#30 CODEC#3 — любой Reference (000F·020F·040F)

Только по этому документу декодер делит запись TRIPLE на поля, показывает её с именами полей и проверяет соответствие формату.

Пример: документ спецификации QUANTITY

У Value QUANTITY (0660) все четыре поля — записи.

ПолеCODEC
amount0610 SIGNED-INTEGER, 0620 UNSIGNED-INTEGER, 0630 BINARY-FLOAT (только конечные значения), 0670 FRACTION, 0680 SIGNED-DECIMAL, 0690 UNSIGNED-DECIMAL
unit000F·020F·040F любой Reference, 0000 необязательное
lower0610·0620·0630·0670·0680·0690 (как у amount), 0000 необязательное
upper0610·0620·0630·0670·0680·0690 (как у amount), 0000 необязательное

Правила

  • В одном документе спецификации один DECLARE. Цель DECLARE совпадает с TAG WORD Codec ID.
  • В одном документе одна и та же цель не объявляется дважды.
  • Варианты с другим составом полей не делаются ветвлением. Для каждого Codec делается отдельное объявление.
  • Нельзя объявить макет, в котором переменных простых значений больше одного или ширина простого значения зависит от другого значения. Такие части оборачиваются в запись.
  • Документ спецификации, как и другие документы, публикуется по версиям. Однако бинарный макет Codec не пересматривается. Чтобы изменить его, назначается новый Codec.

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

  • Соответствие значения SPEC-VERSION (в v1 — 0x0001) версии документа кодекбука. Meta родословной, связывающая принятую и предложенную версии.