Как 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
| Codec | TAG | Документ спецификации |
|---|---|---|
| Reference LOCAL | 0050 | 0x00000000/codecs/0x00000050 |
| Value QUANTITY | 0660 | 0x00000000/codecs/0x00000660 |
| Edge TRIPLE | 0AA0 | 0x00000000/codecs/0x00000AA0 |
| Edge PUBLICATION | 0B80 | 0x00000000/codecs/0x00000B80 |
Декодер строит адрес документа спецификации только по TAG WORD. Встретив неизвестный Codec, он может получить и прочитать этот документ.
<TAG>— 4 hex-цифры (заглавные) целевого TAG WORD. Позиция Length —0000. Документ Codec один на каждый код. Система Reference 5Q тоже держит отдельный документ на каждый код квантификации (LOCAL Identified0050, LOCAL Generic0060). Прямые коды и 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, а документ предложения остаётся неизменным.
Четыре словаря
| Edge | Codec | Что делает |
|---|---|---|
| DECLARE | 0x0BBL | Объявляет состав Payload одного Codec. Целевой TAG WORD — 1 WORD |
| FIELD | 0x0BCL | Одно поле Payload. Принадлежность к DECLARE и ширина |
| ENUM | 0x0BDL | Придаёт смысл одному кодовому значению поля с простым значением |
| CODEC | 0x0BEL | Указывает один 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 | Точный Codec | 0680 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 | Маркер | Это поле |
|---|---|---|
0000 | ABSENT, не записано | Необязательное поле. Его можно опустить |
0010 | UNKNOWN-VALUE, неизвестно | Принимает утверждение, что значение есть, но неизвестно, какое |
0020 | NO-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 | цель 0AA0 | TRIPLE |
| #2 FIELD | поле #1, запись | predicate |
| #3 FIELD | поле #1, запись | subject |
| #4 FIELD | поле #1, запись | object |
| #5 FIELD | поле #1, простое значение 1 WORD | rank |
| #6~#8 ENUM | кодовые значения 0, 1, 2 поля #5 | normal, 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 |
|---|---|
amount | 0610 SIGNED-INTEGER, 0620 UNSIGNED-INTEGER, 0630 BINARY-FLOAT (только конечные значения), 0670 FRACTION, 0680 SIGNED-DECIMAL, 0690 UNSIGNED-DECIMAL |
unit | 000F·020F·040F любой Reference, 0000 необязательное |
lower | 0610·0620·0630·0670·0680·0690 (как у amount), 0000 необязательное |
upper | 0610·0620·0630·0670·0680·0690 (как у amount), 0000 необязательное |
Правила
- В одном документе спецификации один DECLARE. Цель DECLARE совпадает с TAG WORD Codec ID.
- В одном документе одна и та же цель не объявляется дважды.
- Варианты с другим составом полей не делаются ветвлением. Для каждого Codec делается отдельное объявление.
- Нельзя объявить макет, в котором переменных простых значений больше одного или ширина простого значения зависит от другого значения. Такие части оборачиваются в запись.
- Документ спецификации, как и другие документы, публикуется по версиям. Однако бинарный макет Codec не пересматривается. Чтобы изменить его, назначается новый Codec.
Открытые проблемы
- Соответствие значения
SPEC-VERSION(в v1 —0x0001) версии документа кодекбука. Meta родословной, связывающая принятую и предложенную версии.