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

Розв’язання міждокументних посилань `$ref:`

На цій сторінці описано семантику розв’язання міждокументних посилань $ref: у засобах створення схем Aggrega: що бачать автори сутностей Components, Features і записів SchemaLibrary, коли $ref: перетинає межу документа й веде до бібліотеки, а також правила required: для кожного синтаксису, які визначають, які форми запису коректно працюють із міждокументним розгортанням.

$ref: — нативний механізм JSON Schema 2020-12. Він трапляється у вмісті schema: (у сутностях Component, Feature, записах SchemaLibrary), у схемах компактної форми та в синтезованому шарі JSON Schema, який генерують usesSchema: і featuresSchema:. Ця сторінка зосереджена на міждокументному випадку, коли $ref: вказує на запис SchemaLibrary в окремому файлі або артефакті OCI.

Про успадкування між сутностями каталогу (Component розширює Component) див. inheritance-and-interface.md. Розширення однієї сутності Release іншою — це окремий механізм для документа, який не індексується в каталозі; його описано в entities/release.md.

$import: — інше ключове слово, що звертається до вмісту поза документом, і ці два ключові слова відповідають на різні запитання. $ref: називає запис у SchemaLibrary за ідентичністю — його розв’язує каталог, версію надає lockfile — і компонується в будь-якому вузлі. $import: називає файл поруч із сутністю й замінює весь вміст тим, що містить цей файл. $import: застосовується як до схем, так і до valuesMapping:, workload:, artifacts: і parameters:; про $import: у схемі див. compact-form-authoring.md, розділ «Імпорт контракту з файлу».

Семантика розв’язання $ref:

$ref: дотримується стандартного розв’язання JSON Schema 2020-12. На практиці трапляються такі форми посилань:

  • Локальні фрагменти в межах того самого документа: { $ref: "#/$defs/PodResources" } — розв’язується в запис PodResources у $defs схеми.
  • Посилання на записи SchemaLibrary за ідентичністю: { $ref: "WebPrimitives#/schemas/URL" } — форма <Library>#/schemas/<Entry> з голим іменем. Ім’я бібліотеки розв’язується щодо розв’язаного каталогу, а фрагмент JSON Pointer #/schemas/<Entry> вибирає запис; версію надає lock-файл, а не посилання. Посилання не містить хоста реєстру — форма з хостом oci://<host>/… відхиляється під час компіляції з діагностикою, яка спрямовує автора до форми ідентичності, тож фізичне розташування реєстру ніколи не потрапляє до авторського коду. Звідки надходять байти бібліотеки (з локального каталогу, кешу вмісту чи віддаленого реєстру) — справа розв’язувача, яка визначається під час розв’язання і ніколи не є частиною посилання.
  • Шлях до файлу не є ціллю посилання: { $ref: "./schemas/foo.yaml#/definitions/Foo" } відхиляється під час компіляції схеми з діагностикою, що називає форму <Library>#/schemas/<Entry>. Вміст схеми, що зберігається у файлі поруч із сутністю, натомість підключається через $import:, який обмежений власним каталогом сутності, як і кожен файл, що його читає сутність.

Посилання розв’язується під час компіляції. Розгортач вбудовує вміст, на який посилаються, у схему споживача; згенероване IR містить вбудований вміст, а не непряме посилання.

$ref: природно поєднується з ключовими словами композиції JSON Schema:

secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }
- description: "Replication-mode secondary instances."

allOf поєднує форму NodePool, на яку посилаються, з додатковими обмеженнями.

Синтаксис required: за міждокументного $ref:

Оголошуючи обов’язкові властивості в сутності Component або Feature, автори каталогів обирають між двома формами: маркерами на рівні листків (required: true на кожній властивості) або масивом на рівні батьківського об’єкта (required: [name1, name2, ...] в області видимості об’єкта). Обидві форми допустимі в JSON Schema 2020-12, і обидві враховуються під час міждокументного розгортання $ref:, якщо їх записано там, де показано в цьому розділі.

Авторинг у виведеній формі без $ref: — маркери на рівні листків накопичуються під час компіляції. Компілятор обходить кожну властивість і, якщо листок містить required: true, додає ім’я властивості до масиву required: синтезованого батьківського об’єкта.

spec:
schema:
values:
database: { type: string, required: true }
display_name: { type: string, required: true }
default_locale: { type: string, default: "en-US" }

Компілятор видає required: [database, display_name] в області видимості батьківського об’єкта.

Споживачі з $ref: — поруч із міждокументним $ref: можна записати лише properties, required і description, а обов’язкові поля, які додає споживач, — це ті, що він там записує: масив required: на рівні батьківського об’єкта або маркер required: true на рівні листка на властивості, яку він оголошує під properties:. Власні обов’язкові поля запису, на який посилаються, — маркери на рівні листків у його виведеній формі або його власний масив required: — застосовуються через посилання без змін. Масив на рівні батьківського об’єкта називає обов’язкові поля, не оголошуючи повторно властивостей, які запис уже оголошує:

spec:
schema:
values:
$ref: "Datastores#/schemas/PostgresPayload"
required: [database, display_name]

Маркер на рівні листка також враховується — на властивості, яку споживач оголошує поруч із посиланням, — тож записане там properties: { database: { type: string, required: true } } робить database обов’язковим точно так само, як required: [database]. Властивість споживача замінює однойменну властивість запису (див. Споживач звужує запис бібліотеки), тож оголосіть її повторно з потрібною вам структурою.

Розгортання ланцюжків між бібліотеками

Запис SchemaLibrary може сам містити $ref:, що вказує на запис іншої SchemaLibrary, утворюючи ланцюжок. Компілятор обходить ланцюжок під час компіляції: кожне $ref:, знайдене під час розгортання запису, саме розгортається в термінах бібліотеки, яка його містить.

# Library A
spec:
schemas:
DatabasePayload:
type: object
properties:
host: { type: string }
credentials: { $ref: "Credentials#/schemas/BasicAuth" }
# Library B (referenced from library A above)
spec:
schemas:
BasicAuth:
type: object
properties:
username: { type: string }
password: { type: string }

Сутність-споживач Component, що посилається на DatabasePayload, отримує повністю розгорнуту форму, у якій credentials заповнено з BasicAuth бібліотеки B. Значення, що порушує обмеження, внесене ланцюжком, відхиляється за його власним шляхом у документі, що перевіряється, і повідомлення про відхилення не називає запис бібліотеки, з якого походить обмеження; щоб його знайти, простежте ланцюжок $ref: від споживача.

Споживач звужує запис бібліотеки

Сутність-споживач Component може оголосити властивість, назва якої збігається з властивістю, отриманою із запису бібліотеки. У такому разі скомпільована властивість споживача повністю замінює властивість запису бібліотеки в об’єднаній формі.

# Library entry
spec:
schemas:
ToolContract:
type: object
properties:
side_effects:
type: array
items: { type: string, enum: [read, write, delete] }
# Consumer Component
spec:
schema:
values:
$ref: "Tools#/schemas/ToolContract"
properties:
side_effects:
type: array
items: { type: string, enum: [read] }
default: [read]

В об’єднаній формі side_effects відображає вужчий контракт споживача (enum: [read], зі значенням default); ширший enum: [read, write, delete] запису бібліотеки зникає. Цю властивість створив споживач.

Це очікувана поведінка: уточнення споживачами властивості запису бібліотеки — канонічний шаблон звуження. Звуження відбувається мовчки: властивість споживача має власне походження.

Перехресні посилання

  • Про успадкування сутностей каталогу (Component-extends-Component, Feature-extends-Feature) див. inheritance-and-interface.md.
  • Про успадкування між документами розгортання, посилання яких називають файли, а не сутності каталогу: розширення сутності Release іншою сутністю Release описано в entities/release.md, а розширення сутності Manifest іншою сутністю Manifest — у entities/manifest.md.
  • Про вказівники на джерела, специфічні для провайдера (Recipe.spec.source.chart:, Recipe.spec.source.modulePath:), див. документацію сутності Recipe. Вказівники на джерела Provider не уніфіковано під $ref:; плагін провайдера споживає їх безпосередньо.
  • Про правила розгортання скорочених OCI URI (типовий домен, контекстне розгортання сутностей, пріоритет розв’язання, обробка версій) див. uri-grammar.md.