SchemaLibrary
SchemaLibrary — це сутність каталогу, що містить багаторазово використовувані визначення JSON Schema 2020-12, а також необов’язкові параметризовані допоміжні засоби. Components і Features, які мають спільні форми схем — URL-адреси, тривалості, типові структури перевірок (probe), повторювані обмеження ресурсів, — оголошують ці форми один раз у бібліотеці й посилаються на них через канонічні 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/v1beta1kind: SchemaLibrarymetadata: name: WebPrimitives version: 1.0.0spec: schemas: URL: type: string pattern: "^https?://" HTTPMethod: type: string enum: [GET, POST, PUT, PATCH, DELETE]Створення записів схем
Записи схем створюються в одній із трьох форм. Компактна форма — типовий спосіб опису коротких поширених структур: type, pattern, enum, min, max та подібних однорядкових обмежень. JSON Schema 2020-12 у YAML — рівноправний варіант для записів, яким потрібні всі можливості 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 та в закріпленні lockfile), але розв’язану версію надає lockfile кожної сутності 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.