Разрешение междокументных ссылок `$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 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.