Перейти к содержимому
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 по идентичности — каталог её разрешает, lock-файл задаёт версию — и компонуется в любом узле. $import: называет файл рядом с сущностью и заменяет всё содержимое тем, что находится в этом файле. $import: применяется как в схемах, так и в valuesMapping:, workload:, artifacts: и parameters:; об $import: в схеме см. compact-form-authoring.md, раздел «Importing a contract from a file».

Семантика разрешения $ref:

$ref: следует стандартному разрешению JSON Schema 2020-12. На практике встречаются следующие формы ссылок:

  • Локальные фрагменты в пределах того же документа: { $ref: "#/$defs/PodResources" } — разрешается в запись PodResources в $defs схемы.
  • Ссылки на записи SchemaLibrary по идентичности: { $ref: "WebPrimitives#/schemas/URL" } — форма <Library>#/schemas/<Entry> с голым именем. Имя библиотеки разрешается по разрешённому каталогу, а фрагмент JSON Pointer #/schemas/<Entry> выбирает запись; версию предоставляет lockfile, а не ссылка. Ссылка не содержит хоста реестра: форма с хостом 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.