Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Створення схем у компактній формі

Компактна форма — це декларативне скорочення для JSON Schema 2020-12 у вигляді YAML. Автори записують обмеження кожного поля як вбудовані 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Максимальне значення або довжина, аналогічно до minmaximum: / 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.1RFC 2673, розділ 3.2 (dotted-quad)
ipv6адреса IPv6 у будь-якій з її текстових форм — повній, стиснутій через :: або із закінченням адресою IPv4 — 2001:db8::1. Зона (%eth0) чи довжина префікса (/64) не є частиною адресиRFC 4291, розділ 2.2
uuid32 шістнадцяткові цифри у групах 8-4-4-4-12, розділених дефісами, у будь-якому регістрі — 2eb8aa08-aa98-11ea-b4aa-73b441d16380RFC 4122, розділ 3
date-timeпозначка часу зі зміщенням — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00, з днем, що існує у своєму місяці, і додатковою секундою лише о 23:59 UTCRFC 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 в межах області об’єкта й видає їх як масив JSON Schema required: [field1, field2]. Позначка враховується, хоч би де оголошено властивість: в області виведеної форми й на властивості всередині явного блоку 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 «What the compiler does and does not guarantee». Значення, оголошене чутливим, яке автор надав вбудовано, рендериться точно так само, як неоголошене, скрізь, де збірка його взагалі рендерить.
  • Воно не нав’язує механізм доставки. Воно не може перетворити вбудоване значення на посилання на сховище і не звужує те, що дозволяє список дозволених inject слота.
  • Воно не зупиняє збірку, крім як через ту відмову CloudFormation. Сповіщення, які воно генерує під час збірки й описані нижче, є попередженнями: збірка виконується до кінця й записує свої артефакти. Зробити сповіщення фатальним — вибір організації, виражений як політика управління, приєднана до збірки, а не те, що ключове слово робить саме. Відмова провайдера CloudFormation вище — виняток: вона зупиняє збірку, бо літерал, записаний у шаблон, може прочитати кожен, хто може читати стек.
  • На більшості цільових платформ воно не змінює жодного відрендереного байта, і на них ніколи не змінюватиме. Цільова платформа, що має власне поняття чутливості, — це місце, куди оголошення може потрапити; платформа без такого поняття не має нічого, що воно могло б змінити, назавжди. Terraform — єдина ціль стандартної бібліотеки з таким примітивом: коли вхід вендореного модуля приймає матеріал, який автор оголосив чутливим, відрендерений результат отримує згенерований файл перевизначення, що задає власний атрибут чутливості Terraform для цього входу — див. providers/terraform.md «Declared-sensitive module inputs». Скрізь інде оголошення листка чутливим в усьому наявному каталозі залишає кожен відрендерений артефакт ідентичним.

Що воно змінює у виводі інструмента

Єдине, що оголошення таки змінює, — це те, що інструмент виводить для читання людиною: його налагоджувальний вивід і текст відмови, описаний нижче. На налагоджувальних поверхнях значення, оголошене чутливим, замінюється фіксованим текстом <redacted>:

  • потрохове трасування, яке aggrega build --trace записує в .trace/;
  • повузловий блок Values:, який aggrega inspect виводить для сутності Aggregate;
  • полисткový блок приєднань, який 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 value
declared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where the
target 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 declared
sensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMapping
whose output keys no declaration names, so the target receives no per-key sensitivity
marking 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 extend
secondary:
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: містить YAML у форматі JSON Schema; компілятор обробляє його як прозору передачу — вміст потрапляє безпосередньо в розв’язаний документ 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:

contracts/api-server.schema.yaml
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 }

Записаний як YAML у JSON Schema, той самий контракт виписує для кожного об’єкта 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.