Что такое стандарт
Эта глава объясняет, что такое стандарт Framework и в какой единой форме записан каждый стандарт.
Что такое стандарт
Стандарт — записанный набор требований, который отвечает на вопрос «что обязано быть правдой», а не «как это написано». Стандарт позволяет компоненту, приложению и проверке опираться на одни и те же требования и сверять соответствие однозначно.
Что входит в стандарт
В стандарт входят только требования, которые не зависят от реализации: «два экземпляра на странице не делят идентификаторы», «изменение несёт ревизию», «прежнее имя уходит по календарю».
В стандарт не входят имена событий, CSS-классы, ширины колонок и другие детали конкретного компонента — это документация компонента.
Правило размера: стандарт Framework содержит от 15 до 20 требований, и проверка Framework следит за этой рамкой. Если требований больше, в стандарт попали детали реализации.
Чем стандарт отличается от остальной документации
- Изданный стандарт неизменен. Опубликованные байты не правятся. Поправка выходит новой версией, а прежняя остаётся доступной.
- Стандарт закрепляется по хешу. Тот, кто опирается на стандарт, называет не адрес, а версию и sha256 точных байтов.
- У стандарта две формы. Страница для людей в документации и конверт
для программ — JSON-файл в формате
standard-contract. Сайт документации публикует конверты по адресу/ai/standards/<id>/<версия>/standard.json. Источник истины — исходники Framework (contracts/standards/); при расхождении верны их байты.
Кто доказывает соответствие
Стандарт сам соответствие не доказывает. Соответствие доказывают конкретные компоненты и приложения — проверками или явным разбором каждого требования.
Смотрите также
- Форма стандарта: Standard Contract — форма, в которой записан каждый стандарт.
- Карта стандартов — карта стандартов Framework.
- Жизненный цикл изменений и совместимость — как прежние имена уходят из Framework.
Форма стандарта: Standard Contract
Standard Contract (standard-contract) — единая форма, в которой записаны все стандарты
Framework. Одна форма позволяет одной проверке читать любой стандарт и
однозначно сверять его поля, требования и опоры.
Форму задаёт и ведёт проект AI First. Framework хранит закреплённую копию её
схемы (contracts/standards/standard-contract-1.0.schema.json) и записывает,
из какой ревизии и с каким хешем копия получена. Поэтому проверка стандартов
Framework не зависит от внешнего репозитория. Сайт документации публикует ту
же схему: /ai/standards/standard-contract/1.0.0/standard.schema.json.
Конверт
Стандарт — это файл-конверт. Обязательные поля:
| Поле | Что содержит |
|---|---|
format, formatVersion |
Имя формы — всегда standard-contract — и её версия |
id |
Идентификатор, например simai.composite-component |
version |
Полная версия стандарта: <старшая>.<младшая>.<исправление> |
title |
Название |
appliesTo |
К чему применяется: simai.framework.component, simai.framework.composite-component и т. п. |
requirements |
Список требований |
Необязательные поля:
extends,uses,references— связи с другими контрактами (Связи между стандартами);specification— ссылка на схему самой формы;extensions— сведения о владельце и об издании.
Файл обязательно лежит по пути, который совпадает с его идентификатором и
версией: contracts/standards/<id>/<version>/standard.json.
Требование и его уровень
У каждого требования есть идентификатор, уровень, текст и способ проверки. Пример требования:
{
"id": "mutation-carries-revision",
"level": "must",
"text": "Every mutation carries the revision the client last saw…",
"verification": "manual"
}
Уровни требований:
| Уровень | По-русски | Что означает |
|---|---|---|
must |
обязательно | Нарушение делает компонент несоответствующим |
should |
следует | Отступить можно, но причину нужно записать в документации компонента |
may |
можно | Разрешённая возможность, а не обязанность |
Способы проверки:
manual— соответствие показывает автор: он называет, чем выполнено требование;equals— машинная проверка: свойствоpropertyдолжно иметь значениеvalue. Так записывается только обязательное требование.
Поле guidance подсказывает, где требование держится в коде, например
«Framework: held by tests/change-lifecycle.contract.test.mjs».
Связи между стандартами
| Связь | Смысл | Обязательства |
|---|---|---|
extends |
Наследование | Все требования родителя действуют в наследнике; отменить или повторить их нельзя |
uses |
Опора на другой контракт (схему, политику, грамматику) | Требования не наследуются, но байты закреплены |
references |
Справочный материал | Никаких |
Правила ссылок:
- ссылка в
extendsобязана содержать путь и sha256; - в
usesиreferencesпуть необязателен, но если он указан, рядом обязан стоять хеш: ссылка на локальный файл без хеша не принимается.
Закрепление по хешу
Главное правило формы: потребитель закрепляет стандарт локальной копией с путём и sha256. Ссылка только по адресу оставляет нормативный контекст неполным: по тому же адресу позже могут лежать другие байты.
Framework дополняет это правило тремя своими:
- Живой стандарт закрепляет только замороженные копии. Опоры лежат в
contracts/standards/pinned/, а не в рабочих файлах. Иначе следующее изменение рабочей схемы сделало бы изданный стандарт недействительным. - Закреплённая версия совпадает с версией, которую объявляет сам файл.
Схемы несут
x-simai-version, lock-файлы —version. Проверка отклоняет закрепление, при котором один номер версии означал бы два разных файла. - История хранит изданные байты. Заменённое издание остаётся в
contracts/standards/history/<id>/<version>/standard.json, поэтому потребитель, который его закрепил, остаётся корректным.
Следствие: версия стандарта меняется и тогда, когда текст требований не изменился, а изменились только закреплённые байты опоры.
Как форма проверяется
Проверка tests/standards.contract.test.mjs входит в гейт владельца (Гейт владельца).
Она читает каждый конверт и проверяет:
- соответствие закреплённой копии схемы и отсутствие лишних полей;
- что файл лежит по своему идентификатору и версии;
- уникальность идентификаторов требований и допустимость уровней;
- рамку в 15–20 требований;
- хеш каждого закреплённого файла — пересчитывая его по байтам;
- что наследник применяется только к тем видам, что и родитель, и не повторяет унаследованные требования;
- что живой стандарт закрепляет только файлы из
pinned/, а история хранит изданные версии; - что происхождение копии схемы записано.
Смотрите также
- Что такое стандарт — что такое стандарт.
- Карта стандартов — какие стандарты записаны в этой форме.
- Гейт владельца — гейт владельца, в который входит проверка формы.