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

Superficie de validación

Aggrega valida el contenido escrito en cuatro capas de esquema distintas. Cada capa cubre un ámbito distinto, se ejecuta en un punto distinto del pipeline de compilación y produce errores con una forma distinta. A los autores que se topan con un error de validación les resulta útil saber qué capa rechazó la entrada — el mismo campo puede estar regido por más de una capa, y la capa que se activó determina qué corregir y dónde.

Esta página documenta las cuatro capas, su ubicación en el pipeline, la convención de forma de error que sigue cada capa y cómo interactúan las capas cuando más de una se aplica al mismo campo.

Las cuatro capas

Capa 1 — Envoltorio JSON Schema

Ámbito. La forma estructural de todo YAML del catálogo: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, el bloque spec: de nivel superior y los campos obligatorios por entidad que declara el esquema. Cada tipo de entidad (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) tiene su propio JSON Schema, documentado en la Referencia de esquemas. Workload también tiene uno allí, y es el único tipo de ese conjunto que un autor escribe dentro de otra entidad — el bloque workload: de una Recipe o de una FeatureRecipe, o una entrada de una WorkloadLibrary — en lugar de como un archivo de catálogo propio; la misma comprobación del envoltorio lo rige dondequiera que se escriba, y aggrega validate acepta directamente un archivo Workload como destino de una sola entidad.

Ejecución de la validación. En la resolución (resolver / carga), por archivo. Cada documento se comprueba contra el JSON Schema de su tipo cuando se carga; una clave fuera de los campos que declara el esquema se rechaza ahí, antes de que se ejecute cualquier otra validación.

Forma del error. Una discrepancia con el esquema se informa como un fallo del envoltorio del documento. Su cabecera lleva la categoría del documento culpable — [CATALOG_ERROR E0215] para una entidad del catálogo, [DEVELOPER_ERROR E0215] para un Aggregate, [OPS_ERROR E0215] para una Release — y el mensaje nombra el tipo, el archivo, la línea y la columna, la ruta del campo y la restricción infringida:

[CATALOG_ERROR E0215] <path>
document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schema

Las omisiones de campos obligatorios y las discrepancias de tipo aparecen con la misma forma — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".

Capa 2 — Esquemas de los pilares (schema: / featuresSchema / usesSchema)

Ámbito. Los pilares de datos que lleva una entidad — values, infra, parameters, además del bloque de adjuntos features: cuyos slots declara featuresSchema y el bloque uses: regido por usesSchema. Las entidades del Dominio 2 (Component, Feature) incrustan declaraciones JSON Schema 2020-12 en su envoltorio YAML (spec.schema en línea — en forma compacta o completa — o un $ref: a una entrada compartida de una SchemaLibrary); las entidades del Dominio 3 (Recipe, FeatureRecipe) consumen los esquemas resueltos durante su propia pasada de validación.

Ejecución de la validación. En la resolución, después de que se supera el envoltorio JSON Schema. El compilador compone el schema: escrito de la entidad con bases generadas automáticamente, derivadas de las declaraciones usesSchema y featuresSchema; el esquema compuesto valida los bloques values: / infra: / features: / uses: que aporta el desarrollador en cada instancia de componente del Aggregate.

Forma del error. Las infracciones de restricciones aparecen como mensajes que nombran la entidad, la ruta dentro del pilar y la regla que rechazó el valor — por ejemplo, un desarrollador que fija un puerto en 80 frente a una regla del esquema que exige >=1024.

Una entrada usesSchema o featuresSchema redeclarada no produce ningún fallo de composición. Esas dos superficies se superponen por nombre: la entrada de un hijo sustituye por completo la de la base, esquema y selector juntos, de modo que no hay ningún conflicto que informar entre una entrada de la base y una del hijo.

Capa 3 — Capacidad del Provider para el modo sintetizado

Ámbito. Regido por la comprobación de capacidad del modo sintetizado del proveedor vinculado:

  • La compatibilidad con el modo sintetizado (workload:) depende de la capacidad del proveedor vinculado, no de la presencia de workloadSchema: una Recipe workload: vinculada a un proveedor que no puede sintetizar se rechaza aquí. El catálogo de la biblioteca estándar declara workloadSchema en los proveedores capaces de sintetizar por convención — en el spec.provider.workloadSchema del Plugin de renderizado de proveedores — como el contrato de traducción documentado. Ese cuerpo de workloadSchema se compila a su vez a JSON Schema 2020-12 cuando se carga el Plugin, una comprobación estructural de aceptación que rechaza un esquema mal formado en la carga en lugar de en el renderizado.

Ejecución de la validación. En el renderizado base, después de que se haya resuelto el valuesMapping propio de la Recipe. La capa 3 condiciona el despacho en modo sintetizado a la capacidad del proveedor.

Forma del error. Un rechazo por capacidad se atribuye al dominio de autoría del catálogo, de modo que su informe se abre con una cabecera entre corchetes que lleva esa categoría y la instancia causante del fallo. El mensaje se abre con la frase fija que enuncia la condición y luego nombra el nodo, el proveedor y los tipos que ese proveedor sí admite:

[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesized

La cabecera [CATALOG_ERROR] indica que la culpable es la entidad del catálogo, no el Aggregate del desarrollador. En una terminal, la cabecera también lleva el código corto de la condición — E0265 para esta, que la tabla de todas las condiciones resuelve — y el mensaje pasa a su propia línea con sangría; la forma de una línea de arriba es la que llega a un registro. La frase inicial es fija para cada condición, así que es la parte con la que hacer coincidir cuando trabajas a partir del texto; todo lo que sigue varía según el nodo culpable.

Una salvaguarda relacionada protege el propio despacho a los proveedores: cuando más de un Plugin de renderizado de proveedores sirve al mismo destino, el espacio de trabajo resuelve la ambigüedad mediante una vinculación de proveedor en .aggrega-config.yaml, elegida en aggrega pull y registrada en el lockfile. Sin vinculación y con exactamente un Plugin candidato, se usa ese candidato; sin vinculación y con más de un candidato, el build se detiene de forma explícita, nombrando los plugins candidatos. La ambigüedad se resuelve por espacio de trabajo en el punto de uso, no mediante una regla de unicidad para todo el catálogo.

Validación del contenido de Workload por proveedor. El spec.provider.workloadSchema de un Plugin de renderizado de proveedores documenta cómo el proveedor traduce un Workload y marca al proveedor como capaz de sintetizar uno; no valida nada. Todo cuerpo de Workload se valida contra el esquema Workload de la plataforma, sea cual sea el proveedor.

Capa 4 — Validación de valores de las vinculaciones de anotaciones

Ámbito. Los valores de anotación escritos en los límites de la Release / componentes de límite o en los subsistemas / instancias de componente del Aggregate, cuando una vinculación del Manifest bajo mappings.features.annotations.<key> declara un enrutamiento a través de listas de rutas con puntos maps.infra y/o maps.values. Cada ruta declarada recorre el spec.schema.<pillar> de la Feature de destino hasta una propiedad hoja; la contribución del valor de la anotación en esa hoja se valida contra el tipo declarado por el esquema de la Feature. La validación pasa por la propia declaración JSON Schema 2020-12 de la Feature — las vinculaciones solo declaran el enrutamiento, no fragmentos de validación.

Ejecución de la validación. La subfase de expansión de anotaciones de la resolución, después de la validación de los destinos de vinculación del Manifest (la comprobación en la carga del catálogo que confirma que cada ruta declarada existe en el esquema de la Feature referenciada) y junto a la validación de esquemas de la capa 2 sobre adjuntos explícitos. Para cada anotación efectiva por componente: analizar el valor como un escalar, un mapa estructurado o un null explícito; enrutar por subclave a través de la declaración maps de la vinculación, agrupada por pilar, con la aplicación lado-contra-pilar (el lado del Aggregate activa maps.values; el lado de la Release activa maps.infra); validar el valor de tiempo de ejecución por hoja contra el tipo declarado por el esquema de la Feature en el pilar enrutado. Varios errores de subclave se recogen y se emiten todos antes de detenerse.

Forma del error. Los errores de validación de esquema en esta capa siguen la forma de la capa 2 — entidad, ruta (clave de la anotación más enrutamiento de la subclave), detalle de la restricción. Las infracciones de la partición lado-contra-pilar y los fallos de enrutamiento ambiguo se atribuyen al documento en el que se escribió el valor de la anotación, de modo que un fallo que lleva un Aggregate abre una cabecera [DEVELOPER_ERROR] y uno que lleva una Release abre una cabecera [OPS_ERROR], y ambos nombran la clave de la anotación, el pilar enrutado, el lado de autoría y la ubicación en el código fuente.

Una sola convención de formato de errores en todas las capas

Las cuatro capas comparten una convención observable: todo fallo de validación atribuible a Aggrega lleva una forma de ruta más justificación que nombra el campo infractor y la restricción que lo rechazó.

  • Los errores de la capa 1 (envoltorio) y de la capa 2 (esquemas de los pilares) se abren con la misma cabecera entre corchetes — la categoría del documento culpable y el código corto de la condición, como [CATALOG_ERROR E0215] para una discrepancia del envoltorio en una entidad del catálogo y [DEVELOPER_ERROR E0168] para un valor de un Aggregate que un esquema de pilar rechaza — seguida de la ruta del campo y la regla del esquema infringida.
  • Los errores de la capa 3 (fuente del Provider / Workload) son por definición atribuibles a entidades del catálogo — el par Recipe + Provider escribió el esquema que rechazó la entrada del desarrollador. Se atribuyen al dominio de autoría del catálogo, y la atribución te llega en la cabecera entre corchetes del diagnóstico en lugar de como una palabra escrita en el mensaje: un informe que detiene la compilación se abre con [CATALOG_ERROR E0nnn], donde la categoría nombra el dominio y el código corto nombra la condición. Haz coincidir con el código corto, que es fijo una vez emitido.
  • Los errores de la capa 4 (validación de valores de las vinculaciones de anotaciones) siguen la forma de la capa 2 — el esquema de la Feature que valida reside en el spec.schema de la Feature referenciada, y los valores de tiempo de ejecución fluyen a través del enrutamiento maps de la vinculación del Manifest hacia ese esquema para la comprobación de tipos por hoja.

Para el inventario completo de los centinelas con prefijo Aggrega y las superficies que los producen, consulta errors/error-translation.md. Para el catálogo por error (las reglas de forma de la Recipe [CATALOG_ERROR], condición por condición), consulta errors/fatal-halts.md.

Interacción entre capas cuando los campos se solapan

El mismo campo escrito puede estar regido por más de una capa. El containers.<name>.ports.<port> de un Workload lo comprueba la capa 1 como parte de la forma estructural del esquema Workload; la capa 2 no lo alcanza, ya que el contenido de un Workload es una estructura interna de la Recipe y no un pilar de Component; y el workloadSchema de un proveedor no comprueba nada — así que una restricción como rechazar un puerto inferior a 1024 corresponde al esquema del Component o a una aserción, donde la capa que se activa la nombra.

Resumen de la ubicación en el pipeline

CapaÁmbitoSe ejecuta enPrefijo del error
1 — Envoltorio de JSON SchemaForma estructural (apiVersion, kind, metadata, spec de nivel superior)Resolución (carga)la categoría del documento con E0215 — [CATALOG_ERROR E0215] para una entidad del catálogo
2 — Esquemas de los pilares (schema: / featuresSchema / usesSchema)Validación de datos por pilar (values, infra, secrets, uses)Resolución (después del envoltorio)la categoría del documento de autoría con el código corto de la condición — [DEVELOPER_ERROR E0168] para un valor de un Aggregate
3 — Comprobación de capacidad del ProviderCompatibilidad con el modo sintetizado (capacidad del proveedor)Renderizado base[CATALOG_ERROR]
4 — Validación de valores de las vinculaciones de anotacionesContribuciones de valores de anotación enrutadas al spec.schema de la Feature de destino a través de las rutas maps de la vinculación del ManifestLa subfase de expansión de anotaciones de la resolución, junto a la capa 2error de validación de esquema; las superficies lado-contra-pilar / de enrutamiento ambiguo abren el dominio propio del documento de autoría — [DEVELOPER_ERROR] desde un Aggregate, [OPS_ERROR] desde una Release

Referencias cruzadas

  • errors/error-translation.md — inventario de los centinelas con prefijo Aggrega y las superficies que los producen.
  • errors/fatal-halts.md — catálogo por error de cada detención fatal que emite el compilador.
  • vocabulary/data-pillars.md — los pilares de datos (values, infra, parameters, locals, features:, uses: y provides) que valida la capa 2.
  • entities/component.md — superficie de autoría del Component para schema: / featuresSchema / usesSchema.
  • entities/plugin.md — superficie de autoría del Plugin de renderizado de proveedores para spec.provider.workloadSchema.
  • entities/manifest.md — superficie de vinculación features.annotations del Manifest (capa 4).
  • providers/well-known-annotations.md — análisis de los valores de anotación, enrutamiento por subclave de los valores estructurados, exclusión con null por subclave y composición entre lados que valida la capa 4.