Написание в компактной форме
Компактная форма — это декларативная сокращённая запись для JSON Schema 2020-12 в виде YAML. Авторы записывают ограничения для каждого поля как встроенные flow-словари YAML (port: { type: integer, min: 1, max: 65535, default: 8080 }); промежуточные узлы-объекты задаются обычной вложенностью YAML; ссылки используют стандартный для JSON Schema $ref:. Компилятор преобразует компактную форму в JSON Schema 2020-12 до запуска любой валидации, поэтому валидация, отчёты об ошибках и любой инструмент, читающий схему, работают с разрешённой JSON Schema, в какой бы форме она ни была написана.
На этой странице описаны словарь компактной формы, структурные соглашения, выбор между выводимой и явной формой объекта, семантика замыкания, неоднородность type:, допускающая массивы разрешённых типов, ключевые слова, зарезервированные в каждой области выводимой формы, и пространство имён расширений x-aggrega-*. Семантика разрешения междокументных ссылок $ref: описана в cross-document-ref.md. Грамматика написания блока assertions описана в templates/assertions-block.md. Набор опор данных (values:, infra:, provides:, uses:, features:, locals:, parameters:) описан в data-pillars.md.
Компактная форма — основной способ написания для schema:, parameters: и записей SchemaLibrary. JSON Schema в YAML — равноправный вариант написания; обе формы полноценны и могут сочетаться в одной схеме. Обе формы компилируются в один и тот же разрешённый документ JSON Schema; последующие инструменты и валидация не зависят от способа написания.
Словарь
Ключевые слова компактной формы — те, что приведены в таблицах ниже. Авторы изучают их один раз и применяют в schema:, parameters: и записях SchemaLibrary.
Ключевые слова типа и идентичности
| Ключевое слово | Значение | Компилируется в JSON Schema |
|---|---|---|
type | Тип поля (string, integer, number, boolean, object, array или массив допустимых типов) | type: |
description | Документация для человека | description: |
default | Значение по умолчанию, если поле отсутствует | default: |
required | Маркер на уровне листа (required: true) для полей, которые должны присутствовать | Добавляет имя поля в массив required: родителя |
Ключевые слова ограничений
| Ключевое слово | Значение | Компилируется в JSON Schema |
|---|---|---|
enum | Допустимые значения (список) | enum: |
const | Единственное допустимое значение — скаляр, словарь или список | const: |
min | Минимальное значение (число) или минимальная длина (строка/массив) | minimum: (число); minLength: (строка); minItems: (массив) — выбирается по type: |
max | Максимальное значение или длина, аналогично min | maximum: / maxLength: / maxItems: |
minLength / maxLength | Явные ограничения длины строки | Прямое отображение в minLength: / maxLength: (используйте, когда min/max были бы неоднозначны) |
pattern | Шаблон регулярного выражения для строк | pattern: |
format | Именованный формат, которому должна соответствовать строка, — один из email, uri, hostname, ipv4, ipv6, uuid, date-time, date (см. Именованные форматы) | format: |
В блоке parameters: сущности Aggregate некоторые из них проверяются и в самом объявлении, до чтения любого значения сущности Release. Собственные minLength и maxLength параметра равны нулю или больше — отрицательное значение отклоняется при загрузке сущности Aggregate, — а каждый pattern, включая находящийся во вложенном контракте items, properties или valuesType, должен быть компилируемым регулярным выражением, поскольку шаблон компилируется при чтении контракта параметра. Каждый format на любой глубине должен быть одним из именованных форматов ниже. min или max у параметра типа boolean или object также отклоняется, поскольку на этих типах эта пара ничего не ограничивает. Каждая ошибка останавливает сборку с указанием параметра, независимо от того, передаёт ли его сущность Release. Граница длины внутри вложенного контракта этому нижнему пределу не подчиняется; где выполняется каждая проверка, см. в entities/aggregate.md.
Именованные форматы
format задаёт форму, которую должно иметь строковое значение. Имена — те, что определяет спецификация JSON Schema, в её написании, и каждое проверяет то, что оно означает по спецификации:
| Имя | Соответствующее значение — | Определено в |
|---|---|---|
email | почтовый ящик: локальная часть (атомы через точку или строка в кавычках), @, затем домен или литерал адреса в квадратных скобках — ops@example.com. Отображаемое имя, например Joe <joe@example.com>, почтовым ящиком не является | RFC 5321, раздел 4.1.2 (Mailbox) |
uri | абсолютный URI: схема, :, затем остальная часть, где любой символ вне алфавита URI закодирован процентами — https://example.com/a%20b, s3://bucket/key. Относительная ссылка, например /path, им не является | RFC 3986 (URI) |
hostname | имя хоста: метки из букв, цифр и дефисов через точку, каждая длиной 1–63 символа, не начинающаяся и не заканчивающаяся дефисом, всего не более 253 символов — db-primary.data.svc.cluster.local. Метка Punycode (xn--…) принимается как есть; подстановочный знак *, подчёркивание или завершающая точка — нет | RFC 1123, раздел 2.1 |
ipv4 | четыре десятичных числа от 0 до 255, разделённые точками, — 192.0.2.1 | RFC 2673, раздел 3.2 (dotted-quad) |
ipv6 | адрес IPv6 в любой из его текстовых форм — полной, сокращённой с :: или оканчивающейся адресом IPv4, — 2001:db8::1. Зона (%eth0) или длина префикса (/64) не входит в адрес | RFC 4291, раздел 2.2 |
uuid | 32 шестнадцатеричные цифры в группах 8-4-4-4-12, разделённых дефисами, в любом регистре — 2eb8aa08-aa98-11ea-b4aa-73b441d16380 | RFC 4122, раздел 3 |
date-time | метка времени со смещением — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00, — с днём, существующим в своём месяце, и високосной секундой только в 23:59 UTC | RFC 3339, раздел 5.6 (date-time) |
date | календарная дата — 2026-09-28, — день которой существует в её месяце и году | RFC 3339, раздел 5.6 (full-date) |
Формат оценивает только строку: значение другого типа оценивает его type. И он оценивает лишь синтаксис значения — имя хоста никогда не разрешается, URI никогда не загружается, с почтовым ящиком никто не связывается, — поэтому проверка даёт одинаковый результат при каждой сборке и не требует сети.
Проверка выполняется везде, где значение валидируется по своей схеме: в parameters: сущности Aggregate, в values и infra, которые ограничивают столпы schema: сущности Component или Feature, в values и infra на уровне ребра, которые ограничивают схемы полезной нагрузки сокета usesSchema:, и в каждой записи SchemaLibrary, до которой доходят эти схемы. Имена форматов столпа provides оцениваются при загрузке каталога, как и у любой другой схемы; значения, публикуемые сущностью Recipe, по столпу не валидируются, поэтому формат для них не проверяется. Внутри allOf, anyOf, oneOf и not значение, не прошедшее проверку формата, не проходит эту ветвь — так же, как значение, не прошедшее любое другое ограничение. Несоответствующее значение отклоняется с указанием поля, значения и формата.
Имя вне таблицы отклоняется при загрузке схемы, независимо от того, доходит ли до него какое-либо значение, и в отказе перечисляются поддерживаемые имена — поэтому опечатка вроде emial становится диагностикой, а не ограничением, которое ничего не проверяет. Для записи SchemaLibrary запустите aggrega validate по всему каталогу, чтобы увидеть ошибочное имя: сущность Release, схемы которой доходят до записи, тоже отклоняется, но сообщает, что библиотека не найдена. password не является форматом: поле с секретными данными вместо этого объявляет sensitive: true.
Для форм, достигаемых косвенно, действует одно ограничение. Если форма поля приходит через $ref:, рядом с которым стоят другие ключевые слова (например, отображение properties:), через then: или else: ключевого слова when: или через указатель на объявленное свойство, её format проверяется на полях, которые форма объявляет напрямую и через allOf, — но не внутри ветви anyOf, oneOf, not или условной ветви в этой форме.
Ключевые слова композиции и ссылок
| Ключевое слово | Значение | Компилируется в JSON Schema |
|---|---|---|
$ref | Ссылка на фрагмент JSON Pointer или внешнюю запись SchemaLibrary | $ref: |
allOf / anyOf / oneOf | Композиция JSON Schema | Те же ключевые слова |
patternProperties | Отображение с ключами-регулярными выражениями | То же ключевое слово |
valuesType | Сокращение для отображений с типизированными значениями (например, «объект, все значения которого — строки») | additionalProperties: { type: <X> } |
Ключевые слова контейнеров
| Ключевое слово | Значение | Компилируется в JSON Schema |
|---|---|---|
items | Форма элемента массива | items: (рекурсивная компактная форма или JSON Schema) |
properties | Явное объявление дочерних элементов (требуется редко; обычно неявно через структуру YAML) | properties: |
additionalProperties | Разрешены ли необъявленные свойства (false на объекте выводимой формы, где его добавляет компилятор; на явном type: object его пишете вы сами, а там, где вы его не пишете, действует собственное значение JSON Schema по умолчанию — true) | additionalProperties: |
Ключевые слова, специфичные для Aggrega
| Ключевое слово | Значение |
|---|---|
validate | Предикат шаблона Go на уровне поля, возвращающий логическое значение; false останавливает валидацию с validateMessage: |
validateMessage | Сообщение об ошибке, сопровождающее сбой validate: |
when | Условное применение поддерева; предикат шаблона Go, определяющий, применяются ли ограничения узла |
sensitive | Объявляет, что этот лист содержит секретные данные. Компилируется в x-aggrega-sensitive: true. См. «Объявление листа чувствительным» ниже |
$jsonschema | Запасной выход — встроенный полный поддокумент JSON Schema в этом узле |
$mode | Необязательная аннотация выбора для неоднозначных случаев (требуется редко; см. «Выводимая и явная объектная форма» ниже) |
Заимствованные ключевые слова JSON Schema ($ref, allOf, format и т. д.) используют тот же синтаксис, что и JSON Schema, поэтому авторы, уже знающие JSON Schema, сразу их узнают.
Ключевое слово, значение которого является данными, несёт это значение в том виде, в каком оно записано. Словарь или список, заданный для default, enum или const, — это само значение, а не вложенная схема: endpoint: { type: object, default: { host: db, port: 5432 } } задаёт этот объект как значение endpoint по умолчанию, а mode: { type: object, const: { kind: fast } } допускает ровно этот объект — как и mode: { const: { kind: fast } }, поскольку const, как и enum, сам по себе делает узел листом. То же самое действует внутри запасного выхода $jsonschema:.
Как устроен лист в компактной форме
Единица описания — листовой узел: поле со словарём ограничений:
field_name: { type: <type>, ...constraints... }Типичные шаблоны:
port: { type: integer, default: 8080 }port: { type: integer, min: 1, max: 65535, default: 8080 }identifier: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$" }log_level: { type: string, enum: [debug, info, warn, error], default: info }name: { type: string, minLength: 1, required: true }email: { type: string, format: email }enabled: { type: boolean, default: false }Каждый лист занимает одну строку. Словарь ограничений описывает всё, что касается формы поля; структура родительского узла задаёт расположение поля.
Вложенные объекты
Структура объектов повторяет вложенность YAML. Глубокая вложенность работает напрямую, и каждый лист по-прежнему занимает одну строку:
spec: schema: architecture: { type: string, enum: [standalone, replication], default: standalone } primary: replicaCount: { type: integer, min: 1, max: 9, default: 1 } resources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "250m" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "512Mi" } limits: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "500m" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "1Gi" } auth: username: { type: string, default: app_user } password: { type: string, sensitive: true }Компилятор выводит структуру объектов из иерархии YAML. Промежуточные узлы (здесь: primary, resources, requests, limits, auth) являются объектными типами, содержащими вложенные дочерние элементы. Компилятор генерирует явные блоки type: object и properties: в разрешённой JSON Schema; автору не нужно их писать.
Выводимая и явная форма объекта
Область объекта в компактной форме можно описать двумя способами:
Выводимая форма — дочерние элементы находятся непосредственно под родительским ключом, без объявления type: object:
auth: username: { type: string, default: app_user } password: { type: string, sensitive: true, required: true }Компилятор распознаёт область как объект, поскольку её дочерние элементы являются объявлениями свойств. Он генерирует type: object, properties: { ... } и автоматически добавляет additionalProperties: false во время компиляции. Семантика закрытости входит в контракт выводимой формы: опечатки в полях, написанных разработчиком, приводят к явной ошибке.
Явная форма — объявлен type: object, перечислены properties::
auth: type: object properties: username: { type: string, default: app_user } password: { type: string, sensitive: true } required: [password] additionalProperties: true # genuinely-open map authored on purposeВ явной форме компилятор НЕ добавляет additionalProperties: false. Авторы, объявляющие type: object, несут полную ответственность за решение о закрытости; явная форма предназначена для действительно открытых отображений (additionalProperties: true) и для объектов, которым нужны другие ключевые слова JSON Schema (patternProperties, propertyNames, unevaluatedProperties).
Критерий выбора: используйте выводимую форму для обычных закрытых объектов (типичный случай в схемах каталога). Используйте явную форму, когда объект должен быть действительно открытым или когда схеме нужны ключевые слова JSON Schema, которые компактная форма напрямую не поддерживает.
Семантика замкнутости
По соглашению объекты компактной формы в выводимой форме замкнуты: необъявленные свойства вызывают ошибку валидации. Компилятор автоматически выдаёт additionalProperties: false для каждой области объекта в выводимой форме. Это соответствует дисциплине каталогов, при которой опечатки приводят к явной ошибке.
Чтобы открыть объект (разрешив произвольные дополнительные свойства), используйте явную форму с additionalProperties: true:
labels: type: object additionalProperties: true # opt-in; allow any string-keyed valuesДля распространённого шаблона «объект, все значения которого имеют один тип» (например, отображение string → string для меток) используйте valuesType::
labels: { type: object, valuesType: string }nodeSelector: { type: object, valuesType: string }counters: { type: object, valuesType: integer }valuesType: <type> компилируется в additionalProperties: { type: <type> }. Этот шаблон встречается достаточно часто, чтобы заслуживать сокращения из одного ключевого слова.
Указанное выше голое имя типа — это написание для schema: и SchemaLibrary. В слоте parameters: сущности Aggregate вместо этого записывайте значение как контракт — valuesType: { type: string }. То же относится к двум другим ключевым словам, значение которых само является контрактом, — items: и каждой записи в properties:, поскольку объявление параметра и каждый вложенный в него контракт имеют одну форму. Голое имя типа в любой из этих трёх позиций в слоте параметра отклоняется, и диагностика указывает, в каком вложенном контракте оно находилось. Полный словарь слотов параметров см. в entities/aggregate.md.
Обязательные поля
Обязательные поля задаются через required: true для каждого листа:
auth: username: { type: string, default: app_user } password: { type: string, sensitive: true, required: true } database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }Компилятор собирает все маркеры required: true в пределах области объекта и выдаёт их как массив required: [field1, field2] JSON Schema. Маркер учитывается, где бы ни было объявлено свойство: в области выводимой формы и у свойства внутри явного блока properties:.
Потребитель, который подключает запись SchemaLibrary в свою схему через $ref:, может указать свои обязательные поля любым из двух способов — массивом required: [name1, name2] на уровне родителя рядом со ссылкой или маркером required: true у свойства, которое он объявляет там под properties:. Полное правило см. в cross-document-ref.md, §«Синтаксис required: при междокументном $ref:».
Массивы
Массивы задаются через type: array, а items: описывает форму элемента:
tags: { type: array, items: { type: string } }
ports: { type: array, items: { type: integer, min: 1, max: 65535 } }
extraEnvVars: type: array items: name: { type: string, required: true } value: { type: string } valueFrom: { type: object, additionalProperties: true }
allowedHosts: type: array min: 1 # minItems max: 100 # maxItems items: { type: string, format: hostname }Для распространённого случая «массив типизированных скаляров» встроенная форма занимает одну строку. Для массивов объектов items: вводит вложенную схему в компактной форме.
Ключевое слово type: — скаляр или массив типов
type: принимает либо одно значение (type: string), либо массив допустимых типов (type: [string, integer, boolean]). Форма массива — стандартный в JSON Schema 2020-12 способ выразить «это поле принимает один из нескольких типов»:
release_tier: { type: [string, integer], description: "Numeric tier or named tag" }Когда type: содержит массив, пространство значений является объединением пространств значений перечисленных типов. Авторы схем, использующих форму массива, должны обрабатывать обе формы на последующих этапах: поле type итоговой JSON Schema содержит либо строку, либо массив, и потребители, обходящие итоговую схему, проверяют обе формы.
Зарезервированные ключевые слова в каждой области выводимой формы
Диспетчеризация выводимой формы распознаёт небольшой набор ключевых слов, которые имеют значение на уровне словаря компактной формы: description, type, default, required, ключевые слова ограничений (enum, const, min, max, pattern, format и т. д.) и ключевые слова, специфичные для Aggrega (validate, validateMessage, when, sensitive). Когда любое из этих ключевых слов встречается как имя поля в области объекта выводимой формы, компилятор читает охватывающую область как лист-ограничение, а не как объект: ключевое слово воспринимается как ограничение, а не как дочернее свойство, и каждый другой ключ в этой области тогда тоже должен быть ключевым словом, поэтому первый ключ, который им не является, отклоняется как неизвестное ключевое слово.
sensitive заслуживает здесь отдельного упоминания, поскольку это гораздо более правдоподобное имя для реального поля, написанного разработчиком, чем другие ключевые слова, специфичные для Aggrega. Схема, которой действительно нужно свойство с именем sensitive — например, компонент, чьи values предоставляют собственный флаг sensitive, — должна явно объявить охватывающую область, точно так же, как для свойства с именем type или default. Этого можно добиться либо явной формой, приведённой ниже, либо указанием $mode: jsonschema в охватывающей области: при $mode: jsonschema весь узел читается как написанная вручную JSON Schema, где sensitive — обычное содержимое, а не ключевое слово компактной формы.
Для схем, которым нужно свойство, названное так же, как зарезервированное ключевое слово (например, контракт Component с написанным разработчиком полем description:, полем type: или полем default:), используйте явную форму для проблемной области:
spec: schema: values: type: object properties: description: { type: string } # property named "description" type: { type: string } # property named "type" default: { type: string } # property named "default" required: [description, type] additionalProperties: falseЯвная форма обходит диспетчеризацию — properties: явно перечисляет дочерние элементы, поэтому конфликт с ключевым словом не возникает.
Это ограничение действует в каждой области выводимой формы, рекурсивно. Вложенный объект выводимой формы, содержащий свойство, названное так же, как зарезервированное ключевое слово, читается в этой области как лист-ограничение. Исправление то же самое: переведите проблемную область в явную форму.
Ссылки
Ссылки заимствуют $ref: из JSON Schema как синтаксически, так и семантически:
resources: { $ref: "#/$defs/PodResources" }
auth: { $ref: "Datastores#/schemas/MariaDBAuth" }
secondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 }Блоки $defs: внутри схемы в компактной форме объявляют повторно используемые определения. Каждая запись сама является схемой в компактной форме (или JSON Schema, или смешанной). Ссылаться на определение можно через фрагмент JSON Pointer #/$defs/<Name>:
Объявляйте блок внутри столпа, поля которого на него ссылаются, рядом с этими полями, а не рядом со столпом. Блок schema: принимает на своём верхнем уровне только три имени столпов данных, поэтому $defs:, записанный на одном уровне с values:, отклоняется при загрузке сущности с указанием ошибочного ключа и набора столпов, которые блок может содержать. Указатель в любом случае записывается как #/$defs/<Name>.
$defs: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" } limits: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
primary: replicaCount: { type: integer, min: 1, max: 9, default: 1 } resources: { $ref: "#/$defs/PodResources" }О межд документных ссылках на записи SchemaLibrary см. cross-document-ref.md. О раскрытии сокращённой записи OCI URI см. uri-grammar.md.
Направляйте ссылку на определение, а не на свойство
Указатель на запись $defs:, например #/$defs/PodResources, — это предпочтительная форма. Указатель
допустим везде, где его допускает JSON Schema, поэтому указатель на объявленное свойство тоже принимается и применяется,
но ошибки по нему сообщаются менее точно, и эту разницу стоит знать, прежде чем его писать.
Поле, форма которого берётся из записи $defs:, проверяется поле за полем: ошибка сообщается по
пути того значения, которое действительно неверно, и сообщаются все ошибки внутри этого поля, а не
только первая.
$defs: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
primary: resources: { $ref: "#/$defs/PodResources" }Неверное значение cpu здесь сообщается по пути primary.resources.requests.cpu.
Поле, форма которого берётся из указателя на объявленное свойство, проверяется в составе документа целиком. Ограничения по-прежнему действуют, и документ, нарушающий их, по-прежнему останавливает компиляцию, — но ошибка сообщается по полю, несущему указатель, а не по значению внутри него, а если неверны сразу несколько таких полей, называется только одно из них.
primary: resources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
secondary: resources: { $ref: "#/properties/primary/properties/resources" }Неверное значение cpu внутри secondary сообщается по пути secondary.resources.
Оба способа записи принимают и отклоняют одни и те же документы, за исключением одного ограничения для format, описанного в разделе
Именованные форматы: при использовании указателя format внутри ветви anyOf, oneOf или not
формы не проверяется. В остальном различается лишь то, насколько много сообщает
сообщение об ошибке, что важнее всего в редакторе, где маркер ставится по этому пути. То же
относится к записи $defs:, собственный указатель которой ведёт обратно в свойства: обращение к
определению через неё наследует менее точное сообщение.
Условная форма через when:
В JSON Schema 2020-12 условная форма выражается через if/then/else. Компактная форма предоставляет when: как более прямое сокращение: предикат шаблона Go, который, если он истинен, применяет остальные ограничения узла; если он ложен, узел обрабатывается так, как будто его ограничений не существует.
secondary: $ref: "#/$defs/NodePool" when: '{{ eq $.architecture "replication" }}' required: true properties: replicaCount: { type: integer, min: 2 }Предикат вычисляется по значениям экземпляра родителя. $ ссылается на область видимости окружающего объекта. Когда architecture равно replication, ограничения (required: true и дополнительное replicaCount: min: 2) применяются поверх ссылочного NodePool. Когда architecture равно standalone, эти ограничения неактивны.
Предикату доступны стандартные функции шаблонов Go (Sprig). Компилятор компилирует when: в if/then/else из JSON Schema с обёрткой, которая вычисляет предикат шаблона Go до запуска валидации. Детерминированность сохраняется, поскольку предикат является чистым по отношению к экземпляру.
Пользовательская проверка отдельного поля с помощью validate: и validateMessage:
Некоторые ограничения нельзя выразить с помощью min / max / pattern / enum. Для них компактная форма предоставляет validate: — предикат шаблона Go, который, если он ложен, останавливает проверку с пользовательской ошибкой.
db_size: type: string pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$" validate: '{{ regexFind "^[0-9]+" . | atoi | lt 100 }}' validateMessage: "db_size must exceed 100 in its declared unit"Предикат вычисляется по значению поля (доступному как .); окружающая область видимости объекта — $. Если предикат возвращает false, проверка выдаёт ошибку с текстом из validateMessage: (или сообщение по умолчанию, если он не задан).
validate: охватывает случаи, выходящие за рамки стандартного словаря JSON Schema: пользовательскую семантическую проверку (проверку формата semver, JSON-содержимого строки), межполевые правила с узкой областью действия, где ограничение одного поля зависит от соседнего, и ограничения, ради которых не стоит заводить полный блок assertions:.
validate: отличается от when: ролью: when: включает или выключает применение ограничений, а validate: сам является ограничением.
Для действительно межполевых правил с широкой областью действия, где ни одно поле не является «проверяемым», используйте специальный блок assertions:. См. templates/assertions-block.md.
Объявление листа чувствительным — sensitive:
Лист values, infra или provides может объявить, что описываемые им данные содержат секретный материал:
spec: schema: values: origin: type: string required: true sensitive: true description: "The credential material itself." key: type: string default: value description: "The data key the material is stored under."sensitive: true компилируется в ключевое слово расширения x-aggrega-sensitive: true на этом узле в разрешённой JSON Schema, наряду с другими аннотациями x-aggrega-*. Компилятор читает его, чтобы вывести, какие присоединения в развёртывании обрабатывают материал, объявленный чувствительным, и переносит этот выведенный факт в скомпилированный граф.
Объявляйте его на данных, а не на их локаторе. В этом различии весь смысл ключевого слова, и его легко перепутать. Чувствителен материал учётных данных; имя ресурса, который его хранит, и ключ данных внутри этого ресурса — нет: оба публичны, и оба выводятся в открытом виде в каждого потребителя, ссылающегося на ресурс. Пометка локатора утверждает о нём неправду и распространяет эту ошибку на всё, что ниже по цепочке читает объявление. В примере выше origin помечен, а key намеренно нет.
Дополняющее утверждение — всё, что привязывается к этой точке, обрабатывает секретный материал, независимо от того, что заполнение объявляет о собственных листьях, — вовсе не является объявлением листа. Это sensitive на слоте присоединения; см. entities/component.md, «Attachment Slots».
Объявление чувствительным целого объекта
Ключевое слово может стоять на объекте, а не на скаляре, и тогда оно охватывает всё, что находится под этим объектом, — собственных потомков объекта и всё, что вложено глубже. Это объявление стоит использовать, когда материалом является целый блок, а пометка каждого листа по отдельности оставила бы непомеченным следующий лист, который кто-нибудь добавит.
Потомки объекта должны находиться в явном блоке properties:. Это единственное место, где выводимая форма объекта не подходит, и причину стоит знать, а не обходить:
spec: schema: values: credentials: type: object sensitive: true properties: # required here username: { type: string } password: { type: string }Запись потомков непосредственно рядом с маркером, как выводимая форма объекта позволяет повсюду в остальных местах, отклоняется во время компиляции: о первом потомке сообщается как о неизвестном ключевом слове с позицией на собственном ключе потомка:
values: credentials: type: object sensitive: true password: # refused: unknown keyword "password" type: stringОтказ корректен, а не является ограничением, которое нужно обходить. Узел читается как лист-ограничение, как только он содержит ключевое слово компактной формы, а sensitive: — одно из них; поэтому с этого момента каждый соседний ключ тоже должен быть ключевым словом, а password им не является. Блок properties: говорит: «ключи ниже — имена свойств, а не очередные ключевые слова», и это то же разрешение неоднозначности, которое описано в разделе Выводимая и явная форма объекта. Понимать диагностику как «маркер нельзя ставить на объект» — ошибка, которой следует избегать: можно, и блок — это способ так сказать.
Листу внутри объявленного объекта собственный маркер не нужен. Его добавление безвредно и ничего нового не сообщает, поскольку объявление объекта уже его охватывает.
Чего ключевое слово не делает
Название наводит на предположения, которых ключевое слово не оправдывает, поэтому обозначим предел прямо:
- Оно ничего не шифрует. Это аннотация к объявлению, а не механизм обеспечения конфиденциальности.
- Оно не проверяет и не отклоняет, кроме случаев, когда заполняются параметры шаблона CloudFormation. Никакое значение не принимается и не отклоняется из-за того, что лист объявлен чувствительным, и никакой результат сборки не меняется — за исключением того, что когда
valuesMappingсущности Recipe или FeatureRecipe для CloudFormation читает лист, объявленный чувствительным, чтобы заполнить параметры исходного шаблона, каждый литерал, привязываемый этим сопоставлением, останавливает сборку, так что две сборки, различающиеся лишь объявлением, могут завершиться по-разному. См. A secret bound to a CloudFormation parameter would be written into the template (Секрет, привязанный к параметру CloudFormation, был бы записан в шаблон). - Оно не гарантирует, что выводимый результат свободен от материала. Содержит ли артефакт материал, зависит от того, какое заполнение присоединил автор и что автор написал в его
values, — см. architecture/08-credential-model.md, «Что компилятор гарантирует и чего не гарантирует». Значение, объявленное чувствительным и заданное автором встроенно, выводится точно так же, как необъявленное, везде, где сборка его вообще выводит. - Оно не навязывает механизм доставки. Оно не может превратить встроенное значение в ссылку на хранилище и не сужает то, что разрешает список
injectслота. - Оно не останавливает сборку, кроме как через упомянутый отказ CloudFormation. Уведомления, которые оно выдаёт во время сборки и которые описаны ниже, носят рекомендательный характер: сборка выполняется до конца и записывает свои артефакты. Сделать уведомление фатальным — выбор организации, выраженный политикой управления, присоединённой к сборке, а не то, что ключевое слово делает само. Описанный выше отказ провайдера CloudFormation — исключение: он останавливает сборку, потому что литерал, записанный в шаблон, может прочитать любой, кто может прочитать стек.
- Оно не меняет ни одного выводимого байта на большинстве целевых платформ и на них никогда не изменит. Целевая платформа с собственным понятием чувствительности — это то место, где объявлению есть куда лечь; на платформе без такого понятия ему нечего менять, навсегда. Terraform — единственная целевая платформа стандартной библиотеки с таким примитивом: когда вход вендорированного модуля принимает материал, объявленный автором чувствительным, выводимый результат получает сгенерированный файл переопределения, задающий для этого входа собственный атрибут чувствительности Terraform, — см. providers/terraform.md, «Declared-sensitive module inputs». Во всех остальных случаях объявление листа чувствительным во всём существующем каталоге оставляет каждый выводимый артефакт идентичным.
Что оно меняет в выводе инструмента
Единственное, что объявление действительно меняет, — то, что инструмент печатает для чтения человеком: его отладочный вывод и текст отказа, описанный ниже. На отладочных поверхностях значение, объявленное чувствительным, заменяется фиксированным текстом <redacted>:
- трассировка по проходам, которую
aggrega build --traceзаписывает в.trace/; - блок
Values:по узлам, которыйaggrega inspectпечатает для сущности Aggregate; - блок присоединений по листьям, который
aggrega inspectпечатает для разрешённой сущности Release.
Ключ всегда сохраняется, а заменяется только его значение, поэтому читатель по-прежнему видит, что лист задан и что что-то было скрыто. Лист, который автор не объявил, печатает своё значение дословно рядом со скрытым соседом: подстановка следует объявлению и ничему иному, поэтому поле с именем password без объявления печатается, а объявленное поле с именем key — нет.
Объявление достигает каждого листа под ним и достигает всех трёх поверхностей одинаково. Когда объявление стоит на объекте, каждое значение, вложенное в этот объект, тоже скрывается на любой глубине: объявление объекта их называет, поэтому их сокрытие не утверждает ничего, чего автор не написал. Сопоставление идёт по целым сегментам пути, а не по тексту, поэтому соседний элемент, имя которого лишь начинается с объявленного имени, не затрагивается: объявление dbPassword не скрывает dbPasswordHint.
Сокрытие в трассировке можно отключить для одной сборки, когда отлаживается именно скрытое значение: aggrega build --trace --trace-unredacted записывает значения в файлы трассировки и помечает каждый из этих файлов заголовком, сообщающим об этом. Это выбор во время вызова без параметра конфигурации, он затрагивает только трассировку и описан в cli/aggrega-build.md, «Showing the withheld values». У представлений aggrega inspect есть свой флаг, --unredacted, описанный в cli/aggrega-inspect.md, «Showing the withheld values».
Границы этого поведения важнее самого поведения.
Отрисованные артефакты никогда не редактируются. Всё, что находится в dist/, выводится ровно в том виде, в каком его создала отрисовка, потому что это и есть то, что развёртывается: заполнитель, записанный в манифест, дал бы сломанное развёртывание, а не защищённое. Редактирование касается того, что инструмент печатает, и никогда того, что он записывает. Понимать объявление как обещание, что dist/ безопасно публиковать, — единственное неверное прочтение, которого следует избегать: описанный выше предел не меняется, и dist/ остаётся столь же чувствительным, как самое насыщенное секретным материалом присоединение в нём.
Одно объявление может добавить в отрисованный артефакт, и это не редактирование: если у целевой платформы есть собственный примитив чувствительности, объявление отрисовывается в него. Значение по-прежнему записывается полностью — ничего не скрывается и не заменяется, — а артефакт получает рядом с ним собственную пометку целевой платформы, чтобы её инструменты могли обращаться со значением так, как его объявил автор. Сегодня такой примитив предлагает Terraform; что его атрибут гарантирует и чего не гарантирует, описано в providers/terraform.md, раздел «Declared-sensitive module inputs». Такая пометка переносится только туда, где идентичность отрисованного имени восстанавливается из самого объявления; если имя придумал шаблон, пометка отсутствует, а не подбирается приблизительно, потому что пометить значение, которое автор не объявлял, значило бы утверждать о нём ложное. Если этот шаблон — valuesMapping (сущности Recipe или сущности FeatureRecipe для сущности Feature, присоединённой к компоненту), сборка сообщает об этом, как описано ниже.
Редактирование охватывает то, что называет объявление, а также то, что, как видно, читает шаблон. Объявленный лист в разделе values или infra и ключ доставки, который переносит материал из ключа provides, объявленного чувствительным, определяются по имени и скрываются. Значение, вычисленное шаблоном, попадает под ключ, который никто не объявлял, поэтому его определяет ссылка, написанная автором: в трассировке скрывается запись locals: или поле source:, шаблон которых читает объявленный чувствительным лист, а также запись locals:, читающая уже скрытый соседний элемент. Это прочтение намеренно консервативно — обращение к объекту целиком затрагивает каждый объявленный лист под ним, а шаблон, передающий дальше все свои данные, затрагивает их все, — поэтому неразрешимая ссылка приводит к скрытию, а не к печати.
Отрисованный документ показывается как повторная отрисовка, и это указывается. Разобранный Workload в трассировке — это документ, созданный шаблоном сущности Recipe: ничто в нём не фиксирует, из какого объявления взят каждый символ, поэтому нет ключа, по которому можно было бы выполнить замену внутри него, а восстановление связи поле за полем означало бы анализ содержимого значения, чего компилятор не делает. Вместо этого трассировка показывает тот же шаблон workload:, вычисленный повторно в контексте, где объявленные чувствительными данные уже читаются как текст замены, и сообщает об этом в записи workload_note рядом с документом. Поскольку шаблон видит строку там, где была строка, повторная отрисовка сохраняет форму выведенного документа, а текст замены стоит на месте скрытого значения. Остаются два различия, и примечание называет оба: шаблон, ветвящийся по содержимому значения, отрисовывается с текстом замены иначе, а значение, которое ось не называет, переносится без изменений. Это отладочное представление отрисованного, а не его копия.
Значения потребляемого узла скрываются в соответствии с объявлениями этого узла на обеих поверхностях, куда их переносит ребро. Представление ребра uses воспроизводит то, что опубликовал целевой компонент, поэтому им управляет собственная схема цели: ключ provides, который цель объявила чувствительным, скрывается в трассировке потребителя, даже если потребитель ничего не объявляет. Если собственный блок inject ребра направляет этот ключ на ключ доставки потребляющего компонента, этот ключ доставки тоже скрывается — по тому же правилу, которому следует сопоставление inject присоединения, с чтением того же объявления, так что две схемы связывания не могут расходиться. Представления aggrega inspect показывают собственные разделы узла и его присоединения, а не опубликованные значения потребляемого узла, поэтому там нет межузлового представления, которое нужно было бы скрывать.
Присоединение, записанное на соединении, скрывается в соответствии с объявлениями его собственной сущности Feature на каждой поверхности, где оно показано. Трассировка показывает его в представлении ребра uses этого соединения, по пути .context.uses.<alias>.features.<slot>, а aggrega inspect печатает его под строкой соединения в разрешённой сущности Release. В обоих случаях лист values или infra, который его Feature объявляет чувствительным, скрывается точно так же, как для той же Feature, присоединённой непосредственно к компоненту, а в трассировке скрывается и ключ разрешённого provides присоединения, который Feature объявляет чувствительным. Его тип, версия, метки и каждый необъявленный лист и ключ provides печатаются дословно, так что опубликованный локатор остаётся читаемым рядом с материалом, на который он указывает. Слот, объявляющий sensitive: true, на компоненте или на сокете, помечает присоединение как работающее с секретным материалом и сам по себе не скрывает ни одного листа — какие листы скрывать, объявляет Feature.
Машиночитаемые проекции дословны по контракту, и обращаться с ними нужно так же, как с файлами, из которых они получены. aggrega inspect --raw выводит сущность ровно так, как она написана, а aggrega inspect --output yaml воспроизводит написанную сущность для любого вида, включая Release. Ни одна из них ничего не заменяет, и это сделано намеренно: это выходные данные, которые разбирает скрипт и сравнивает diff, поэтому вывод, втихую скрывающий часть себя, искажал бы входные данные, которые он якобы воспроизводит, и ломал бы полный цикл, от которого зависят его потребители. Объявления листа чувствительным недостаточно, чтобы исключить его из этих выводов: передавайте, храните и распространяйте их так же, как сами сущности Aggregate и Release.
Скомпилированный граф — единственная машиночитаемая проекция, которая скрывает значения, где бы её ни выдавали. --ir-graph в aggrega inspect, aggrega validate и aggrega build записывает разрешённый при запуске граф в формате JSON рядом со всем, что команда уже выводит, а aggrega/irGraph демона отвечает редактору тем же графом; в каждом случае значение, объявленное автором чувствительным, заменяется точно так же, как в читаемых представлениях. --unredacted рядом с --ir-graph печатает эти значения, как и поле unredacted в запросе к демону. Таким образом, граф, полученный от команды, и граф, полученный по протоколу демона, — один и тот же документ с одним правилом обработки, и конвейер или клиент, которому нужны написанные автором значения, должен запросить их явно.
Что отказ сообщает об объявленном значении
Отказ, вызванный шаблоном, который читает значение, объявленное автором как чувствительное, не содержит этого значения. Когда шаблон останавливает сборку — утверждение вызывает fail, выражение не удаётся вычислить, вывод не читается как документ, который шаблон должен создать, — и одна из его ссылок достигает объявленного чувствительным элемента данных, сообщаемое берётся из повторного вычисления того же шаблона в контексте, в котором каждый объявленный чувствительным элемент данных уже читается как <redacted>, — если только шаблон не остановился на предложении, которое он сам выписывает целиком; это первый случай ниже:
assertion failed: the admin password <redacted> must be supplied as a reference- Вызов
fail, предложение которого полностью записано в шаблоне, сообщается в том виде, в каком оно записано. Если вызов, остановивший сборку, — этоfailс одной строкой в кавычках —fail "…", в который ничего не передано через конвейер и в предложение которого ничего не подставлено, — отказ содержит это предложение независимо от содержимого значения и от того, какая ветвь привела к вызову, поскольку предложение не цитирует ничего из прочитанного шаблоном: утверждение, отклоняющее источник неверной формы, показывает собственное объяснение этой формы. Предложение, построенное любым другим способом —printf, поле, переменная, значение, переданное через конвейер вfail, — сообщается согласно следующим случаям. - Если второе вычисление завершается ошибкой на том же выражении по той же причине, сообщается именно эта ошибка. Собственная фраза автора сохраняется, а на месте значения стоит
<redacted>; значение, которое шаблон закодировал, заключил в кавычки или иначе преобразовал, тоже скрывается, поскольку замена происходит до преобразования. - Если нет, отказ называет выражение, вызвавшее ошибку, и сообщает, что его текст скрыт. Это шаблон, поведение которого зависело от содержимого значения, — с текстом замены он пошёл по другой ветви или завершился ошибкой в другом месте, — поэтому ничего из составленного им показать нельзя. Чтобы такой отказ объяснял себя сам, запишите его предложение полностью в вызове
fail, как описано в первом случае. Отказ по-прежнему останавливает сборку и сохраняет свой код. - Отрисованная сущность Workload, которую отклоняет схема Workload, описывается на основе схемы. Поля документа не хранят обратной связи с данными, которые прочитал его шаблон, поэтому если этот шаблон прочитал объявленный чувствительным элемент данных, каждое замечание, которое могло бы процитировать значение, вместо этого формулирует ограничение, с
<redacted>на месте значения и пояснением причины. Советы, выведенные из значения, не даются, а замечание, не цитирующее значения, — отсутствующий ключ, ключ, который Workload не допускает, — выглядит как обычно:
.containers.main.imagePullPolicy: against /$defs/container: enum: <redacted> does not satisfy enum ["Always","Never","IfNotPresent"] (the value is withheld because the template that rendered this document reads a value declared sensitive)- Входные данные
withшага конвейера, отклонённые объявленным входным контрактом шага, описываются на основе контракта, если шаблонwithчитает объявленный чувствительным элемент данных: каждая ошибочная позиция во входных данных и ключевое слово схемы, отклонившее её, затем пояснение причины — и ничего из того, что содержали входные данные. - Отказ, называющий координату
source:, описывается на основе того, что получено не из объявленного, если шаблонsource:получил эту координату, прочитав объявленный чувствительным элемент данных: источника нет в lock-файле или кеше, его кешированный архив не совпадает с записью в lock-файле либо закрепление, записанное рядом с сущностью, расходится с lock-файлом. Каждая строка такого отказа называет координаты, использованные при поиске, поэтому она называет источник по его url и версии или ссылке, с которой он был запрошен, — там, где он их прочитал, — с<redacted>вместо каждой, полученной таким шаблоном, и сообщает, что причина скрыта. Отказ сохраняет свой код и способ исправления, который сборка даёт для этого кода:
source-artifact https://example.com/fragments/app.yaml@<redacted>: the reason is withheld: the template producing this source reads a value declared sensitive, and the reason names what the template producedОбъявленным считается то, что называют объявления, во всех частях контекста, которые может читать шаблон: собственные values и infra компонента, сущности Features, подключённые к нему и к каждому из его соединений, ключ доставки, несущий объявленный материал, ключ provides, который его сущность Component объявляет чувствительным, каждая запись списка, который несёт контекст, как описано ниже, и запись locals:, вычисленная из любого из них. Шаблон, не читающий ничего из этого, сообщает ровно так же, как если бы объявлений не было нигде, байт в байт, поэтому иначе сообщается только отказ, вызванный шаблоном, который прочитал объявленное значение. Чтение то же, что использует трассировка, — по ссылкам, которые записывает шаблон: обращение ко всему объекту достигает каждого объявленного листа под ним, поэтому может скрыть текст, не содержавший значения. Шаблон, который передаёт все свои данные целиком — точку или $ без продолжения, переданные в функцию вроде toJson, выведенные или переданные шаблону, вызываемому по имени, — читает каждое объявленное значение в них, поэтому о его отказе сообщается так же; внутри тела range или with точка — это значение, которое тело перебирает или называет, и её передача читает только то, что содержит это значение. Ничто здесь не зависит от --trace-unredacted: этот флаг влияет только на файлы трассировки, а отказ выглядит одинаково с ним и без него.
Объявленное значение скрывается, где бы оно ни находилось, в том числе внутри списка. Записи одного списка подчиняются разным сущностям, и каждая запись скрывается по объявлениям своей сущности. В представлении .boundary, которое читает сущность FeatureRecipe уровня всей границы, каждое соединение, перечисленное в internal_uses_edges, outgoing_cross_boundary_uses_edges, incoming_cross_boundary_uses_edges и cross_boundary_uses_edges, несёт provides, которые публикует его цель, и они скрываются там, где сущность Component цели объявляет ключ чувствительным, а каждая запись feature_attachments несёт infra этого вложения, которое скрывается там, где его Feature объявляет лист. В контексте сущности Feature, подключённой к компоненту, каждая запись .context.used_by несёт то, что публикует подключающийся компонент, и это скрывается там, где сущность Component подключающегося компонента объявляет ключ. Тот же ключ в записи, сущность которой ничего не объявляет, приводится как есть, а запись locals:, вычисленная из скрытой записи, скрывается вместе с ней. Перебор списка или обращение к одной из его записей через index читает весь список, поэтому считается чтением того, что несёт каждая запись:
error calling fail: target secret_ref "<redacted>" must start with ref-Это касается текста отказа, который выдаёт сборка. То, что сообщается провайдеру о том, какая часть его входных данных получена из объявленного значения, — значения, созданные valuesMapping, отрендеренный документ workload:, каждая запись artifacts:, каждое поле записи omits:, — не учитывает значение, прочитанное изнутри списка, поэтому собственная обработка объявленного значения провайдером, включая описанный выше отказ CloudFormation для привязанного литерала, на такое значение не распространяется.
Некоторые отказы выходят за эти рамки. Текст, который пишет плагин, — собственный отказ провайдера или шага конвейера — это фраза плагина, передаваемая так, как её написал плагин. Шаблон, вычисляемый вне утверждений и отрисовки сборки, — интерполяция и проверки параметров в сущности Aggregate, шаблоны when: и validate: схемы и разрешение координаты source:, записывающее её закрепление, — сообщает о своей ошибке так, как она произошла.
Предупреждение сборки о значении, передаваемом как литерал
Сборка выводит одно предупреждение на каждый ключ доставки, который несёт объявленный чувствительным материал как литеральное значение. Оно срабатывает, когда блок inject подключения направляет ключ provides, объявленный чувствительным в сущности Feature этого подключения, на ключ доставки потребляющего компонента, и значение действительно доставляется:
warning: node "db" (provider "helm"): attachment "user_password" delivers a valuedeclared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where thetarget supports it, fill the slot with an attachment that delivers a reference insteadТри его свойства преднамеренны.
Оно сообщает, как передаётся значение, а не о том, что что-то не так. Доставка литерала часто единственное, что принимает цель, и целое семейство подключений существует именно для этого. Предупреждение показывает автору, какое значение идёт этим путём и где, чтобы выбор был явным, а не неявным; оно не утверждает, что выбор ошибочен.
Это предупреждение, а не остановка. Сборка завершается успешно и записывает артефакты без изменений. Организация, которая хочет, чтобы учётные данные, доставляемые литералом, приводили к сбою сборки, выражает это политикой управления над сборкой — именно там место отклонению: правило, которое некоторые развёртывания вынуждены нарушать, не является поведением компилятора по умолчанию.
Решение принимается по связыванию, а не по значению. Предупреждение читает чувствительность, объявленную схемой, и доставку, которую написал автор. Никакое значение не проверяется, поэтому поле никогда не угадывается как учётные данные по имени или содержимому, а необъявленное значение, в котором случайно оказался пароль, ничего не вызывает.
Два случая намеренно остаются без предупреждения. Ключ доставки, чей ключ provides ничего не публикует, не доставляет литерала и ни о чём не сообщает — предупреждение следует за состоявшейся доставкой. А слот с пустым списком разрешений inject оставляет доставку сущности Recipe, поэтому автор не написал ключа доставки, о котором можно сообщить, и ему нечего предпринимать.
Предупреждение образует собственный класс со своим кодом, и --no-unsupported-field-warnings его не отключает: этот флаг относится к уведомлениям о точности цели, а это другая оценка, отключаемая по другим причинам. Оно также доходит до редактора, где отображается как проблема в сущности Aggregate, если языковой сервер запущен с включённым --build-on-inspect (или ключом конфигурации serve.build_on_inspect). По умолчанию этот параметр выключен для согласованности с aggrega inspect: команда терминала при инспекции графа не доходит до этапа отрисовки, поэтому тоже не выдаёт такого предупреждения, и инспекция в редакторе, которая его также не выдаёт, показывает вам то же, что и терминал. Включив параметр, вы запрашиваете у редактора дополнительный уровень, и при этом ничего не записывается на диск — этап выполняется, а его артефакты отбрасываются. Он добавляет предупреждения, которые сборка выдаёт при отрисовке, и ни одной из проверок, на которых сборка останавливается. Каждая опубликованная проблема называет уровень, который её выдал, поэтому редактор может отличать это предупреждение от тех, о которых сообщают этапы разрешения и анализа.
Предупреждение сборки о значении, которое отображение отрисовывает без пометки
Сборка выводит одно предупреждение на каждый объявленный чувствительным лист values, пометку которого отрисовка не может передать, пока у автора ещё есть рычаг воздействия на неё. Оно срабатывает при отрисовке из source:, значения которого являются результатом valuesMapping — сущности Recipe над листом, который объявляет её Component, или сущности FeatureRecipe для Feature, присоединённой к компоненту, над листом, который объявляет эта Feature. Выходные ключи отображения — его собственное изобретение, поэтому ни одно объявление не называет ни один из них, и цель не получает поключевой пометки для листа:
warning: node "api" (provider "terraform"): attachment "token": "values.token" is declaredsensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMappingwhose output keys no declaration names, so the target receives no per-key sensitivitymarking for it; ...Строка называет лист по его авторской координате, а также Recipe или FeatureRecipe, отображение которой управляет соединением, потому что объявление и отображение записаны в двух разных сущностях; строка присоединения начинается с имени, под которым оно присоединено, так что два присоединения одной Feature к одному компоненту различимы. Рычаг — удаление отображения: без него значения, которые получает отрисовка из источника, имеют в качестве ключей объявленные пути листьев, и пометка передаётся вместе с ними. Отрисовка только артефактов и отрисовка только рабочей нагрузки остаются без предупреждения, потому что вообще не передают цели карту значений, как и Feature, присоединённая к границе, которая отрисовывается на пустом столпе values, — указанное выше ограничение там постоянно, и предупреждению нечего было бы предложить. Как и предупреждение о значении, передаваемом литералом, это предупреждение, а не остановка: оно не меняет ни одного отрисованного байта, образует собственный класс с собственным кодом sensitivity-not-conveyed, и --no-unsupported-field-warnings его не подавляет. Его полный вид описан в разделе Предупреждения и вывод линтера.
Где объявление читается, а где нет
Ключевое слово читается на том узле, на котором оно стоит, а затем чтение проходит по всем путям, которыми объявление может достичь этого элемента данных: вложенным картам свойств, каждой ветви композиции и цели $ref. И ветвь, и цель ссылки компонуются в несущее их свойство, поэтому объявление, найденное через любую из них, собирается для этого свойства; путь удлиняет только спуск по properties.
Маркер читается независимо от того, стоит ли он рядом с одним из этих ключевых слов или внутри того, чего ключевое слово достигает, поэтому две формы не требуют продуманного размещения:
- Рядом с
$refили внутри цели ссылки. Маркер на ссылающемся листе объявляет этот лист. Маркер в схеме, на которую указывает ссылка, тоже собирается для ссылающегося листа — по пути этого листа плюс цепочке под ним, но никогда не по пути внутри определения, где нет авторского значения. - Рядом с ключевым словом композиции (
allOf/anyOf/oneOf) или внутри собственныхpropertiesветви. Ветвь компонуется в несущий её объект, поэтому обходится каждая ветвь — включая условные ветви узла, написанного как JSON Schema, — и объявление внутри неё собирается по собственному пути компонующего свойства плюс его цепочке.
Одна форма всё же требует продуманного размещения маркера:
- На самом листе массива, а не на типе его элементов
items. Массив, элементы которого несут секретный материал, объявляется чувствительным на уровне массива, потому что тип элемента — не карта свойств и в него не выполняется спуск.
parameters: — другой словарь
sensitive не входит в словарь типизированного контракта parameters:. Aggregate, объявляющая его на записи параметра, отклоняется при загрузке Aggregate с диагностикой оболочки документа, сообщающей unexpected property: "sensitive" и указывающей на сам ошибочный ключ, — так же обрабатывается любой ключ вне этого словаря, поскольку контракт параметров является закрытым объектом.
Эта асимметрия намеренна: ось чувствительности охватывает три столпа данных, которые объявляет сущность каталога, а параметр — это вход контракта окружения, а не лист столпа. Передача учётных данных через параметр описана в architecture/08-credential-model.md, раздел «Legacy charts that demand a formatted string», где изложен компромисс, на который идёт этот путь.
Композиция с allOf, anyOf, oneOf
Ключевые слова композиции работают так же, как в JSON Schema:
# Inherit and extendsecondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 }
# Disjunction (one of several shapes)auth: oneOf: - existingSecret: { type: string, required: true } - rootPassword: { type: string, required: true } username: { type: string, default: app_user } password: { type: string, required: true }Компилятор выводит те же ключевые слова композиции в разрешённой JSON Schema. Каждая из составляющих записей может быть записана в компактной форме, в JSON Schema или ссылкой $ref:. Смешивание форм внутри одной композиции поддерживается.
Запасной выход — $jsonschema:
Для случаев, выходящих за пределы словаря компактной формы ($dynamicRef, unevaluatedProperties, глубокая композиция not:, рекурсивные типы), любой узел можно записать в полной JSON Schema:
values: architecture: { type: string, enum: [standalone, replication] } some_complex_field: $jsonschema: | type: object unevaluatedProperties: false allOf: - $ref: "#/$defs/Foo" - not: required: [conflicting_field] patternProperties: "^x-": { type: string } $defs: Foo: type: object properties: name: { type: string }Блок $jsonschema: содержит JSON Schema в виде YAML; компилятор передаёт его прозрачно — содержимое попадает непосредственно в разрешённый документ JSON Schema в позиции этого узла. Валидация, сообщения об ошибках и инструменты работают с разрешённым документом; этот запасной выход служит исключительно для удобства написания.
Ветвь not: может содержать description:, объясняющий, почему исключаемая ею форма отклоняется. Значение, соответствующее этой ветви, тогда отклоняется с этим описанием в качестве причины, выводимым в одной строке, вместо общей формулировки «not allowed here (здесь не допускается)», — поэтому пишите его как предложение, которое должен прочитать автор отклонённого значения. Используется только описание, записанное в самой ветви not:; описание в записи $defs, на которую ветвь лишь ссылается, не используется.
Каждый узел внутри блока читается как JSON Schema, а ключевое слово компактной формы, записанное там, сохраняет своё компактное значение (min: 3 у строки по-прежнему означает минимальную длину). $ref в блоке разрешается так же, как вне его: #/$defs/Foo указывает на запись в $defs: опоры, поэтому пример объявляет Foo там, а ссылка на запись, которую никто не объявил, отклоняется при загрузке сущности. $dynamicRef разрешается относительно $dynamicAnchor, поэтому можно записать рекурсивную структуру; значение, не прошедшее проверку глубоко внутри рекурсии, сообщается в поле, которое его содержит, — tree.children для неверного name двумя уровнями ниже в дереве, элементы children которого имеют вид { $dynamicRef: "#node" }.
Для unevaluatedProperties и unevaluatedItems действует одно ограничение. Если любое из них записано в узле, который также содержит ссылку, ключевое слово композиции (allOf, anyOf, oneOf), условие или зависимую схему, оно загружается, но не применяется, — а unevaluatedItems также не применяется рядом с contains. В примере выше unevaluatedProperties: false стоит рядом с allOf, поэтому { name: n, extra: 1 } принимается, хотя ни Foo, ни patternProperties не объявляют extra.
Запасной выход $jsonschema: действует на уровне узла, а не документа. Схема может использовать компактную форму для простых частей, запасной выход в JSON Schema для одного сложного поля и $ref: для общих структур — всё в одном документе.
Сочетание компактной формы и JSON Schema в одном документе
Компактную форму и JSON Schema можно свободно сочетать на границе любого узла. Правило диспетчеризации определяется формой содержимого:
- Узел, содержащий
$jsonschema:, рассматривается как JSON Schema (запасной выход). - Узел, содержащий ключевые слова верхнего уровня в стиле JSON Schema (
type:,properties:,additionalProperties:,if:и т. д.), рассматривается как JSON Schema (явная форма). - Узел, содержащий только записи «имя свойства → дочерняя схема» (без зарезервированных ключевых слов JSON Schema), рассматривается как компактная форма (выводимая форма).
- Узел, содержащий только
$ref:, является сквозной передачей ссылки. - Узел с
allOf:/anyOf:/oneOf:является композицией; каждая запись диспетчеризуется независимо.
Для листьев компактной формы стандартный шаблон — field_name: { type: ..., constraints... }: YAML-словарь, содержащий известную лексику компактной формы. Диспетчеризация распознаёт словари ограничений по их ключам.
В редком неоднозначном случае (например, схема компактной формы с полем, буквально названным type, которое диспетчеризация выводимой формы интерпретировала бы как ключевое слово JSON Schema) каноническим решением является явная форма — см. раздел «Зарезервированные ключевые слова в каждой области выводимой формы» выше.
Импорт контракта из файла — $import:
Контракт не обязательно размещать внутри сущности, которая его объявляет. $import: указывает файл, из которого его следует прочитать:
spec: schema: $import: ./contracts/api-server.schema.yamlТогда весь spec.schema берётся из этого файла, который пишется точно так же, как заменяемый им блок: столпы на верхнем уровне, под ними компактная форма или YAML в формате JSON Schema:
values: greeting: { type: string, enum: [hello, howdy], default: hello }infra: image_tag: { type: string, default: "1.0" }provides: host: { type: string }Можно импортировать и отдельный столп, а соседние с ним столпы описать встроенно рядом:
spec: schema: values: $import: ./contracts/values.yaml infra: image_tag: { type: string, default: "1.0" }Та же форма работает в valueSchema: и infraSchema: сокета usesSchema:.
Правила, которые им управляют:
$import:— единственный ключ в той позиции, где он находится. Соседний ключ, записанный рядом с ним, отклоняется, а не отбрасывается один из двух.- Относительный путь разрешается относительно каталога, в котором находится файл объявившей его сущности, и никогда относительно каталога, из которого запускается сборка, — это та же база, что используют
valuesMapping:,workload:иartifacts:. Путь должен оставаться внутри этого каталога, потому что все файлы, которые несёт публикация сущности, берутся оттуда: путь, выходящий за его пределы, или абсолютный путь указывает на файл, который не будет перенесён вместе с сущностью, и отклоняется — см. A path names content outside the entity’s own directory (Путь указывает на содержимое за пределами собственного каталога сущности). Схему, общую для нескольких сущностей, следует поместить в SchemaLibrary и ссылаться на неё через$ref:. - Импортированный файл переносится вместе с сущностью. Опубликованная сущность несёт каждый файл, импортируемый её схемой, включая все файлы цепочки, поэтому копия, полученная из реестра, читает тот же контракт и проверяет значения, написанные для него, — см.
aggrega push. - Импортированный файл содержит содержимое схемы, а не документ сущности. Файл, содержимое которого не является отображением YAML, отклоняется с указанием имени файла.
- Импортированный файл сам может состоять из одного
$import:, который разрешается рекурсивно; цепочка, возвращающаяся к файлу, который уже читается, отклоняется с указанием цепочки.
Импорт читается при загрузке сущности, поэтому каждая поверхность, читающая эту сущность, видит один и тот же контракт: aggrega validate, сборка, aggrega push, aggrega inspect и редактор. Файл, который не удаётся прочитать, или содержимое, не являющееся схемой, отклоняется на этом этапе, а не оставляет контракт непроверенным, — и push отклоняет его до того, как что-либо будет опубликовано.
$import: и $ref: не взаимозаменяемы. $import: указывает файл и заменяет содержимое целиком; $ref: указывает запись SchemaLibrary по идентификатору и компонуется в любом узле. Значение $import:, содержащее идентификатор библиотеки или хост реестра, отклоняется с указанием использовать $ref:. См. cross-document-ref.md.
Пространство имён расширений Aggrega — x-aggrega-*
Компактная форма распознаёт любое ключевое слово с префиксом x-aggrega- как расширение, специфичное для Aggrega. Пространство имён открыто: новые аннотации попадают в каталог без правок словаря для каждого ключевого слова. Авторы, пишущие x-aggrega-selector, x-aggrega-narrowed-from или будущие аннотации, получают своё содержимое в нужной области видимости итоговой JSON Schema без отклонения на этапе компиляции.
Префикс пространства имён важен: опечатка вроде x-agrega-source (пропущена одна g) НЕ распознаётся как ключевое слово расширения и будет отклонена семантикой закрытых объектов в областях выводимой формы. Область префикса служит сетью для обнаружения опечаток в поверхности аннотаций каталога.
Отдельные аннотации x-aggrega-* компилятор выдаёт в хорошо известных точках конвейера:
x-aggrega-selector:— выдаётся при синтезеusesSchema:иfeaturesSchema:и несёт строку селектора, нацеленную на совместимые Components поставщика.x-aggrega-sensitive:— выдаётся листом, объявляющимsensitive: true. См. раздел Объявление листа конфиденциальным выше.
Авторы каталогов, создающие собственные ключевые слова расширений, используют то же пространство имён; последующие инструменты, потребляющие скомпилированную JSON Schema, читают ключи x-aggrega-* без конфликтов с собственным пространством ключевых слов JSON Schema.
Рабочий пример — схема Component для MariaDB
Типичная схема Component в компактной форме для хранилища данных MariaDB, в которой везде используется выводимая форма, а также показаны смешанные ограничения листьев, ссылки, условная структура и рабочий oneOf для блока аутентификации:
spec: schema: values: architecture: type: string enum: [standalone, replication] default: standalone description: | Topology mode. `standalone` runs a single primary; `replication` runs a primary plus N secondary replicas governed by the secondary block.
primary: replicaCount: { type: integer, min: 1, max: 9, default: 1 } resources: { $ref: "#/$defs/PodResources" } persistence: { $ref: "#/$defs/PersistenceSpec" }
secondary: when: '{{ eq $.architecture "replication" }}' properties: replicaCount: { type: integer, min: 2, max: 8, default: 2 } resources: { $ref: "#/$defs/PodResources" } persistence: { $ref: "#/$defs/PersistenceSpec" }
auth: oneOf: - existingSecret: { type: string, required: true } - rootPassword: { type: string, sensitive: true, required: true } username: { type: string, default: app_user } password: { type: string, sensitive: true, required: true } database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }
metrics: enabled: { type: boolean, default: false } serviceMonitor: enabled: { type: boolean, default: false } namespace: { type: string }
labels: { type: object, valuesType: string }
$defs: PodResources: requests: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" } limits: cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" } memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
PersistenceSpec: size: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$", required: true } storageClass: { type: string }В виде JSON Schema на YAML тот же контракт расписывает для каждого объекта type: object, properties: и additionalProperties: false и повторно перечисляет каждое обязательное поле в required: родителя, поэтому он получается значительно длиннее. Выигрыш в компактности растёт на более крупных контрактах Component и достаточно существенен, чтобы сделать компактную форму основным способом написания schema:, parameters: и записей SchemaLibrary.
Перекрёстные ссылки
- О семантике разрешения междокументных
$ref:(синтаксисrequired:рядом с междокументной ссылкой; развёртывание цепочек от библиотеки к библиотеке; сужение библиотеки потребителем): cross-document-ref.md. - О грамматике написания блока
assertions:(правила между полями, которые не может выразитьvalidate:компактной формы): templates/assertions-block.md. - О наборе столпов данных, в которых размещаются схемы компактной формы (
values:,infra:,provides:,uses:,features:,locals:,parameters:): data-pillars.md. - О правилах развёртывания сокращённой записи OCI URI (домен по умолчанию, сегмент реестра, резервная версия, развёртывание издателя): uri-grammar.md.
- О написании сущностей SchemaLibrary (где в каталоге хранятся схемы, на которые можно ссылаться через
$ref:): ../entities/schemalibrary.md.