Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

SchemaLibrary

SchemaLibrary — это сущность каталога, которая содержит переиспользуемые определения JSON Schema 2020-12, а также необязательные параметризованные вспомогательные конструкции. Components и Features с общими формами схем — URL, длительностями, типовыми структурами проб, повторяющимися ограничениями ресурсов — объявляют эти формы один раз в библиотеке и ссылаются на них через канонические URI $ref. Сущность библиотеки относится к уровню 3: она подключается по желанию в каталогах, которым нужно переиспользование схем между сущностями Component. Каталоги без повторяющегося содержимого схем поставляются без какой-либо SchemaLibrary.

Роль SchemaLibrary

Архитекторы платформы создают сущности SchemaLibraries, чтобы централизовать схемы, повторяющиеся в каталоге. Библиотека — не развёртываемый строительный блок, а пространство имён определений. Авторы сущностей Component / Feature ссылаются на записи библиотеки по их каноническому URI $ref: тип задаётся один раз и проверяется везде, где разрешается ссылка.

Разделение на «библиотеку» и «потребителя» сделано намеренно. Сущности Components объявляют контракт, который заполняет экземпляр (его values, infra и provides, его сокеты, его слоты учётных данных). Сущности Features описывают поведенческие дополнения. Сущности SchemaLibraries описывают только содержимое схем — структурные правила, которым должно удовлетворять значение. Разделение этих трёх ролей позволяет каждому виду сущностей развиваться в собственном темпе; авторы, которым не нужны общие определения схем, никогда не сталкиваются с сущностью библиотеки.

Оболочка сущности

Сущность SchemaLibrary имеет стандартную оболочку каталога. apiVersion: aggrega.ai/v1beta1 и kind: SchemaLibrary обозначают вид сущности; metadata.name — идентификатор в стиле PascalCase; metadata.version следует строгому семантическому версионированию. Содержимое библиотеки находится в spec: spec.schemas обязателен (библиотека должна объявить хотя бы одну запись), а spec.templates необязателен (присутствует, только если библиотека использует параметризованные вспомогательные шаблоны).

apiVersion: aggrega.ai/v1beta1
kind: SchemaLibrary
metadata:
name: WebPrimitives
version: 1.0.0
spec:
schemas:
URL:
type: string
pattern: "^https?://"
HTTPMethod:
type: string
enum: [GET, POST, PUT, PATCH, DELETE]

Написание записей схемы

Записи схемы пишутся в одной из трёх форм. Компактная форма — основной вариант для коротких распространённых структур: type, pattern, enum, min, max и подобных однострочных ограничений. YAML в формате JSON Schema 2020-12 — равноправный вариант для записей, которым нужны все возможности JSON Schema (ключевые слова композиции, условная структура, сложные $defs). Смешение двух форм в пределах одной записи поддерживается за счёт того, что компилятор компактной формы выбирает обработку по структуре содержимого каждого узла; запасной выход $jsonschema: встраивает полное содержимое JSON Schema в любой узел, когда компактная форма не может выразить замысел.

format в записи проверяет то же, что и в любой схеме: он называет один из форматов email, uri, hostname, ipv4, ipv6, uuid, date-time и date, и значение, которое потребитель передаёт для поля, отклоняется, если оно не соответствует этому формату, — см. vocabulary/compact-form-authoring.md. Запись, называющая любой другой формат, включая password, отклоняется при загрузке библиотеки, поэтому aggrega validate для всего каталога отклоняет её независимо от того, ссылается ли на неё уже что-либо, с указанием библиотеки, записи и имени формата и перечнем поддерживаемых форматов, а сборка или загрузка, чья сущность Release достигает библиотеки, на этом останавливается. Запись, ссылающаяся на другую библиотеку, проверяется там, где её потребляет опора сущности Component или Feature. Поле, содержащее секретные данные, объявляет sensitive: true, а не формат.

Шаблоны и $instantiate:

Библиотеки со значительной повторяющейся структурой объявляют параметризованные вспомогательные шаблоны в spec.templates. Шаблон содержит карту $params: (именованные типизированные объявления параметров) и тело (компактную форму или содержимое JSON Schema, ссылающееся на параметры как на скалярные токены $<paramName>). Записи схем создают экземпляры шаблонов через привязки $instantiate: + $args:; механизм подстановки заменяет заполнители параметров литеральными скалярными значениями и формирует тело итоговой записи.

spec:
schemas:
LivenessProbe:
$instantiate: ProbeTemplate
$args:
port: 8080
path: /healthz
ReadinessProbe:
$instantiate: ProbeTemplate
$args:
port: 8081
path: /ready
templates:
ProbeTemplate:
$params:
port:
type: integer
path:
type: string
type: object
properties:
port:
type: integer
const: $port
path:
type: string
const: $path

Подстановка выполняется только литеральными скалярами. Механизм подстановки не интерпретирует синтаксис шаблонов Go, не вычисляет условия и не выполняет циклы. Авторы, которым нужны более выразительные вспомогательные средства, составляют сущности Components или Features, которые используют записи библиотеки со своими собственными вариациями.

Соглашения об именовании

Имена библиотек, ключи записей схем и имена шаблонов записываются в PascalCase. JSON Schema конверта сущности обеспечивает соблюдение этого соглашения в трёх местах с помощью ограничений по шаблону:

  • metadata.name соответствует ^[A-Z][A-Za-z0-9]*$.
  • Ключи карты spec.schemas соответствуют тому же шаблону через propertyNames.
  • Ключи карты spec.templates соответствуют тому же шаблону через propertyNames.

Сущность SchemaLibrary с ключом не в PascalCase в spec.schemas или spec.templates не проходит проверку конверта при загрузке рабочего пространства. Проверка на уровне конверта несёт существенную нагрузку: ключи записей схем входят в канонические URI $id (#/schemas/<name>), а имена шаблонов ссылаются на канонические URI во время создания экземпляра. Отсеивание ключей не в PascalCase при загрузке не даёт им распространиться по экосистеме каталогов.

Имена параметров в карте $params: шаблона локальны для шаблона — они не входят в канонические URI $id и не ограничиваются шаблоном на уровне конверта. Авторы следуют любому соглашению об именовании, подходящему для параметров шаблона; типичны port, path, intervalSec и подобные имена параметров в нижнем регистре.

Единообразие именования на уровнях библиотеки, схемы и шаблона делает идентификаторы ссылок легко читаемыми: WebPrimitives#/schemas/URL понятен с первого взгляда.

Семантику разрешения межфайловых ссылок $ref: — как $ref: разрешается через границы SchemaLibrary, различие синтаксиса required: для потребителей, содержащих $ref:, раскрытие цепочек от библиотеки к библиотеке и поведение, при котором потребитель сужает библиотеку, — см. в vocabulary/cross-document-ref.md.

Ссылки на записи библиотеки

Авторы сущностей Component / Feature ссылаются на запись библиотеки по её идентичности — форме с голым именем <Library>#/schemas/<name>:

# Inside a Component schema:
spec:
schema:
values:
healthCheck:
$ref: "WebPrimitives#/schemas/URL"

Имя библиотеки разрешается по разрешённому каталогу; фрагмент #/schemas/<name> выбирает запись. Ссылка не содержит хоста реестра; автор может указать необязательную нижнюю границу версии в виде <Library>:<version>#/schemas/<name> (разделитель версии — :, как в сопоставлениях recipe/feature и в закреплении lock-файла), но разрешённую версию предоставляет lock-файл каждой сущности Release, который закрепляет каждую используемую библиотеку по имени + версии + дайджесту содержимого. Ссылка, содержащая хост реестра, — форма oci://<host>/…, — отклоняется при компиляции с диагностикой, направляющей автора к форме идентичности, так что физическое расположение реестра никогда не попадает в авторский исходный код. Откуда отдаются байты библиотеки (локальный каталог, кэш содержимого или удалённый реестр), — забота резолвера, определяемая в момент разрешения; перенос реестра — это изменение конфигурации резолвера, а не исходного кода.

Запрещённые ключевые слова JSON Schema

Ключевые слова JSON Schema 2020-12 $dynamicAnchor и $dynamicRef запрещены в записях SchemaLibrary. Парсер SchemaLibrary сканирует как записи схем, так и тела шаблонов во время загрузки рабочего пространства; линтер публикации применяет избыточную защиту во время публикации; механизм инстанцирования повторно сканирует разрешённое тело после подстановки параметров, поэтому шаблон, который протаскивает запрещённые ключевые слова через значения параметров, всё равно завершается ошибкой. Вместе три проверки закрывают путь статического внесения (литерал $dynamicAnchor в записи схемы или теле шаблона), путь параметрического внесения (значение $args:, содержащее $dynamicRef) и путь обхода через сторонние инструменты (защита во время публикации перехватывает всё, что миновало парсер).

При срабатывании отклонения ошибка указывает недопустимое ключевое слово и путь к файлу. Авторы видят ошибку на этапе написания, а не при первом инстанцировании; тела шаблонов не исключаются из проверки во время загрузки.

Семантика динамических ссылок связана с вычислением во время выполнения таким образом, что это нарушает гарантию детерминированности компилятора на этапе компиляции. Авторы, которым нужно поведение динамических ссылок, перестраивают схему так, чтобы использовать статическое разрешение $ref; у этой проверки нет исключений.

Размещение по уровням

SchemaLibrary относится к уровню 3 в модели документирования уровней сущностей — подключается по желанию в каталогах, которым нужно повторное использование схем между сущностями Component. Каталоги без повторяющегося содержимого схем поставляются без какой-либо сущности SchemaLibrary; отметка уровня означает «продвинутое; пропустите, если не нужно» для навигации по документации, а не возможности. Компилятор обрабатывает SchemaLibrary единообразно с другими видами сущностей каталога: та же проверка оболочки при загрузке рабочего пространства, тот же конвейер JSON Schema 2020-12 для содержимого каждой записи, тот же конвейер публикации OCI во время выпуска.

В пределах уровня 3 механизм параметрических помощников spec.templates сам по себе подключается по желанию. Библиотеки со значительным объёмом повторяющейся структуры (шаблон Probe, параметризованный портом и путём; шаблон CORS, параметризованный списком разрешённых источников; шаблон TLS, параметризованный путями к сертификату и ключу) выигрывают от повторного использования через templates; библиотеки с разнородными единичными записями полностью обходятся без блока шаблонов и описывают каждую запись непосредственно в spec.schemas.