Resolución de `$ref:` entre documentos
Esta página documenta la semántica de resolución de las referencias $ref: entre documentos en la superficie de autoría de esquemas de Aggrega — lo que ven los autores de Components, Features y entradas de SchemaLibrary cuando un $ref: cruza el límite de un documento hacia una biblioteca, y las reglas de required: por sintaxis que fijan qué formas de autoría funcionan limpiamente con la expansión entre documentos.
$ref: es nativo de JSON Schema 2020-12. Aparece dentro del contenido de schema: (entradas de Component, Feature y SchemaLibrary), dentro de los esquemas en forma compacta y dentro de la capa de JSON Schema sintetizada que emiten usesSchema: y featuresSchema:. Esta página se centra en el caso entre documentos, en el que $ref: apunta a una entrada de SchemaLibrary en un archivo independiente o en un artefacto OCI.
Para la herencia entre entidades del catálogo (Component-extends-Component), consulta inheritance-and-interface.md. Una Release que extiende una Release es un mecanismo distinto sobre un documento que no está indexado en el catálogo; está documentado en entities/release.md.
$import: es la otra palabra clave que alcanza contenido fuera del documento, y las dos responden a preguntas distintas. $ref: nombra una entrada de una SchemaLibrary por identidad — el catálogo la resuelve, el lockfile proporciona la versión — y se compone en cualquier nodo. $import: nombra un archivo junto a la entidad y sustituye el contenido completo por lo que contiene ese archivo. $import: se aplica en la superficie de esquemas además de en valuesMapping:, workload:, artifacts: y parameters:; para $import: en un esquema, consulta compact-form-authoring.md §«Importing a contract from a file (Importar un contrato desde un archivo)».
Semántica de resolución de $ref:
$ref: sigue la resolución estándar de JSON Schema 2020-12. En la práctica aparecen las siguientes formas de referencia:
- Fragmentos locales dentro del mismo documento:
{ $ref: "#/$defs/PodResources" }— se resuelve en la entradaPodResourcesbajo los$defsdel esquema. - Referencias a entradas de SchemaLibrary por identidad:
{ $ref: "WebPrimitives#/schemas/URL" }— la forma de nombre simple<Library>#/schemas/<Entry>. El nombre de la biblioteca se resuelve contra el catálogo resuelto y el fragmento JSON Pointer#/schemas/<Entry>selecciona la entrada; la versión la proporciona el lockfile, no la referencia. Una referencia no lleva ningún host de registry — una formaoci://<host>/…con host se rechaza al compilar con un diagnóstico que dirige al autor hacia la forma por identidad, de modo que una ubicación física de registry nunca entra en el código fuente escrito. Desde dónde se sirven los bytes de la biblioteca (un directorio local del catálogo, la caché de contenido o un registry remoto) es asunto del resolutor, se fija en el momento de la resolución y nunca forma parte de la referencia. - Una ruta de archivo no es un destino de referencia:
{ $ref: "./schemas/foo.yaml#/definitions/Foo" }se rechaza cuando el esquema se compila, con un diagnóstico que nombra la forma<Library>#/schemas/<Entry>. El contenido de esquema guardado en un archivo junto a la entidad se incorpora en su lugar con$import:, que está limitado al directorio propio de la entidad, como todo archivo que lee una entidad.
La referencia se resuelve en tiempo de compilación. El expansor inserta en línea el contenido referenciado en el esquema del consumidor; la IR renderizada lleva el contenido insertado, no la indirección.
$ref: se compone de forma natural con las palabras clave de composición de JSON Schema:
secondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 } - description: "Replication-mode secondary instances."El allOf compone la forma NodePool referenciada con las restricciones adicionales.
Sintaxis de required: bajo un $ref: entre documentos
Los autores del catálogo eligen entre dos formas de autoría al declarar propiedades obligatorias en un Component o una Feature: marcadores a nivel de hoja (required: true en cada propiedad) o el array a nivel del padre (required: [name1, name2, ...] en el ámbito del objeto). Ambas formas son válidas en JSON Schema 2020-12, y ambas cuentan bajo la expansión de $ref: entre documentos, escritas donde muestra esta sección.
Autoría en forma inferida sin $ref: — los marcadores a nivel de hoja se acumulan en tiempo de compilación. El compilador recorre cada propiedad y, donde una hoja lleva required: true, aporta el nombre de la propiedad al array required: del padre sintetizado.
spec: schema: values: database: { type: string, required: true } display_name: { type: string, required: true } default_locale: { type: string, default: "en-US" }El compilador emite required: [database, display_name] en el ámbito del padre.
Consumidores con $ref: — junto a un $ref: entre documentos solo se pueden escribir properties, required y description, y los requisitos que añade el consumidor son los que escribe allí: un array required: a nivel del padre, o un marcador required: true a nivel de hoja en una propiedad que declara bajo properties:. Los requisitos propios de la entrada referenciada — marcadores a nivel de hoja en su forma inferida, o un array required: propio — se aplican sin cambios a través de la referencia. Un array a nivel del padre nombra requisitos sin volver a declarar las propiedades que la entrada ya declara:
spec: schema: values: $ref: "Datastores#/schemas/PostgresPayload" required: [database, display_name]Un marcador a nivel de hoja también cuenta, en una propiedad que el consumidor declara junto a la referencia — así, properties: { database: { type: string, required: true } } escrito allí hace que database sea obligatorio exactamente como lo hace required: [database]. La propiedad del consumidor sustituye a la propiedad de la entrada con el mismo nombre (consulta El consumidor restringe la entrada de biblioteca), así que vuelve a declararla con la forma que quieres.
Expansión de cadenas de biblioteca a biblioteca
Una entrada de SchemaLibrary puede contener a su vez un $ref: que apunta a otra entrada de SchemaLibrary, lo que produce una cadena. El compilador recorre la cadena en tiempo de compilación: cada $ref: que encuentra mientras se expande una entrada se expande a su vez, en los términos de la biblioteca que lo contiene.
# 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 }Un Component consumidor que referencia DatabasePayload recibe la forma completamente expandida, con credentials rellenado a partir del BasicAuth de la biblioteca B. Un valor que incumple una restricción aportada por la cadena se rechaza en su propia ruta dentro del documento que se comprueba, y el rechazo no nombra la entrada de biblioteca de la que procede la restricción; sigue la cadena de $ref: desde el consumidor para encontrarla.
El consumidor restringe la entrada de biblioteca
Un Component consumidor puede declarar una propiedad cuyo nombre coincide con una propiedad traída de una entrada de biblioteca. Cuando esto ocurre, la propiedad compilada del consumidor sustituye por completo a la de la entrada de biblioteca en la forma fusionada.
# 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]En la forma fusionada, side_effects refleja el contrato más estrecho del consumidor (enum: [read], con un default); el enum: [read, write, delete] más amplio de la entrada de biblioteca desaparece. La propiedad la escribe el consumidor.
Este es el comportamiento esperado: que los consumidores refinen la propiedad de una entrada de biblioteca es el patrón canónico de restricción. La restricción es silenciosa: la propiedad del consumidor se sostiene sobre su propia procedencia.
Referencias cruzadas
- Para la herencia entre entidades del catálogo (Component-extends-Component, Feature-extends-Feature), consulta inheritance-and-interface.md.
- Para la herencia entre los documentos del lado del despliegue, cuyas referencias nombran archivos en lugar de entidades del catálogo: una Release que extiende una Release está documentada en
entities/release.md, y un Manifest que extiende un Manifest, enentities/manifest.md. - Para los punteros de origen específicos del proveedor (
Recipe.spec.source.chart:,Recipe.spec.source.modulePath:), consulta la documentación de la Recipe de cada entidad. Los punteros de origen de Provider no se unifican bajo$ref:; el plugin del proveedor los consume directamente. - Para las reglas de expansión de las abreviaturas de URI OCI (dominio predeterminado, expansión contextual de entidades, precedencia de resolución, gestión de versiones), consulta uri-grammar.md.