Перевод для чтения человеком. Сверен с английским оригиналом ревизии 61e75e9 (на английском). Перевод не является новой редакцией нормативного контракта. Текущая английская страница.
Статус: принят для перехода чтения и проверки на v0.2.
Нормативный источник — GoogleCloudPlatform/knowledge-catalog/okf/SPEC.md
в коммите 3fcbb9f828c2f23d109c855ee403c3a4c81f3a96. Неизменяемый адрес исходного файла:
https://raw.githubusercontent.com/GoogleCloudPlatform/knowledge-catalog/3fcbb9f828c2f23d109c855ee403c3a4c81f3a96/okf/SPEC.md
Его SHA-256:
5a3311d270bebb16d558010e75064f5b75323f284992641732b1c8097511f948.
Машиночитаемая фиксация находится в fixtures/v02/spec-lock.json. Нормативные
положения — §§1–13; приложение A содержит канонический сквозной пример.
При чтении объявленная версия и фактически применяемый контракт учитываются отдельно.
| Вход | Применяемый контракт | Источник выбора | Совместимость |
|---|---|---|---|
объявлена 0.1 |
0.1 |
declared |
legacy |
объявлена 0.2 |
0.2 |
declared |
native |
| объявления нет | 0.2 |
default |
native с правилами совместимости §13 |
| синтаксически корректное объявление неподдерживаемой версии | 0.2 |
future-best-effort |
best-effort |
| явно выбранная поддерживаемая версия без противоречащего объявления | выбранная версия | explicit |
native или legacy |
Явный выбор версии задаёт обязательное условие. Противоречащее ему объявление —
ошибка; реализация не должна молча применять другую семантику. Объявление
okf_version использует канонический синтаксис <major>.<minor>.
Синтаксически корректные неподдерживаемые объявления остаются видимыми, хотя
чтение выполняется по v0.2 в режиме максимально возможной совместимости.
Некорректное объявление считается ошибкой структуры корневого индекса и никогда
не обозначается как совместимость с будущей версией. Версии Go-модуля,
исполняемого файла и плагина не связаны с okf_version.
future-best-effort — зафиксированная публичная метка источника выбора для любого
канонического неподдерживаемого объявления, в том числе численно более раннего,
например 0.0. Метка обозначает способ совместимого чтения и не утверждает,
что объявленная версия новее 0.2. Исходное объявление всегда сохраняется.
Исполняемая матрица версий охватывает 0.0, 0.3, 0.10, 1.0, очень большие
канонические компоненты и некорректные записи с ведущими нулями.
Базовые ошибки соответствия ограничены §11 спецификации:
type — непустая строка YAML.index.md и log.md соответствуют своей зарезервированной структуре.Все группы полей v0.2 необязательны. Некорректная присутствующая группа даёт предупреждение строгой политики и никогда не блокирует загрузку в разрешающем режиме. Неизвестные ключи, типы понятий, среды выполнения и типы параметров остаются доступными для чтения.
Правила совместимости с v0.1 применяются при чтении и не выполняют неявную миграцию:
timestamp используется только при полном отсутствии generated;# Citations используется только при полном отсутствии sources.Присутствующее, но некорректное новое поле отключает соответствующее старое представление. Чтение, форматирование, индексирование и построение графа не переписывают исходные документы.
Разрешающая загрузка сохраняет повторяющиеся ключи отображения YAML вместо отказа в разборе всего документа. Посторонние повторы ключей, определённых автором документа, доступны через интерфейсы чтения исходного YAML без потерь. Повторяющийся стандартный ключ считается присутствующим, но семантически неразрешённым: типизированное чтение завершается отказом, а не выбирает одно значение. Повторяющиеся ключи новых групп полей также отключают старое представление.
Два исключения из §11 и правил зарезервированной структуры — повторяющийся
type понятия и повторяющийся корневой okf_version; валидатор сообщает о них
базовыми диагностическими сообщениями ERROR. Остальные повторяющиеся ключи
стандартных групп дают строгие сообщения WARNING с обычными путями полей этой
группы. Изменение без потерь отклоняет повтор только тогда, когда запрошенная
операция затрагивает неоднозначный путь или селектор; несвязанные повторы
сохраняются побайтово.
Эти решения являются политикой библиотеки, а не дополнениями к исходному OKF:
| Неоднозначность | Решение библиотеки |
|---|---|
Примеры sources[].author используют неопределённый team:* |
Проверять как непустую строку; не требовать соглашения об идентификаторах участников |
Грамматика и уникальность sources[].id не заданы |
Сохранять любую непустую строку; строгая проверка требует уникальности для сопоставления ссылок с источниками |
sources[].resource может описывать область данных |
Сохранять видимым и не навязывать интерпретацию как пути или URI |
Два зафиксированных документа объявляют 0.2, но различаются временными полями |
Явно выбирать date-3fcbb9f (по умолчанию) или instant-0b87c52; второй требует даты и времени RFC3339 со смещением и сравнивает точные моменты; без --as-of/as_of устаревание не оценивается и системные часы никогда не используются; см. ADR 0003 |
Значение usage_count |
Неотрицательный целочисленный сигнал, который никогда не является оценкой достоверности |
| Реестр сред выполнения и типов параметров | Произвольные строки; реестра нет |
| Наличие исполнителя и подтверждающего участника | Рекомендация строгой политики, а не базовое соответствие |
| Одновременное старое представление происхождения и представление v0.2 | Представление v0.2 имеет приоритет; неявное удаление повторов не выполняется |
| Метка источника выбора для канонической неподдерживаемой версии | Сохранять исходное объявление и использовать зафиксированную публичную метку future-best-effort для неподдерживаемых версий как старше, так и младше |
Длина идентификатора участника и символы : |
Проверять только группу участника и непустые компоненты; предметного ограничения длины нет, дополнительные : внутри идентификаторов human:/process: разрешены |
Ограждённый блок «под # Computation» |
Допустимое содержимое — один закрытый ограждённый блок, являющийся непосредственным узлом верхнего уровня AST внутри единственного раздела H1 верхнего уровня; соседний текст разрешён, а блоки внутри списков/цитат считаются цитируемым содержимым или примерами и делают содержимое конфликтующим, а не отсутствующим |
YAML relations |
Расширение skosovsky/okf, отсутствующее в исходной v0.2 |
Читатель, валидатор и граф не исполняют содержимое набора документов. Привязка
параметров, среда выполнения исполнителя, форматы передачи квитанций и вердиктов,
ABI подтверждающего участника, переносимость, изоляция выполнения и кэширование
подтверждений намеренно отложены. store.CommitReceipt не связан с executor.receipt.
fixtures/v02/corpus.yaml перечисляет общие тестовые примеры: минимальный v0.2,
приложение A, встроенные и файловые вычисления, отображение и список verified,
совместимость с v0.1, смешанные сведения о происхождении, будущие версии и
неблагоприятные случаи необязательных групп полей. fixtures/v02/legacy-inventory.yaml
— явный список разрешённых старых написаний в зафиксированной истории
спецификации и регрессионных примерах. Тесты пакетов и внешних интерфейсов должны
ссылаться на эти пути, а не копировать строки примеров.