Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Autoría en forma compacta

La forma compacta es una notación abreviada declarativa con forma de YAML para JSON Schema 2020-12. Los autores escriben las restricciones por campo como mapas YAML en estilo de flujo inline (port: { type: integer, min: 1, max: 65535, default: 8080 }); los nodos de objeto intermedios son el anidamiento natural de YAML; las referencias usan el $ref: estándar de JSON Schema. El compilador transforma la forma compacta en JSON Schema 2020-12 antes de que se ejecute cualquier validación, de modo que la validación, el informe de errores y cada herramienta que lee un esquema trabajan sobre el JSON Schema resuelto, sea cual sea la forma en que se escribió.

Esta página documenta el vocabulario de la forma compacta, las convenciones estructurales, el despacho entre objetos en forma inferida y explícita, la semántica de cierre, la heterogeneidad de type: que permite arrays de tipos admitidos, las palabras clave reservadas en cada ámbito en forma inferida y el espacio de nombres de extensión x-aggrega-*. Para la semántica de resolución de $ref: entre documentos, consulta cross-document-ref.md. Para la gramática de autoría del bloque de aserciones, consulta templates/assertions-block.md. Para el conjunto de pilares de datos (values:, infra:, provides:, uses:, features:, locals:, parameters:), consulta data-pillars.md.

La forma compacta es la superficie de autoría predeterminada para schema:, parameters: y las entradas de SchemaLibrary. JSON Schema en YAML es una opción de autoría de igual rango; ambas formas son de primera clase y pueden mezclarse dentro de un mismo esquema. Las dos formas se compilan en el mismo documento JSON Schema resuelto; las herramientas posteriores y la validación son ajenas al camino de autoría.

Vocabulario

Las palabras clave de la forma compacta son las de las tablas siguientes. Los autores las aprenden una vez y las aplican en schema:, parameters: y las entradas de SchemaLibrary.

Palabras clave de tipo e identidad

Palabra claveSignificadoSe compila a JSON Schema
typeTipo del campo (string, integer, number, boolean, object, array o un array de tipos admitidos)type:
descriptionDocumentación legible por personasdescription:
defaultValor predeterminado cuando falta el campodefault:
requiredMarcador por hoja (required: true) para los campos que deben estar presentesAñade el nombre del campo al array required: del padre

Palabras clave de restricción

Palabra claveSignificadoSe compila a JSON Schema
enumValores admitidos (lista)enum:
constEl único valor admitido — un escalar, un mapa o una listaconst:
minValor mínimo (numérico) o longitud mínima (cadena/array)minimum: (numérico); minLength: (cadena); minItems: (array) — elegido según type:
maxValor o longitud máximos, en paralelo a minmaximum: / maxLength: / maxItems:
minLength / maxLengthRestricciones explícitas de longitud de cadenaCorrespondencia directa con minLength: / maxLength: (úsalo cuando min/max serían ambiguos)
patternPatrón regex para cadenaspattern:
formatFormato con nombre que debe tener una cadena — uno de email, uri, hostname, ipv4, ipv6, uuid, date-time, date (consulta Formatos con nombre)format:

En el bloque parameters: de un Aggregate, algunas de estas también se comprueban sobre la propia declaración, antes de leer cualquier valor de la Release. Los minLength y maxLength propios de un parámetro son cero o más — uno negativo se rechaza cuando se carga el Aggregate — y cada pattern, incluido uno dentro de un contrato items, properties o valuesType anidado, debe ser una expresión regular que compile, ya que el patrón se compila al leer el contrato del parámetro. Cada format, a cualquier profundidad, debe ser uno de los formatos con nombre de más abajo. También se rechaza un min o un max en un parámetro booleano o de objeto, ya que el par no acota nada en esos tipos. Cada fallo detiene la compilación nombrando el parámetro, tanto si una Release lo proporciona como si no. Un límite de longitud dentro de un contrato anidado no está sujeto a ese mínimo; consulta entities/aggregate.md para saber dónde se ejecuta cada comprobación.

Formatos con nombre

format nombra la forma que debe tener un valor de cadena. Los nombres son los que define la especificación JSON Schema, escritos como ella los escribe, y cada uno comprueba lo que la especificación define que significa:

NombreUn valor conforme esDefinido por
emailun buzón: una parte local (átomos separados por puntos, o una cadena entre comillas), @, luego un dominio o un literal de dirección entre corchetes — ops@example.com. Un nombre para mostrar como Joe <joe@example.com> no es un buzónRFC 5321, sección 4.1.2 (Mailbox)
uriun URI absoluto: un esquema, :, luego el resto, con cualquier carácter fuera del alfabeto URI codificado con porcentaje — https://example.com/a%20b, s3://bucket/key. Una referencia relativa como /path no lo esRFC 3986 (URI)
hostnameun nombre de host: etiquetas separadas por puntos formadas por letras, dígitos y guiones, cada una de 1–63 caracteres que no empieza ni termina con un guion, 253 caracteres como máximo en total — db-primary.data.svc.cluster.local. Una etiqueta Punycode (xn--…) se acepta tal como está escrita; un comodín *, un guion bajo o un punto final, noRFC 1123, sección 2.1
ipv4cuatro números decimales de 0 a 255, separados por puntos — 192.0.2.1RFC 2673, sección 3.2 (dotted-quad)
ipv6una dirección IPv6 en cualquiera de sus formas de texto — completa, comprimida con :: o terminada en una dirección IPv4 — 2001:db8::1. Una zona (%eth0) o una longitud de prefijo (/64) no forma parte de una direcciónRFC 4291, sección 2.2
uuid32 dígitos hexadecimales en grupos de 8-4-4-4-12 separados por guiones, en mayúsculas o minúsculas — 2eb8aa08-aa98-11ea-b4aa-73b441d16380RFC 4122, sección 3
date-timeuna marca de tiempo con un desfase — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00, un día que existe en su mes y un segundo intercalar solo a las 23:59 UTCRFC 3339, sección 5.6 (date-time)
dateuna fecha de calendario — 2026-09-28 — cuyo día existe en su mes y añoRFC 3339, sección 5.6 (full-date)

Un formato juzga una cadena y nada más: un valor de otro tipo lo juzga su type. Y solo juzga la sintaxis del valor — nunca se resuelve un nombre de host, nunca se obtiene un URI, nunca se contacta un buzón —, de modo que la comprobación da la misma respuesta en cada compilación y no necesita red.

La comprobación se ejecuta dondequiera que un valor se valide contra su esquema: los parameters: de un Aggregate, los values e infra que restringen los pilares schema: de un Component o de una Feature, los values e infra por arista que restringen los esquemas de payload de un socket usesSchema:, y cada entrada de SchemaLibrary que alcanzan esos esquemas. Los nombres de formato de un pilar provides se juzgan cuando se carga el catálogo, como los de cualquier otro esquema; los valores que publica una Recipe no se validan contra el pilar, así que en ellos no se comprueba ningún formato. Dentro de allOf, anyOf, oneOf y not, un valor que no cumple su formato es un valor que no cumple esa rama, exactamente igual que un valor que no cumple cualquier otra restricción. Un valor no conforme se rechaza nombrando el campo, el valor y el formato.

Un nombre fuera de la tabla se rechaza cuando se carga el esquema, llegue o no algún valor a él, y el rechazo enumera los nombres admitidos — así, una errata como emial es un diagnóstico en lugar de una restricción que no comprueba nada. Para una entrada de SchemaLibrary, ejecuta aggrega validate sobre todo el catálogo para ver el nombre erróneo: una Release cuyos esquemas alcanzan la entrada también se rechaza, pero informa de la biblioteca como no encontrada. password no es un formato: un campo que contiene material secreto declara en su lugar sensitive: true.

Un límite se aplica a las formas alcanzadas indirectamente. Cuando la forma de un campo llega a través de un $ref: que lleva otras palabras clave junto a él (un mapa properties:, por ejemplo), a través del then: o el else: de un when:, o a través de un puntero a una propiedad declarada, su format se comprueba en los campos que la forma declara directamente y a través de allOf — pero no dentro de una rama anyOf, oneOf, not o condicional dentro de esa forma.

Palabras clave de composición y referencia

Palabra claveSignificadoSe compila a JSON Schema
$refReferencia a un fragmento JSON Pointer o a una entrada externa de SchemaLibrary$ref:
allOf / anyOf / oneOfComposición de JSON SchemaLas mismas palabras clave
patternPropertiesMapa con claves regexLa misma palabra clave
valuesTypeAbreviatura para mapas de valores tipados (p. ej., «objeto cuyos valores son todos cadenas»)additionalProperties: { type: <X> }

Palabras clave de contenedor

Palabra claveSignificadoSe compila a JSON Schema
itemsForma de los elementos del arrayitems: (forma compacta recursiva o JSON Schema)
propertiesDeclaración explícita de los hijos (rara vez necesaria; normalmente implícita mediante la estructura YAML)properties:
additionalPropertiesSi se permiten propiedades no declaradas (false en un objeto en forma inferida, donde lo añade el compilador; en un type: object explícito te corresponde escribirlo a ti, y donde no lo haces se aplica el valor predeterminado propio de JSON Schema, true)additionalProperties:

Palabras clave específicas de Aggrega

Palabra claveSignificado
validatePredicado de plantilla Go por campo que devuelve un booleano; false detiene la validación con validateMessage:
validateMessageMensaje de error que acompaña a un fallo de validate:
whenAplicación condicional de un subárbol; predicado de plantilla Go que determina si se aplican las restricciones del nodo
sensitiveDeclara que esta hoja contiene material secreto. Se compila a x-aggrega-sensitive: true. Consulta «Declaring a leaf sensitive (Declarar una hoja sensible)» más abajo
$jsonschemaVía de escape — subdocumento JSON Schema completo incrustado en este nodo
$modeAnotación de despacho opcional para casos ambiguos (rara vez necesaria; consulta «Inferred vs explicit object form (Forma inferida y forma explícita de los objetos)» más abajo)

Las palabras clave tomadas de JSON Schema ($ref, allOf, format, etc.) reutilizan una sintaxis idéntica a la de JSON Schema, por lo que los autores que ya conocen JSON Schema las reconocen de inmediato.

Una palabra clave cuyo valor es un dato lleva ese valor tal como está escrito. Un mapa o una lista que se da a default, enum o const es el propio valor, nunca un esquema anidado: endpoint: { type: object, default: { host: db, port: 5432 } } establece ese objeto como valor predeterminado de endpoint, y mode: { type: object, const: { kind: fast } } admite exactamente ese objeto — igual que mode: { const: { kind: fast } }, ya que const, como enum, convierte por sí solo el nodo en una hoja. Lo mismo vale dentro de una vía de escape $jsonschema:.

Cómo se estructura una hoja en forma compacta

La unidad de autoría es un nodo hoja — un campo con un dict de restricciones:

field_name: { type: <type>, ...constraints... }

Patrones comunes:

port: { type: integer, default: 8080 }
port: { type: integer, min: 1, max: 65535, default: 8080 }
identifier: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$" }
log_level: { type: string, enum: [debug, info, warn, error], default: info }
name: { type: string, minLength: 1, required: true }
email: { type: string, format: email }
enabled: { type: boolean, default: false }

Cada hoja ocupa una línea. El dict de restricciones recoge todo sobre la forma del campo; la estructura del nodo padre recoge la ubicación del campo.

Objetos anidados

La estructura de los objetos refleja el anidamiento YAML. El anidamiento profundo funciona directamente, con cada hoja todavía en una línea:

spec:
schema:
architecture: { type: string, enum: [standalone, replication], default: standalone }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "250m" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "512Mi" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "500m" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "1Gi" }
auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true }

El compilador infiere la estructura de los objetos a partir de la jerarquía YAML. Los nodos intermedios (aquí: primary, resources, requests, limits, auth) son tipos de objeto que contienen los hijos anidados. El compilador emite bloques type: object y properties: explícitos en el JSON Schema resuelto; el autor no los escribe.

Forma inferida y forma explícita de los objetos

Un ámbito de objeto en forma compacta puede escribirse de dos maneras:

Forma inferida — los hijos directamente bajo la clave padre, sin declaración type: object:

auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }

El compilador reconoce el ámbito como un objeto porque sus hijos son declaraciones de propiedades. Emite type: object, properties: { ... } e inyecta automáticamente additionalProperties: false en tiempo de compilación. La semántica de cierre forma parte del contrato de la forma inferida: las erratas en los campos escritos por los desarrolladores fallan de forma visible.

Forma explícita — type: object declarado, properties: enumeradas:

auth:
type: object
properties:
username: { type: string, default: app_user }
password: { type: string, sensitive: true }
required: [password]
additionalProperties: true # genuinely-open map authored on purpose

El compilador NO inyecta additionalProperties: false en la forma explícita. Los autores que declaran type: object asumen toda la responsabilidad de la decisión de cierre; la forma explícita es la superficie para mapas realmente abiertos (additionalProperties: true) y para objetos que necesitan otras palabras clave de JSON Schema (patternProperties, propertyNames, unevaluatedProperties).

Criterio de autoría: usa la forma inferida para los objetos cerrados ordinarios (el caso habitual en los esquemas del catálogo). Usa la forma explícita cuando el objeto deba ser realmente abierto, o cuando el esquema requiera palabras clave de JSON Schema que la forma compacta no admite directamente.

Semántica de cierre

Por convención, los objetos en forma inferida de la forma compacta son cerrados: las propiedades no declaradas producen un error de validación. El compilador emite automáticamente additionalProperties: false en cada ámbito de objeto en forma inferida. Esto coincide con la disciplina del catálogo de que las erratas fallen de forma visible.

Para abrir un objeto (permitiendo propiedades adicionales arbitrarias), usa la forma explícita con additionalProperties: true:

labels:
type: object
additionalProperties: true # opt-in; allow any string-keyed values

Para el patrón común «objeto cuyos valores comparten todos un tipo» (p. ej., un mapa de cadena → cadena para las etiquetas), usa valuesType::

labels: { type: object, valuesType: string }
nodeSelector: { type: object, valuesType: string }
counters: { type: object, valuesType: integer }

valuesType: <type> se compila a additionalProperties: { type: <type> }. Es un patrón lo bastante frecuente como para merecer una abreviatura de una sola palabra clave.

El nombre de tipo simple de arriba es la grafía de schema: y de SchemaLibrary. En un slot parameters: de un Aggregate, escribe en cambio el valor como un contrato — valuesType: { type: string }. Lo mismo se aplica a las otras dos palabras clave cuyo valor es a su vez un contrato, items: y cada entrada bajo properties:, porque una declaración de parámetro y cada contrato anidado en ella tienen una sola forma. Un nombre de tipo simple en cualquiera de esas tres posiciones de un slot de parámetro se rechaza, y el diagnóstico nombra qué contrato anidado lo contenía. Consulta entities/aggregate.md para el vocabulario completo de los slots de parámetros.

Campos obligatorios

Los campos obligatorios usan required: true por hoja:

auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }
database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }

El compilador recopila todos los marcadores required: true dentro de un ámbito de objeto y los emite como el array required: [field1, field2] de JSON Schema. El marcador cuenta allí donde se declare la propiedad: en un ámbito en forma inferida y en una propiedad dentro de un bloque properties: explícito.

Un consumidor que incorpora una entrada de SchemaLibrary a su esquema mediante $ref: puede nombrar sus requisitos de cualquiera de las dos maneras — un array required: [name1, name2] a nivel del padre junto a la referencia, o un marcador required: true en una propiedad que declara allí bajo properties:. Consulta cross-document-ref.md §«required: syntax under cross-document $ref: (sintaxis de los campos obligatorios bajo una referencia entre documentos)» para la regla completa.

Arrays

Los arrays usan type: array con items: describiendo la forma de los elementos:

tags: { type: array, items: { type: string } }
ports: { type: array, items: { type: integer, min: 1, max: 65535 } }
extraEnvVars:
type: array
items:
name: { type: string, required: true }
value: { type: string }
valueFrom: { type: object, additionalProperties: true }
allowedHosts:
type: array
min: 1 # minItems
max: 100 # maxItems
items: { type: string, format: hostname }

Para el caso común «array de escalares tipados», la forma inline ocupa una línea. Para arrays de objetos, items: introduce un esquema anidado en forma compacta.

La palabra clave type: — escalar o array de tipos

type: acepta un único valor (type: string) o un array de tipos admitidos (type: [string, integer, boolean]). La forma de array es la expresión estándar de JSON Schema 2020-12 para «este campo acepta uno de varios tipos»:

release_tier: { type: [string, integer], description: "Numeric tier or named tag" }

Cuando type: lleva un array, el espacio de valores es la unión de los espacios de valores de los tipos nombrados. Los autores que escriben esquemas que consumen la forma de array deben manejar ambas formas aguas abajo — el campo type del JSON Schema resuelto contiene una cadena o un array, y los consumidores que recorren el esquema resuelto comprueban ambas formas.

Palabras clave reservadas en cada ámbito en forma inferida

El despacho de la forma inferida reconoce un pequeño conjunto de palabras clave que tienen significado en el nivel del vocabulario de la forma compacta: description, type, default, required, las palabras clave de restricción (enum, const, min, max, pattern, format, etc.) y las palabras clave específicas de Aggrega (validate, validateMessage, when, sensitive). Cuando cualquiera de estas palabras clave aparece como nombre de campo en un ámbito de objeto en forma inferida, el compilador lee el ámbito que la contiene como una hoja de restricción en lugar de como un objeto: la palabra clave se toma como una restricción, no como una propiedad hija, y cada una de las demás claves de ese ámbito debe ser entonces también una palabra clave, de modo que la primera que no lo sea se rechaza como palabra clave desconocida.

sensitive merece una mención específica aquí, porque es un nombre mucho más plausible para un campo real escrito por un desarrollador que las demás palabras clave específicas de Aggrega. Un esquema que de verdad necesita una propiedad llamada sensitive — un componente cuyos values exponen un indicador sensitive propio, por ejemplo — debe declarar explícitamente el ámbito que la contiene, exactamente como lo haría para una propiedad llamada type o default. Lo consigue la forma explícita de más abajo o $mode: jsonschema en el ámbito que la contiene: con $mode: jsonschema todo el nodo se lee como JSON Schema escrito por el autor, donde sensitive es contenido ordinario y no la palabra clave de la forma compacta.

Para los esquemas que necesitan una propiedad con el nombre de una palabra clave reservada (p. ej., un contrato de Component con un campo description: escrito por el desarrollador, o un campo type:, o un campo default:), usa la forma explícita para el ámbito en cuestión:

spec:
schema:
values:
type: object
properties:
description: { type: string } # property named "description"
type: { type: string } # property named "type"
default: { type: string } # property named "default"
required: [description, type]
additionalProperties: false

La forma explícita evita el despacho — properties: enumera los hijos explícitamente, así que la colisión de palabras clave no se produce.

Esta restricción se aplica en cada ámbito en forma inferida, de forma recursiva. Un objeto anidado en forma inferida que contiene una propiedad con el nombre de una palabra clave reservada se lee como una hoja de restricción en ese ámbito. La solución es la misma: cambiar el ámbito en cuestión a la forma explícita.

Referencias

Las referencias toman de JSON Schema el $ref: en lo sintáctico y en lo semántico:

resources: { $ref: "#/$defs/PodResources" }
auth: { $ref: "Datastores#/schemas/MariaDBAuth" }
secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }

Los bloques $defs: dentro de un esquema en forma compacta declaran definiciones reutilizables. Cada entrada es a su vez un esquema en forma compacta (o JSON Schema, o mixto). Se hace referencia mediante el fragmento JSON Pointer #/$defs/<Name>:

Declara el bloque dentro del pilar cuyos campos hacen referencia a él, junto a esos campos — no junto al pilar. Un bloque schema: solo acepta en su propio nivel superior los nombres de los tres pilares de datos, así que un $defs: escrito como hermano de values: se rechaza cuando se carga la entidad, con un error que nombra la clave en cuestión y el conjunto de pilares que el bloque puede contener. El puntero se escribe #/$defs/<Name> en ambos casos.

$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources: { $ref: "#/$defs/PodResources" }

Para las referencias entre documentos que apuntan a entradas de SchemaLibrary, consulta cross-document-ref.md. Para la expansión de la forma abreviada de las URI OCI, consulta uri-grammar.md.

Apuntar una referencia a una definición, no a una propiedad

Un puntero que nombra una entrada $defs: — #/$defs/PodResources — es la forma a la que recurrir. Un puntero es válido allí donde JSON Schema lo permite, así que un puntero a una propiedad declarada también se acepta y se aplica, pero se informa con menos precisión, y conviene conocer la diferencia antes de escribir uno.

Un campo cuya forma procede de una entrada $defs: se comprueba campo por campo: un fallo se informa en la ruta del valor que realmente es incorrecto, y se informa cada fallo bajo ese campo, no solo el primero.

$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
primary:
resources: { $ref: "#/$defs/PodResources" }

Un cpu incorrecto aquí se informa en primary.resources.requests.cpu.

Un campo cuya forma procede de un puntero a una propiedad declarada se comprueba como parte del documento en su conjunto. Las restricciones siguen aplicándose y un documento que las infringe sigue deteniéndose — pero el fallo se informa en el campo que lleva el puntero en lugar de en el valor que contiene, y cuando varios de esos campos son incorrectos a la vez solo se nombra uno de ellos.

primary:
resources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
secondary:
resources: { $ref: "#/properties/primary/properties/resources" }

Un cpu incorrecto bajo secondary se informa en secondary.resources.

Ambas formas de escritura aceptan y rechazan los mismos documentos, salvo por un límite sobre format indicado en Formatos con nombre: a través del puntero, un format dentro de una rama anyOf, oneOf o not de la forma no se comprueba. Por lo demás, lo que cambia es cuánto te dice el mensaje, lo que importa sobre todo en un editor, donde el marcador se coloca a partir de esa ruta. Lo mismo se aplica a una entrada $defs: cuyo propio puntero vuelve a salir hacia las propiedades: alcanzar una definición a través de ella hereda el informe menos preciso.

Forma condicional mediante when:

JSON Schema 2020-12 expresa la forma condicional mediante if/then/else. La forma compacta proporciona when: como abreviatura más directa: un predicado de plantilla Go que, si es verdadero, aplica el resto de las restricciones del nodo; si es falso, el nodo se trata como si sus restricciones no existieran.

secondary:
$ref: "#/$defs/NodePool"
when: '{{ eq $.architecture "replication" }}'
required: true
properties:
replicaCount: { type: integer, min: 2 }

El predicado se evalúa sobre los valores de la instancia del padre. $ se refiere al ámbito de objeto circundante. Cuando architecture es replication, las restricciones (required: true, el replicaCount: min: 2 adicional) se aplican además del NodePool referenciado. Cuando architecture es standalone, esas restricciones están inactivas.

El predicado tiene acceso a las funciones estándar de las plantillas Go (Sprig). El compilador compila when: al if/then/else de JSON Schema más un envoltorio que evalúa el predicado de plantilla Go antes de que se ejecute la validación. El determinismo se conserva porque el predicado es puro respecto a la instancia.

Validación personalizada por campo mediante validate: y validateMessage:

Algunas restricciones no se pueden expresar con min / max / pattern / enum. Para ellas, la forma compacta proporciona validate: — un predicado de plantilla Go que, si es falso, detiene la validación con un error personalizado.

db_size:
type: string
pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$"
validate: '{{ regexFind "^[0-9]+" . | atoi | lt 100 }}'
validateMessage: "db_size must exceed 100 in its declared unit"

El predicado se ejecuta sobre el valor del campo (accesible como .); el ámbito de objeto circundante es $. Si el predicado devuelve false, la validación produce un error usando validateMessage: (o un mensaje predeterminado si no se proporciona).

validate: cubre casos que van más allá del vocabulario estándar de JSON Schema: la validación semántica personalizada (comprobación del formato semver, contenido JSON de una cadena), las reglas entre campos pero de ámbito estrecho en las que la restricción de un campo depende de un hermano, y las restricciones que no justifican un bloque assertions: completo.

validate: se diferencia de when: en su papel: when: determina si las restricciones se aplican; validate: es en sí mismo una restricción.

Para las reglas realmente entre campos de ámbito amplio, en las que ningún campo concreto es «el que se valida», usa el bloque dedicado assertions:. Consulta templates/assertions-block.md.

Declarar una hoja sensible — sensitive:

Una hoja de values, infra o provides puede declarar que el dato que describe contiene material secreto:

spec:
schema:
values:
origin:
type: string
required: true
sensitive: true
description: "The credential material itself."
key:
type: string
default: value
description: "The data key the material is stored under."

sensitive: true se compila a la palabra clave de extensión x-aggrega-sensitive: true en ese nodo del JSON Schema resuelto, junto a las demás anotaciones x-aggrega-*. El compilador la lee para derivar qué vinculaciones de un despliegue manejan material declarado sensible, y lleva ese hecho derivado en el grafo compilado.

Decláralo en el dato, no en su localizador. La distinción es todo el sentido de la palabra clave y es fácil invertirla. El material de una credencial es sensible; el nombre del recurso que lo contiene y la clave de datos dentro de ese recurso no lo son — ambos son públicos, y ambos se renderizan en claro en cada consumidor que hace referencia al recurso. Marcar un localizador afirma algo falso sobre él y propaga ese error a todo lo que, aguas abajo, lee la declaración. En el ejemplo anterior, origin está marcado y key deliberadamente no.

La afirmación complementaria — lo que sea que se enlace a este punto maneja material secreto, independientemente de lo que el relleno declare sobre sus propias hojas — no es en absoluto una declaración de hoja. Es sensitive en un slot de asociación; consulta entities/component.md «Attachment Slots (Slots de asociación)».

Declarar un objeto entero sensible

La palabra clave puede estar en un objeto en lugar de en un escalar, y entonces cubre todo lo que hay bajo ese objeto — los hijos del propio objeto y cualquier cosa anidada más abajo. Es la declaración a la que recurrir cuando todo un bloque es material y marcar cada hoja por separado dejaría sin marcar la siguiente hoja que alguien añada.

Los hijos del objeto deben estar en un bloque properties: explícito. Este es el único lugar en el que la forma inferida de los objetos no sirve, y conviene conocer el motivo en lugar de sortearlo:

spec:
schema:
values:
credentials:
type: object
sensitive: true
properties: # required here
username: { type: string }
password: { type: string }

Escribir los hijos directamente junto al marcador, como la forma inferida de los objetos permite en cualquier otro lugar, se rechaza en tiempo de compilación — el primer hijo se informa como palabra clave desconocida, situada en la propia clave del hijo:

values:
credentials:
type: object
sensitive: true
password: # refused: unknown keyword "password"
type: string

El rechazo es correcto, no una limitación que sortear. Un nodo se lee como hoja de restricción en cuanto lleva una palabra clave de la forma compacta, y sensitive: lo es — así que a partir de ese punto cada clave hermana tiene que ser también una palabra clave, y password no lo es. El bloque properties: es lo que dice «las claves de abajo son nombres de propiedades, no más palabras clave», y es la misma desambiguación que describe Forma inferida y forma explícita de los objetos. Leer el diagnóstico como «el marcador no puede ir en un objeto» es la mala interpretación que hay que evitar: sí puede, y el bloque es la forma de decirlo.

Una hoja dentro de un objeto declarado no necesita marcador propio. Añadir uno es inofensivo y no dice nada nuevo, ya que la declaración del objeto ya la cubre.

Lo que la palabra clave no hace

El nombre invita a suposiciones que la palabra clave no justifica, así que conviene enunciar su techo con claridad:

  • No cifra nada. Es una anotación sobre una declaración, no un mecanismo de confidencialidad.
  • No valida ni rechaza, salvo donde se rellenan los parámetros de una plantilla de CloudFormation. Ningún valor se acepta o se rechaza porque una hoja esté declarada sensible, y ningún resultado de la compilación cambia — salvo que, donde el valuesMapping de una Recipe o de una FeatureRecipe de CloudFormation lee una hoja declarada sensible para rellenar los parámetros de una plantilla obtenida de una fuente, cada literal que ese mapping vincula detiene la compilación, de modo que dos compilaciones que solo difieren en la declaración pueden terminar de forma distinta. Consulta A secret bound to a CloudFormation parameter would be written into the template (Un secreto asociado a un parámetro de CloudFormation se escribiría en la plantilla).
  • No garantiza que la salida renderizada esté libre de material. Que un artefacto contenga material depende de qué relleno haya vinculado un autor y de lo que el autor haya escrito en sus values — consulta architecture/08-credential-model.md «What the compiler does and does not guarantee (Qué garantiza el compilador y qué no)». Un valor declarado sensible que un autor proporcionó en línea se renderiza exactamente igual que uno no declarado, dondequiera que la compilación lo renderice.
  • No impone un mecanismo de entrega. No puede convertir un valor en línea en una referencia a un almacén, y no restringe lo que permite la lista de permitidos inject de un slot.
  • No detiene una compilación, salvo mediante ese rechazo de CloudFormation. Los avisos que emite en tiempo de compilación, descritos más abajo, son advertencias: la compilación se ejecuta hasta el final y escribe sus artefactos. Hacer fatal un aviso es una elección de cada organización, expresada como una política de gobernanza vinculada a la compilación, no algo que la palabra clave haga por sí sola. El rechazo del proveedor de CloudFormation descrito arriba es la excepción: detiene la compilación, porque un literal escrito en una plantilla es legible por cualquiera que pueda leer el stack.
  • No cambia ningún byte renderizado en la mayoría de los destinos, y en ellos nunca lo hará. Una plataforma de destino que tiene una noción propia de sensibilidad es donde una declaración tiene dónde aterrizar; un destino que no la tiene no ofrece nada que ella pueda cambiar, de forma permanente. Terraform es el único destino de la biblioteca estándar que tiene una primitiva así: donde la entrada de un módulo vendorizado recibe material que un autor declaró sensible, la salida renderizada gana un archivo de sobrescritura generado que establece el atributo de sensibilidad propio de Terraform para esa entrada — consulta providers/terraform.md «Declared-sensitive module inputs (Entradas de módulo declaradas sensibles)». En cualquier otro caso, declarar una hoja sensible en un catálogo existente deja idéntico cada artefacto renderizado.

Qué cambia en lo que imprime la herramienta

Lo único que una declaración sí cambia es lo que la herramienta imprime para que lo lea una persona: su salida de depuración y el texto de un rechazo, descrito más abajo. En las superficies de depuración, un valor declarado sensible se sustituye por el texto fijo <redacted>:

  • la traza por pasada que aggrega build --trace escribe en .trace/;
  • el bloque Values: por nodo que aggrega inspect imprime para un Aggregate;
  • el bloque de vinculaciones por hoja que aggrega inspect imprime para una Release resuelta.

La clave siempre se conserva y solo se sustituye su valor, de modo que quien lee sigue viendo que la hoja está escrita y que algo se ha ocultado. Una hoja que el autor no declaró imprime su valor literalmente junto a una hermana oculta — la sustitución sigue a la declaración y a nada más, así que un campo llamado password que no lleva ninguna declaración se imprime, y un campo declarado llamado key no.

Una declaración alcanza cada hoja que hay bajo ella, y alcanza las tres superficies de la misma manera. Donde la declaración está en un objeto, cada valor anidado dentro de ese objeto también se oculta, a cualquier profundidad — la declaración del objeto los nombra, así que ocultarlos no afirma nada que el autor no haya escrito. La coincidencia se hace sobre segmentos de ruta completos y no sobre el texto, de modo que una hermana cuyo nombre simplemente empieza por un nombre declarado no se toca: declarar dbPassword no oculta dbPasswordHint.

La ocultación de la traza se puede desactivar para una sola compilación, cuando el valor oculto es precisamente el que se está depurando: aggrega build --trace --trace-unredacted escribe los valores en los archivos de traza y marca cada uno de esos archivos con una cabecera que lo indica. Es una elección en el momento de la invocación sin ningún ajuste de configuración, solo alcanza a la traza, y está documentada con cli/aggrega-build.md «Showing the withheld values (Mostrar los valores ocultos)». Los layouts de aggrega inspect tienen la suya, --unredacted, documentada con cli/aggrega-inspect.md «Showing the withheld values (Mostrar los valores ocultos)».

Los límites de ese comportamiento importan más que el comportamiento en sí.

Los artefactos renderizados nunca se enmascaran. Todo lo que está bajo dist/ se emite exactamente como lo produjo el renderizado, porque es lo que se despliega: un marcador de posición escrito en un manifiesto sería un despliegue roto en lugar de uno protegido. El enmascaramiento cubre lo que la herramienta imprime, nunca lo que escribe. Leer una declaración como la promesa de que dist/ es seguro de publicar es la única interpretación errónea que hay que evitar — el techo descrito arriba no cambia, y dist/ sigue siendo tan sensible como la vinculación que más material lleva.

Hay una cosa que una declaración puede añadir a un artefacto renderizado, y no es enmascaramiento: donde un destino tiene una primitiva de sensibilidad propia, la declaración se renderiza en ella. El valor se sigue escribiendo completo — nada se oculta ni se sustituye — y lo que gana el artefacto es la marca propia del destino junto a él, de modo que las herramientas del destino puedan tratar el valor como el autor lo declaró. Terraform es el destino que ofrece una hoy, y lo que su atributo garantiza y no garantiza está en providers/terraform.md «Declared-sensitive module inputs (Entradas de módulo declaradas sensibles)». Esa marca solo viaja allí donde la identidad del nombre renderizado se recupera de la propia declaración; donde una plantilla inventó el nombre, la marca está ausente en lugar de aproximada, porque marcar un valor que el autor no declaró afirmaría algo falso sobre él. Donde esa plantilla es un valuesMapping — el de una Recipe, o el de la FeatureRecipe de una Feature vinculada a un componente — la compilación lo indica, como se describe más abajo.

El enmascaramiento alcanza lo que una declaración nombra, más lo que se ve leer a una plantilla. Una hoja declarada en un pilar values o infra, y una clave de entrega que lleva material de una clave provides declarada sensible, se identifican ambas por su nombre y se ocultan. Un valor que una plantilla calculó queda bajo una clave que nadie declaró, así que lo que lo identifica es, en cambio, la referencia que escribió el autor: en la traza, una entrada locals: o un campo source: cuya plantilla lee una hoja declarada sensible queda oculto, y también una entrada locals: que lee una hermana ya oculta. La lectura es deliberadamente prudente — alcanzar un objeto entero alcanza cada hoja declarada bajo él, y una plantilla que transmite la totalidad de sus datos las alcanza todas — así que una referencia que no puede resolverse oculta en lugar de imprimir.

Un documento renderizado se muestra como un nuevo renderizado, y lo indica. El Workload analizado de la traza es un documento que produjo la plantilla de la Recipe: nada en él registra de qué declaración procede cada carácter, así que no hay ninguna clave en la que sustituir dentro de él, y recuperar el vínculo campo por campo significaría inspeccionar el contenido de un valor, algo que el compilador no hace. Lo que la traza muestra en su lugar es la misma plantilla workload: evaluada de nuevo contra un contexto cuyos datos declarados sensibles ya se leen como el texto de sustitución, anunciado en una entrada workload_note junto al documento. Como la plantilla ve una cadena donde había una cadena, el nuevo renderizado conserva la forma del documento emitido y el texto de sustitución ocupa la posición propia del dato oculto. Quedan dos diferencias y la nota indica ambas: una plantilla que se ramifica según el contenido de un valor se renderiza de otra forma contra el texto de sustitución, y un dato que el eje no nombra se transmite sin cambios. Es una vista de depuración de lo que se renderizó, nunca una copia.

Los valores de un nodo consumido se ocultan según las declaraciones de ese nodo, en las dos superficies a las que la arista los lleva. Una vista de una arista uses reproduce lo que publicó un componente de destino, así que la rige el esquema propio del destino: una clave provides que el destino declaró sensible queda oculta en la traza del consumidor incluso cuando el consumidor no declara nada. Donde el propio bloque inject de la arista enruta esa clave hacia una clave de entrega del componente consumidor, esa clave de entrega también queda oculta: la misma regla que sigue el mapeo inject de una vinculación, leyendo la misma declaración, de modo que los dos cableados no pueden discrepar. Los layouts de aggrega inspect muestran los pilares propios de un nodo y sus vinculaciones, no los valores publicados de un nodo consumido, así que allí nada lleva una vista entre nodos que ocultar.

Una vinculación escrita en una conexión se oculta según las declaraciones de su propia Feature, en cada superficie que la muestra. La traza la muestra bajo la vista de la arista uses de esa conexión, en .context.uses.<alias>.features.<slot>, y aggrega inspect la imprime bajo la línea de la conexión en una Release resuelta. En ambas, una hoja values o infra que su Feature declara sensible se oculta exactamente igual que en la misma Feature vinculada directamente al componente, y en la traza también se oculta una clave del provides resuelto de la vinculación que la Feature declara sensible. Su tipo, su versión, sus etiquetas y cada hoja y clave provides no declaradas se imprimen literalmente, de modo que un localizador publicado sigue siendo legible junto al material que localiza. Un slot que declara sensitive: true, en el componente o en un socket, marca la vinculación como manejadora de material secreto y no oculta ninguna hoja por su cuenta: qué hojas se ocultan le corresponde declararlo a la Feature.

Las proyecciones legibles por máquina son literales por contrato, y necesitan el mismo tratamiento que los archivos de los que proceden. aggrega inspect --raw emite una entidad exactamente como se escribió, y aggrega inspect --output yaml reproduce la entidad escrita para cada tipo, una Release incluida. Ninguna de las dos sustituye nada, y es deliberado: son las salidas que un script analiza y que un diff compara, así que una salida que ocultara en silencio una parte de sí misma representaría de forma errónea la entrada que dice reproducir y rompería el viaje de ida y vuelta del que dependen sus consumidores. Declarar sensible una hoja no basta para mantenerla fuera de esas salidas: canalízalas, guárdalas y compártelas como harías con el Aggregate y la Release mismos.

El grafo compilado es la única proyección legible por máquina que sí oculta, dondequiera que se entregue. --ir-graph, en aggrega inspect, aggrega validate y aggrega build, escribe el grafo que resolvió la ejecución como JSON junto a lo que el comando ya produce, y aggrega/irGraph del daemon responde a un editor con el mismo grafo; en cada caso, un valor que un autor declaró sensible se sustituye exactamente igual que en los layouts legibles. --unredacted junto a --ir-graph imprime en cambio esos valores, y lo mismo hace el campo unredacted de la solicitud al daemon. Así, el grafo leído desde un comando y el grafo leído a través del protocolo del daemon son el mismo documento bajo la misma regla de tratamiento, y una pipeline o un cliente que necesite los valores escritos tiene que pedirlos.

Qué dice un rechazo sobre un valor declarado

Un rechazo generado por una plantilla que lee un valor que un autor declaró sensible no lleva ese valor. Cuando una plantilla detiene la compilación — una aserción que llama a fail, una expresión que no puede evaluarse, una salida que no se lee como el documento que la plantilla debe producir — y una de sus referencias alcanza un dato declarado sensible, lo que se informa procede de evaluar la misma plantilla una segunda vez, contra un contexto en el que cada dato declarado sensible ya se lee <redacted> — salvo que la plantilla se haya detenido en una frase que ella misma escribe completa, el primer caso de abajo:

assertion failed: the admin password <redacted> must be supplied as a reference
  • Un fail cuya frase está escrita completa en la plantilla se informa tal como está escrita. Cuando la llamada que detuvo la compilación es fail con una única cadena entre comillas — fail "…", sin nada canalizado hacia ella ni nada compuesto en su frase —, el rechazo lleva esa frase sea cual sea el contenido del valor y cualquiera que sea la rama que llevó a la llamada, porque la frase no cita nada de lo que leyó la plantilla: una aserción que rechaza un origen con la forma incorrecta muestra su propia explicación de la forma. Una frase construida de cualquier otra manera — printf, un campo, una variable, un valor canalizado hacia fail — se informa según los casos que siguen.
  • Donde la segunda evaluación falla en la misma expresión por el mismo motivo, se informa de su fallo. La propia frase del autor se conserva con <redacted> donde estaba el valor, y un valor que la plantilla codificó, entrecomilló o transformó de otro modo también se oculta, porque la sustitución ocurre antes de la transformación.
  • Donde no lo hace, el rechazo nombra la expresión que falla y dice que su texto está oculto. Se trata de una plantilla cuyo comportamiento dependía de lo que contiene el valor — tomó otra rama, o falló en otro lugar, contra el texto de sustitución — así que nada de lo que compuso puede mostrarse. Para que un rechazo así se explique por sí mismo, escribe su frase completa en la llamada a fail, como describe el primer caso. El rechazo sigue deteniendo la compilación, y conserva su código.
  • Un Workload renderizado que el esquema del Workload rechaza se redacta a partir del esquema. Los campos del documento no llevan ningún vínculo de vuelta a los datos que leyó su plantilla, así que, donde esa plantilla leyó un dato declarado sensible, cada hallazgo que podría citar un valor enuncia en su lugar la restricción, con <redacted> en el lugar del valor y un aviso que explica por qué. No se da ningún consejo derivado del valor, y un hallazgo que no cita ningún valor — una clave que falta, una clave que el Workload no admite — se lee como siempre:
.containers.main.imagePullPolicy: against /$defs/container: enum: <redacted> does not satisfy enum ["Always","Never","IfNotPresent"] (the value is withheld because the template that rendered this document reads a value declared sensitive)
  • Una entrada with de un paso de la pipeline rechazada por el contrato de entrada declarado del paso se redacta a partir del contrato donde la plantilla with lee un dato declarado sensible: cada posición que falla en la entrada y la palabra clave del esquema que la rechazó, seguidas de un aviso que explica por qué, y nada de lo que llevaba la entrada.
  • Un rechazo que nombra una coordenada source: se redacta a partir de lo que nada declarado produjo donde una plantilla source: produjo esa coordenada leyendo un dato declarado sensible: la fuente no está en el lockfile ni en la caché, su archivo en caché no coincide con lo que registra el lockfile, o el pin registrado junto a la entidad no concuerda con el lockfile. Cada línea que imprime un rechazo así nombra las coordenadas que usó la búsqueda, así que nombra la fuente por su url y por la versión o la referencia en la que se pidió — donde las había leído — con <redacted> en lugar de cada una que produjo una plantilla así, y dice que su motivo está oculto. Conserva su código y la solución que la compilación da para ese código:
source-artifact https://example.com/fragments/app.yaml@<redacted>: the reason is withheld: the template producing this source reads a value declared sensitive, and the reason names what the template produced

Lo que cuenta como declarado es lo que nombran las declaraciones, en cada parte del contexto que una plantilla puede leer: los values y los infra propios del componente, las Features vinculadas a él y a cada una de sus conexiones, una clave de entrega que lleva material declarado, una clave provides que su Component declara sensible, cada entrada de una lista que lleva el contexto, descrita más abajo, y una entrada locals: calculada a partir de cualquiera de ellos. Una plantilla que no lee ninguno de ellos informa exactamente como lo haría sin ninguna declaración en ningún lugar, byte a byte, así que solo un rechazo generado por una plantilla que leyó un valor declarado se informa de otra forma. La lectura es la misma que usa la traza, obtenida de las referencias que escribe una plantilla: alcanzar un objeto entero alcanza cada hoja declarada bajo él, así que puede ocultar texto que no contenía ningún valor. Una plantilla que transmite la totalidad de sus datos de una vez — el punto o $ sin nada después, pasado a una función como toJson, impreso, o pasado a una plantilla que invoca por su nombre — lee cada valor declarado que contienen, así que su rechazo se informa de la misma manera; dentro de un cuerpo range o with el punto es el valor que ese cuerpo itera o nombra, y transmitirlo solo lee lo que contiene ese valor. Nada de esto depende de --trace-unredacted: ese flag solo alcanza los archivos de traza, y un rechazo se lee igual con y sin él.

Un valor declarado se oculta dondequiera que esté, también dentro de una lista. Las entradas de una misma lista las rigen entidades distintas, y cada entrada se oculta según las suyas. En la vista .boundary que lee una FeatureRecipe de ámbito de límite, cada conexión listada en internal_uses_edges, outgoing_cross_boundary_uses_edges, incoming_cross_boundary_uses_edges y cross_boundary_uses_edges lleva los provides que publica su destino, ocultos donde el Component del destino declara sensible la clave, y cada entrada de feature_attachments lleva los infra de esa vinculación, ocultos donde su Feature declara la hoja. En el contexto de una Feature vinculada a un componente, cada entrada de .context.used_by lleva lo que publica el componente que se conecta, oculto donde el Component del componente que se conecta declara la clave. La misma clave en una entrada cuya entidad no declara nada se cita tal cual, y una entrada locals: calculada a partir de una entrada oculta se oculta con ella. Recorrer una lista, o alcanzar una de sus entradas mediante index, lee la lista entera, así que cuenta como leer lo que lleva cada entrada:

error calling fail: target secret_ref "<redacted>" must start with ref-

Eso alcanza el texto de un rechazo que genera la compilación. Lo que se le dice a un proveedor sobre qué parte de su entrada procede de un valor declarado — los valores que produjo un valuesMapping, un documento workload: renderizado, cada entrada artifacts:, cada campo de una entrada omits: — no cuenta un valor leído desde dentro de una lista, así que el tratamiento propio que un proveedor da a un valor declarado, incluido el rechazo de CloudFormation de un literal asociado descrito arriba, no alcanza a ninguno.

Algunos rechazos quedan fuera de esto. El texto que escribe un plugin — el rechazo propio de un proveedor o de un paso de la pipeline — es la frase del plugin, transmitida tal como el plugin la escribió. Una plantilla evaluada fuera de las aserciones de la compilación y de su renderizado — la interpolación de parámetros y las comprobaciones de parámetros en un Aggregate, las plantillas when: y validate: de un esquema, y la resolución de una coordenada source: que registra su pin — informa de su fallo tal como falló.

El aviso de compilación para un valor que viaja como literal

Una compilación imprime un aviso por cada clave de entrega que lleva material declarado sensible como valor literal. Se dispara cuando el bloque inject de una vinculación enruta una clave provides que la Feature de la vinculación declaró sensible hacia una clave de entrega del componente consumidor, y el valor se entrega realmente:

warning: node "db" (provider "helm"): attachment "user_password" delivers a value
declared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where the
target supports it, fill the slot with an attachment that delivers a reference instead

Tres cosas sobre él son deliberadas.

Informa de cómo viaja un valor, no de que algo esté mal. Entregar un literal es con frecuencia lo único que un destino acepta, y existe toda una familia de vinculaciones para hacer exactamente eso. El aviso le dice a un autor qué valor toma esa ruta y dónde, de modo que la elección sea visible en lugar de implícita; no afirma que la elección sea un error.

Es una advertencia y nunca una detención. La compilación tiene éxito y escribe sus artefactos sin cambios. Una organización que quiera que una credencial entregada como literal haga fallar la compilación lo expresa como una política de gobernanza sobre la compilación, que es donde corresponde un rechazo — una regla que algunos despliegues tienen que romper no es un comportamiento predeterminado del compilador.

Se decide a partir del cableado, nunca del valor. El aviso lee la sensibilidad que declaró un esquema más la entrega que escribió el autor. No se inspecciona ningún valor, así que nunca se supone que un campo sea una credencial por su nombre o su contenido, y un valor no declarado que resulta contener una contraseña no genera nada.

Dos casos se quedan deliberadamente en silencio. Una clave de entrega cuya clave provides referenciada no publica nada no entrega ningún literal y no informa de nada — el aviso sigue a una entrega que ocurrió. Y un slot cuya lista de permitidos inject está vacía deja la entrega a la Recipe, así que el autor no escribió ninguna clave de entrega de la que informar y no tiene nada sobre lo que actuar.

El aviso es una clase propia, identificada por su propio código, y --no-unsupported-field-warnings no lo silencia: ese flag cubre las notificaciones de fidelidad de un destino, que son un juicio distinto silenciado por motivos distintos. También llega al editor, donde aparece como un problema en el Aggregate, siempre que el servidor de lenguaje se ejecute con --build-on-inspect (o la clave de configuración serve.build_on_inspect) activado. Ese ajuste está desactivado por defecto por coherencia con aggrega inspect: el comando de terminal nunca llega a la etapa de renderizado mientras inspecciona un grafo, así que tampoco genera un aviso así, y una inspección en el editor que tampoco genera ninguno te muestra lo mismo que el terminal. Activar el ajuste es la forma de pedir al editor la capa adicional, y no se escribe nada en disco cuando lo haces — la etapa se ejecuta y sus artefactos se descartan. Añade los avisos que genera una compilación al renderizar, y ninguna de las comprobaciones en las que una compilación se detiene. Cada problema publicado nombra la capa que lo generó, de modo que un editor puede mantener este aviso separado de los que informan las etapas de resolución y de análisis.

El aviso de compilación para un valor que un mapeo renderiza sin marca

Una compilación imprime un aviso por cada hoja values declarada sensible cuya marca un renderizado no puede llevar mientras el autor todavía tiene la palanca sobre ella. Se dispara en un renderizado desde un source: cuyos valores son la salida de un valuesMapping — el de una Recipe, sobre una hoja que declara su Component, o el de la FeatureRecipe de una Feature vinculada a un componente, sobre una hoja que declara esa Feature. Las claves de salida del mapeo son invención suya, así que ninguna declaración nombra ninguna de ellas y el destino no recibe ninguna marca por clave para la hoja:

warning: node "api" (provider "terraform"): attachment "token": "values.token" is declared
sensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMapping
whose output keys no declaration names, so the target receives no per-key sensitivity
marking for it; ...

La línea nombra la hoja en su coordenada escrita y la Recipe o la FeatureRecipe cuyo mapeo condiciona la unión, porque la declaración y el mapeo se escriben en dos entidades distintas; la línea de una vinculación empieza con el nombre bajo el que está vinculada, de modo que se distinguen dos vinculaciones de una misma Feature en un mismo componente. Quitar el mapeo es la palanca: sin uno, los valores que recibe un renderizado desde una fuente están indexados por las rutas de las hojas declaradas, y la marca viaja con ellos. Un renderizado solo de artefactos y un renderizado solo de workload se quedan en silencio, porque no entregan a su destino ningún mapa de valores, y lo mismo ocurre con una Feature vinculada a un límite, que se renderiza contra un pilar values vacío — el techo descrito arriba es permanente allí, y una advertencia no nombraría nada que hacer. Como el aviso para un valor que viaja como literal, es una advertencia y nunca una detención, no cambia ningún byte renderizado, es una clase propia con su propio código, sensitivity-not-conveyed, y --no-unsupported-field-warnings no lo silencia. Advertencias y salida del linter recoge su forma completa.

Dónde se lee la declaración, y dónde no

La palabra clave se lee en el nodo en el que está, y la lectura sigue después cada vía por la que una declaración puede alcanzar ese dato: mapas de propiedades anidados, cada rama de composición y el destino de un $ref. Una rama y un destino de referencia se componen ambos sobre la propiedad que los lleva, así que una declaración encontrada a través de cualquiera de ellos se recoge para esa propiedad; solo un descenso por properties extiende la ruta.

Un marcador se lee tanto si está junto a una de esas palabras clave como si está dentro de lo que la palabra clave alcanza, así que dos formas no necesitan una colocación deliberada:

  • Junto a un $ref, o dentro del destino de la referencia. Un marcador en la hoja que hace la referencia declara esa hoja. Un marcador en el esquema referenciado también se recoge para la hoja que hace la referencia, en la ruta de esa hoja más la cadena que hay debajo — nunca en una ruta dentro de la definición, donde no vive ningún valor escrito.
  • Junto a una palabra clave de composición (allOf / anyOf / oneOf), o dentro de las properties propias de una rama. Una rama se compone sobre el objeto que la lleva, así que se desciende por cada rama — incluidas las ramas condicionales de un nodo escrito como JSON Schema — y una declaración dentro de una de ellas se recoge en la ruta propia de la propiedad que compone más su cadena.

Una forma sí necesita que el marcador se coloque deliberadamente:

  • En la propia hoja array, no en su tipo de elemento items. Un array cuyos elementos llevan material se declara sensible en el array, porque un tipo de elemento no es un mapa de propiedades y no se desciende a él.

parameters: es un vocabulario distinto

sensitive no forma parte del vocabulario del contrato tipado de parameters:. Un Aggregate que lo declara en una entrada de parámetro se rechaza cuando se carga el Aggregate, con un diagnóstico del sobre del documento que informa de unexpected property: "sensitive" situado en la propia clave infractora — el mismo trato que recibe cualquier clave fuera de ese vocabulario, ya que el contrato de parámetros es un objeto cerrado.

La asimetría es deliberada: el eje de sensibilidad cubre los tres pilares de datos que declara una entidad de catálogo, y un parámetro es una entrada del contrato de entorno y no una hoja de pilar. Elevar material de credenciales a través de un parámetro está documentado en architecture/08-credential-model.md «Legacy charts that demand a formatted string (Charts heredados que exigen una cadena con formato)», que expone la contrapartida que asume esa vía.

Composición con allOf, anyOf, oneOf

Las palabras clave de composición funcionan como en JSON Schema:

# Inherit and extend
secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }
# Disjunction (one of several shapes)
auth:
oneOf:
- existingSecret: { type: string, required: true }
- rootPassword: { type: string, required: true }
username: { type: string, default: app_user }
password: { type: string, required: true }

El compilador emite las mismas palabras clave de composición en el JSON Schema resuelto. Cada una de las entradas que componen puede ser forma compacta, JSON Schema o referencias $ref:. Se admite la mezcla dentro de una composición.

La vía de escape — $jsonschema:

Para los casos que van más allá del vocabulario de la forma compacta ($dynamicRef, unevaluatedProperties, composición not: profunda, tipos recursivos), cualquier nodo puede pasar a JSON Schema completo:

values:
architecture: { type: string, enum: [standalone, replication] }
some_complex_field:
$jsonschema: |
type: object
unevaluatedProperties: false
allOf:
- $ref: "#/$defs/Foo"
- not:
required: [conflicting_field]
patternProperties:
"^x-": { type: string }
$defs:
Foo:
type: object
properties:
name: { type: string }

El bloque $jsonschema: contiene YAML de JSON Schema; el compilador lo trata como un paso transparente — el contenido va directamente al documento JSON Schema resuelto en la posición de ese nodo. La validación, el informe de errores y las herramientas trabajan todos sobre el documento resuelto; la vía de escape es puramente una comodidad de escritura.

Una rama not: puede llevar una description: que indique por qué se rechaza la forma que excluye. Un valor que coincide con esa rama se rechaza entonces con la descripción como motivo, impresa en una sola línea, en lugar de la redacción genérica «not allowed here (no permitido aquí)» — así que escríbela como la frase que debería leer el autor del valor rechazado. Solo se usa una descripción escrita en la propia rama not:; una en una entrada de $defs a la que la rama solo hace referencia, no.

Cada nodo dentro del bloque se lee como JSON Schema, y una palabra clave de la forma compacta escrita allí conserva su significado compacto (min: 3 en una cadena sigue siendo una longitud mínima). Un $ref en el bloque se resuelve como uno de fuera: #/$defs/Foo nombra una entrada del $defs: del pilar, así que el ejemplo declara Foo allí, y una referencia que nombra una entrada que nadie declaró se rechaza cuando se carga la entidad. $dynamicRef se resuelve contra un $dynamicAnchor, así que se puede escribir una forma recursiva; un valor que falla en lo profundo de la recursión se informa en el campo que lo contiene — tree.children, para un name incorrecto dos niveles más abajo en un árbol cuyos elementos children son { $dynamicRef: "#node" }.

Un límite se aplica a unevaluatedProperties y unevaluatedItems. Escrita en un nodo que también lleva una referencia, una palabra clave de composición (allOf, anyOf, oneOf), un condicional o un esquema dependiente, cualquiera de las dos se carga pero no se aplica — y unevaluatedItems tampoco se aplica junto a contains. En el ejemplo anterior, unevaluatedProperties: false está junto a allOf, así que { name: n, extra: 1 } se acepta aunque ni Foo ni patternProperties declaran extra.

La vía de escape $jsonschema: es por nodo, no por documento. Un esquema puede usar la forma compacta para las partes sencillas, la vía de escape a JSON Schema para el único campo complejo y $ref: para las formas compartidas — todo en un mismo documento.

Mezclar forma compacta y JSON Schema en un mismo documento

La forma compacta y JSON Schema pueden mezclarse libremente en cualquier límite entre nodos. La regla de despacho la determina la forma del contenido:

  • Un nodo que contiene $jsonschema: se trata como JSON Schema (la vía de escape).
  • Un nodo que contiene palabras clave de nivel superior al estilo de JSON Schema (type:, properties:, additionalProperties:, if:, etc.) se trata como JSON Schema (la forma explícita).
  • Un nodo que contiene solo entradas nombre de propiedad → esquema hijo (sin palabras clave reservadas de JSON Schema) se trata como forma compacta (forma inferida).
  • Un nodo con solo $ref: es un paso de referencia.
  • Un nodo con allOf: / anyOf: / oneOf: es una composición; cada entrada se despacha de forma independiente.

Para las hojas en forma compacta, el patrón estándar es field_name: { type: ..., constraints... } — un mapa YAML que contiene un vocabulario conocido de la forma compacta. El despacho reconoce los diccionarios de restricciones por sus claves.

Para el raro caso ambiguo (p. ej., un esquema en forma compacta con un campo llamado literalmente type que el despacho en forma inferida interpretaría como la palabra clave de JSON Schema), la forma explícita es la corrección canónica — consulta «Reserved keywords at every inferred-form scope (Palabras clave reservadas en cada ámbito en forma inferida)» más arriba.

Importar un contrato desde un archivo — $import:

Un contrato no tiene por qué estar dentro de la entidad que lo declara. $import: nombra un archivo del que leerlo:

spec:
schema:
$import: ./contracts/api-server.schema.yaml

Todo el spec.schema procede entonces de ese archivo, que se escribe exactamente igual que el bloque al que sustituye — los pilares arriba, forma compacta o YAML de JSON Schema debajo:

contracts/api-server.schema.yaml
values:
greeting: { type: string, enum: [hello, howdy], default: hello }
infra:
image_tag: { type: string, default: "1.0" }
provides:
host: { type: string }

Un solo pilar puede importarse por sí mismo, con sus hermanos escritos en línea junto a él:

spec:
schema:
values:
$import: ./contracts/values.yaml
infra:
image_tag: { type: string, default: "1.0" }

La misma forma funciona en el valueSchema: y el infraSchema: de un socket usesSchema:.

Las reglas que lo rigen:

  • $import: es la única clave en la posición en la que aparece. Un hermano escrito junto a él se rechaza, en lugar de descartarse uno de los dos.
  • Una ruta relativa se lee respecto al directorio que contiene el archivo de la entidad que la declaró, nunca respecto al directorio desde el que se ejecuta una compilación — la misma base que usan valuesMapping:, workload: y artifacts:. Debe quedarse dentro de ese directorio, porque cada archivo que lleva una publicación de la entidad se toma de allí: una ruta que sale de él, o una ruta absoluta, nombra un archivo que no viajaría con la entidad y se rechaza — consulta A path names content outside the entity’s own directory (Una ruta nombra contenido fuera del directorio propio de la entidad). Un esquema que comparten varias entidades pertenece a una SchemaLibrary, referenciada con $ref:.
  • El archivo importado viaja con la entidad. Una entidad publicada lleva cada archivo que su esquema importa, incluido cada archivo de una cadena, de modo que una copia obtenida de un registro lee el mismo contrato y valida los valores escritos contra él — consulta aggrega push.
  • El archivo importado lleva contenido de esquema, no un documento de entidad. Un archivo cuyo contenido no es un mapa YAML se rechaza, nombrando el archivo.
  • Un archivo importado puede ser a su vez un único $import:, que se resuelve de forma recursiva; una cadena que vuelve a un archivo que ya se está leyendo se rechaza, nombrando la cadena.

La importación se lee cuando se carga la entidad, así que cada superficie que lee esa entidad ve el mismo contrato: aggrega validate, una compilación, aggrega push, aggrega inspect y el editor. Un archivo que no se puede leer, o un contenido que no es un esquema, se rechaza en ese punto en lugar de dejar el contrato sin aplicar — y un push lo rechaza antes de que se publique nada.

$import: y $ref: no son intercambiables. $import: nombra un archivo y sustituye un contenido entero; $ref: nombra una entrada de SchemaLibrary por su identidad y se compone en cualquier nodo. Un valor $import: que lleva una identidad de biblioteca o un host de registro se rechaza con una indicación hacia $ref:. Consulta cross-document-ref.md.

Espacio de nombres de extensiones de Aggrega — x-aggrega-*

La forma compacta reconoce cualquier palabra clave con el prefijo x-aggrega- como una extensión específica de Aggrega. El espacio de nombres es abierto: las nuevas anotaciones entran en el catálogo sin ediciones del vocabulario palabra clave por palabra clave. Los autores que escriben x-aggrega-selector, x-aggrega-narrowed-from o anotaciones futuras hacen llegar su contenido al ámbito correcto del JSON Schema resuelto sin rechazo en tiempo de compilación.

El prefijo del espacio de nombres importa: una errata como x-agrega-source (falta una g) NO se reconoce como palabra clave de extensión y la rechazaría la semántica de objeto cerrado en los ámbitos en forma inferida. El ámbito del prefijo actúa como red de detección de erratas para la superficie de anotaciones del catálogo.

El compilador emite anotaciones x-aggrega-* concretas en puntos bien conocidos de la pipeline:

  • x-aggrega-selector: — emitida por la síntesis de usesSchema: y featuresSchema: para llevar la cadena del selector que apunta a los Components proveedores compatibles.
  • x-aggrega-sensitive: — emitida por una hoja que declara sensitive: true. Consulta Declarar una hoja sensible más arriba.

Los autores de catálogos que escriben sus propias palabras clave de extensión usan el mismo espacio de nombres; las herramientas posteriores que consumen el JSON Schema compilado leen las claves x-aggrega-* sin colisionar con el espacio de palabras clave propio de JSON Schema.

Ejemplo completo — esquema de Component de MariaDB

Un esquema de Component representativo en forma compacta para un almacén de datos MariaDB, que muestra la forma inferida en todo momento, restricciones de hoja mixtas, referencias, forma condicional y un oneOf completo para el bloque de autenticación:

spec:
schema:
values:
architecture:
type: string
enum: [standalone, replication]
default: standalone
description: |
Topology mode. `standalone` runs a single primary; `replication` runs a primary
plus N secondary replicas governed by the secondary block.
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources: { $ref: "#/$defs/PodResources" }
persistence: { $ref: "#/$defs/PersistenceSpec" }
secondary:
when: '{{ eq $.architecture "replication" }}'
properties:
replicaCount: { type: integer, min: 2, max: 8, default: 2 }
resources: { $ref: "#/$defs/PodResources" }
persistence: { $ref: "#/$defs/PersistenceSpec" }
auth:
oneOf:
- existingSecret: { type: string, required: true }
- rootPassword: { type: string, sensitive: true, required: true }
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }
database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }
metrics:
enabled: { type: boolean, default: false }
serviceMonitor:
enabled: { type: boolean, default: false }
namespace: { type: string }
labels: { type: object, valuesType: string }
$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
PersistenceSpec:
size: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$", required: true }
storageClass: { type: string }

Escrito como YAML de JSON Schema, el mismo contrato detalla en cada objeto type: object, properties: y additionalProperties: false, y enumera de nuevo cada campo obligatorio en el required: de su padre, así que resulta bastante más largo. La ganancia en compacidad se acumula en contratos de Component más grandes y es lo bastante significativa como para hacer de la forma compacta la superficie de escritura predeterminada para schema:, parameters: y las entradas de SchemaLibrary.

Referencias cruzadas

  • Para la semántica de resolución de $ref: entre documentos (la sintaxis de required: junto a una referencia entre documentos; la expansión de cadenas de biblioteca a biblioteca; el consumidor que restringe la biblioteca): cross-document-ref.md.
  • Para la gramática de escritura del bloque assertions: (reglas entre campos que validate: en forma compacta no puede expresar): templates/assertions-block.md.
  • Para el conjunto de pilares de datos que alojan los esquemas en forma compacta (values:, infra:, provides:, uses:, features:, locals:, parameters:): data-pillars.md.
  • Para las reglas de expansión de la forma abreviada de las URI OCI (dominio predeterminado, segmento del registro, versión de reserva, expansión del publicador): uri-grammar.md.
  • Para la escritura de la entidad SchemaLibrary (donde viven en el catálogo los esquemas que se pueden referenciar con $ref:): ../entities/schemalibrary.md.