Поверхность валидации
Aggrega проверяет написанное авторами содержимое на четырёх отдельных уровнях схем. Каждый уровень охватывает свою область, выполняется на своём этапе конвейера компиляции и выдаёт ошибки своей формы. Автору, столкнувшемуся с ошибкой валидации, полезно знать, какой уровень отклонил входные данные: одно и то же поле может регулироваться несколькими уровнями, и от того, какой уровень сработал, зависит, что и где исправлять.
На этой странице описаны четыре уровня, их место в конвейере, соглашение о форме ошибок, которому следует каждый уровень, и то, как уровни взаимодействуют, когда к одному полю применяется больше одного из них.
Четыре уровня
Уровень 1 — оболочка JSON Schema
Область. Структура каждого YAML-файла каталога: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, блок верхнего уровня spec: и обязательные для каждой сущности поля, которые объявляет схема. У каждого вида сущности (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) есть собственная JSON Schema, описанная в справочнике по схемам. Там же есть схема и для Workload — это единственный вид из этого набора, который автор пишет внутри другой сущности (в блоке workload: сущности Recipe или FeatureRecipe либо в записи WorkloadLibrary), а не как отдельный файл каталога; та же проверка оболочки применяется к нему везде, где он написан, а aggrega validate принимает файл Workload напрямую как цель из одной сущности.
Когда выполняется валидация. При разрешении (resolver / load), для каждого файла. Каждый документ при загрузке проверяется по JSON Schema своего вида; ключ вне полей, объявленных схемой, отклоняется на этом этапе, до любой дальнейшей валидации.
Форма ошибки. Несоответствие схеме сообщается как сбой оболочки документа. Его заголовок несёт категорию документа, в котором ошибка, — [CATALOG_ERROR E0215] для сущности каталога, [DEVELOPER_ERROR E0215] для Aggregate, [OPS_ERROR E0215] для Release, — а сообщение называет вид, файл, строку и столбец, путь к полю и нарушенное ограничение:
[CATALOG_ERROR E0215] <path> document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schemaПропуски обязательных полей и несоответствия типов выводятся в той же форме — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".
Уровень 2 — схемы опор (schema: / featuresSchema / usesSchema)
Область. Опоры данных, которые несёт сущность, — values, infra, parameters, а также блок подключений features:, слоты которого объявляет featuresSchema, и блок uses:, управляемый usesSchema. Сущности домена 2 (Component, Feature) встраивают объявления JSON Schema 2020-12 в свою YAML-оболочку (spec.schema inline — в компактной или полной форме — или $ref: на общую запись SchemaLibrary); сущности домена 3 (Recipe, FeatureRecipe) используют разрешённые схемы в собственном проходе валидации.
Когда выполняется валидация. При разрешении, после успешной проверки оболочки JSON Schema. Компилятор объединяет написанную автором schema: сущности с автоматически сгенерированными базами, выведенными из объявлений usesSchema и featuresSchema; объединённая схема проверяет предоставленные разработчиком блоки values: / infra: / features: / uses: каждого экземпляра компонента в Aggregate.
Вид ошибки. Нарушения ограничений выдаются как сообщения, называющие сущность, путь внутри опоры и правило, отклонившее значение, — например, если разработчик задаёт порт 80 при правиле схемы, требующем >=1024.
Повторно объявленная запись usesSchema или featuresSchema не вызывает ошибки объединения. Эти две поверхности накладываются по имени: запись потомка полностью заменяет запись базы, схема и селектор вместе, поэтому конфликта между записью базы и записью потомка, о котором следовало бы сообщить, нет.
Уровень 3 — возможность синтезированного режима Provider
Область. Определяется проверкой возможности синтезированного режима у привязанного провайдера:
- Поддержка синтезированного режима (
workload:) зависит от возможности привязанного провайдера, а не от наличияworkloadSchema: сущность Recipe сworkload:, привязанная к провайдеру, который не умеет синтезировать, отклоняется здесь. Каталог стандартной библиотеки по соглашению объявляетworkloadSchemaу провайдеров, способных к синтезу, — вspec.provider.workloadSchemaсущности Plugin, выполняющей рендеринг для провайдера, — как документированный контракт трансляции. Само телоworkloadSchemaкомпилируется в JSON Schema 2020-12 при загрузке Plugin — это структурная проверка приёмки, которая отклоняет некорректную схему при загрузке, а не при рендеринге.
Когда выполняется валидация. При базовом рендеринге, после разрешения собственного valuesMapping сущности Recipe. Уровень 3 пропускает диспетчеризацию синтезированного режима в зависимости от возможности провайдера.
Вид ошибки. Отказ по возможности относится к домену авторинга каталога, поэтому отчёт начинается с заголовка в квадратных скобках с этой категорией и экземпляром, в котором возникла ошибка. Сообщение начинается с фиксированного предложения, описывающего условие, затем называет узел, провайдера и виды, которые этот провайдер поддерживает:
[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesizedЗаголовок [CATALOG_ERROR] указывает, что ошибка в сущности каталога, а не в Aggregate разработчика. В терминале заголовок также содержит короткий код условия — E0265 для этого случая, который можно найти в таблице всех условий, — а сообщение переносится на отдельную строку с отступом; однострочная форма выше — это то, что попадает в журнал. Начальное предложение фиксировано для каждого условия, поэтому именно по нему следует выполнять сопоставление, когда вы работаете с текстом; всё, что следует за ним, зависит от проблемного узла.
Связанная защита охраняет саму диспетчеризацию провайдеров: если одну и ту же цель обслуживают несколько сущностей Plugin, выполняющих рендеринг для провайдера, рабочее пространство разрешает неоднозначность с помощью привязки провайдера в .aggrega-config.yaml, выбранной при aggrega pull и записанной в lock-файл. Если привязки нет и кандидат Plugin ровно один, используется он; если привязки нет и кандидатов несколько, сборка явно останавливается и называет плагины-кандидаты. Неоднозначность разрешается в каждом рабочем пространстве в точке использования, а не правилом уникальности на уровне всего каталога.
Валидация содержимого Workload для каждого провайдера.
spec.provider.workloadSchemaсущности Plugin, отрисовывающей провайдер, описывает, как провайдер преобразует Workload, и помечает провайдер как способный синтезировать его; она ничего не проверяет. Каждое тело Workload проверяется по схеме Workload платформы, каким бы ни был провайдер.
Уровень 4 — валидация значений привязок аннотаций
Область. Значения аннотаций, заданные на границах / граничных компонентах Release или в подсистемах / экземплярах компонентов Aggregate, когда привязка Manifest в mappings.features.annotations.<key> объявляет маршрутизацию через списки путей с точками maps.infra и/или maps.values. Каждый объявленный путь проходит по spec.schema.<pillar> целевой Feature до листового свойства; вклад значения аннотации в этот лист проверяется по типу, объявленному в схеме Feature. Валидация идёт через собственное объявление JSON Schema 2020-12 сущности Feature — привязки объявляют только маршрутизацию, а не фрагменты валидации.
Когда выполняется валидация. На подфазе раскрытия аннотаций при разрешении, после проверки целей привязок Manifest (проверки при загрузке каталога, подтверждающей, что каждый объявленный путь существует в указанной схеме Feature) и параллельно с валидацией схем уровня 2 для явных подключений. Для каждой действующей аннотации компонента: значение разбирается как скаляр, структурированный словарь или явный null; каждый подключ маршрутизируется через сгруппированное по опорам объявление maps привязки с проверкой соответствия стороны и опоры (сторона Aggregate задействует maps.values; сторона Release задействует maps.infra); значение времени выполнения для каждого листа проверяется по типу, объявленному в схеме Feature в целевой опоре. Ошибки нескольких подключей собираются и выводятся все до остановки.
Вид ошибки. Ошибки валидации схемы на этом уровне имеют вид уровня 2 — сущность, путь (ключ аннотации плюс маршрут подключа), подробности ограничения. Нарушения разделения сторон и опор и ошибки неоднозначной маршрутизации относятся к документу, в котором задано значение аннотации, поэтому ошибка в Aggregate начинается с заголовка [DEVELOPER_ERROR], а ошибка в Release — с заголовка [OPS_ERROR]; обе называют ключ аннотации, целевую опору, сторону авторинга и место в исходном файле.
Единое соглашение о форматировании ошибок для всех уровней
Все четыре уровня следуют одному наблюдаемому соглашению: каждый сбой валидации, относимый к Aggrega, имеет форму «путь плюс обоснование», которая называет проблемное поле и ограничение, отклонившее его значение.
- Ошибки уровня 1 (оболочка) и уровня 2 (схемы опор) начинаются с одного и того же заголовка в квадратных скобках — категории документа, в котором ошибка, и короткого кода условия, например
[CATALOG_ERROR E0215]для несоответствия оболочки в сущности каталога и[DEVELOPER_ERROR E0168]для значения Aggregate, которое отклоняет схема опоры, — за которым следуют путь к полю и нарушенное правило схемы. - Ошибки уровня 3 (источник Provider / Workload) по определению относятся к сущности каталога: схему, отклонившую ввод разработчика, написала пара Recipe + Provider. Они относятся к домену авторинга каталога, и эта принадлежность доходит до вас в заголовке диагностики в квадратных скобках, а не в виде слова в тексте сообщения: отчёт об остановке начинается с
[CATALOG_ERROR E0nnn], где категория называет домен, а короткий код — условие. Сопоставляйте по короткому коду: после выдачи он не меняется. - Ошибки уровня 4 (валидация значений привязок аннотаций) имеют ту же форму, что и на уровне 2: валидирующая схема Feature находится в
spec.schemaуказанной сущности Feature, а значения времени выполнения проходят через маршрутизациюmapsпривязки Manifest в эту схему для проверки типа на каждом листе.
Полный перечень сигнальных ошибок с префиксом Aggrega и мест, где они возникают, см. в errors/error-translation.md. Каталог ошибок по отдельности (правила формы Recipe для [CATALOG_ERROR], условие за условием) см. в errors/fatal-halts.md.
Взаимодействие слоёв при перекрытии полей
Одно и то же написанное поле может регулироваться более чем одним уровнем. containers.<name>.ports.<port> в Workload проверяется уровнем 1 как часть структуры схемы Workload; уровень 2 до него не доходит, поскольку содержимое Workload — это внутренняя структура Recipe, а не опора Component; а workloadSchema провайдера ничего не проверяет — поэтому ограничение вроде запрета порта ниже 1024 следует помещать в схему Component или в утверждение, где его назовёт сработавший уровень.
Сводка размещения в конвейере
| Уровень | Область действия | Когда выполняется | Префикс ошибки |
|---|---|---|---|
| 1 — оболочка JSON Schema | Структурная форма (apiVersion, kind, metadata, spec верхнего уровня) | Разрешение (загрузка) | категория документа с E0215 — [CATALOG_ERROR E0215] для сущности каталога |
2 — схемы столпов (schema: / featuresSchema / usesSchema) | Валидация данных по каждому столпу (values, infra, secrets, uses) | Разрешение (после оболочки) | категория документа-источника с коротким кодом условия — [DEVELOPER_ERROR E0168] для значения Aggregate |
| 3 — шлюз возможностей Provider | Поддержка синтезированного режима (возможность провайдера) | Базовый рендеринг | [CATALOG_ERROR] |
| 4 — валидация значений привязок аннотаций | Вклады значений аннотаций, направляемые в spec.schema целевой сущности Feature через пути maps привязки сущности Manifest | Подфаза раскрытия аннотаций в ходе разрешения, наряду с уровнем 2 | ошибка валидации схемы; проверки «сторона или столп» и неоднозначной маршрутизации относятся к домену самого авторского документа — [DEVELOPER_ERROR] для сущности Aggregate, [OPS_ERROR] для сущности Release |
Перекрёстные ссылки
errors/error-translation.md— перечень сигнальных ошибок с префиксом Aggrega и поверхностей, которые их порождают.errors/fatal-halts.md— каталог всех фатальных остановок, которые выдаёт компилятор, по отдельным ошибкам.vocabulary/data-pillars.md— столпы данных (values,infra,parameters,locals,features:,uses:иprovides), которые проверяет уровень 2.entities/component.md— поверхность создания сущности Component дляschema:/featuresSchema/usesSchema.entities/plugin.md— поверхность создания сущности Plugin для рендеринга провайдера дляspec.provider.workloadSchema.entities/manifest.md— поверхность привязкиfeatures.annotationsсущности Manifest (уровень 4).providers/well-known-annotations.md— разбор значений аннотаций, маршрутизация подключей структурированных значений, отказ через null для отдельного подключа и межсторонняя композиция, которые проверяет уровень 4.