Розв’язання міждокументних посилань `$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 Aspec: 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 entryspec: schemas: ToolContract: type: object properties: side_effects: type: array items: { type: string, enum: [read, write, delete] }
# Consumer Componentspec: 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.