Superfície de validação
O Aggrega valida o conteúdo escrito em quatro camadas de schema distintas. Cada camada abrange um âmbito diferente, é executada num ponto diferente do pipeline de compilação e produz erros com uma forma diferente. Os autores que encontram um erro de validação beneficiam de saber que camada rejeitou a entrada — o mesmo campo pode ser regido por mais do que uma camada, e a camada que atuou determina o que corrigir e onde.
Esta página documenta as quatro camadas, o seu posicionamento no pipeline, a convenção de forma de erro que cada camada segue e a forma como as camadas interagem quando mais do que uma se aplica ao mesmo campo.
As quatro camadas
Camada 1 — Envelope JSON Schema
Âmbito. A forma estrutural de todo o YAML do catálogo: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, o bloco spec: de nível superior e os campos obrigatórios por entidade que o esquema declara. Cada tipo de entidade (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) tem o seu próprio JSON Schema, documentado na Referência de esquemas. O Workload também tem um aí, e é o único tipo desse conjunto que um autor escreve dentro de outra entidade — o bloco workload: de uma Recipe ou de uma FeatureRecipe, ou uma entrada de uma WorkloadLibrary — em vez de como um ficheiro de catálogo próprio; a mesma verificação do envelope rege-o onde quer que seja escrito, e o aggrega validate aceita diretamente um ficheiro Workload como alvo de entidade única.
Execução da validação. Na resolução (resolver / carregamento), por ficheiro. Cada documento é verificado face ao JSON Schema do seu tipo quando é carregado; uma chave fora dos campos que o esquema declara é recusada aí, antes de ser executada qualquer outra validação.
Formato do erro. Uma incompatibilidade com o esquema é reportada como uma falha do envelope do documento. O seu cabeçalho contém a categoria do documento em erro — [CATALOG_ERROR E0215] para uma entidade do catálogo, [DEVELOPER_ERROR E0215] para um Aggregate, [OPS_ERROR E0215] para uma Release — e a mensagem indica o tipo, o ficheiro, a linha e a coluna, o caminho do campo e a restrição violada:
[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 schemaAs omissões de campos obrigatórios e as incompatibilidades de tipo surgem no mesmo formato — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".
Camada 2 — Esquemas dos pilares (schema: / featuresSchema / usesSchema)
Âmbito. Os pilares de dados que uma entidade contém — values, infra, parameters, além do bloco de anexos features: cujos slots o featuresSchema declara e do bloco uses: regido pelo usesSchema. As entidades do Domínio 2 (Component, Feature) incorporam declarações JSON Schema 2020-12 no seu envelope YAML (spec.schema inline — na forma compacta ou completa — ou um $ref: para uma entrada partilhada de uma SchemaLibrary); as entidades do Domínio 3 (Recipe, FeatureRecipe) consomem os esquemas resolvidos durante a sua própria passagem de validação.
Execução da validação. Na resolução, depois de o envelope JSON Schema ser aprovado. O compilador compõe o schema: escrito da entidade com bases geradas automaticamente, derivadas das declarações usesSchema e featuresSchema; o esquema composto valida os blocos values: / infra: / features: / uses: fornecidos pelo programador em cada instância de componente no Aggregate.
Formato do erro. As violações de restrições surgem como mensagens que indicam a entidade, o caminho dentro do pilar e a regra que rejeitou o valor — por exemplo, um programador que define uma porta como 80 perante uma regra do esquema que exige >=1024.
Uma entrada usesSchema ou featuresSchema redeclarada não produz qualquer falha de composição. Essas duas superfícies sobrepõem-se por nome: a entrada de um filho substitui integralmente a da base, esquema e seletor em conjunto, pelo que não há conflito a reportar entre uma entrada da base e uma do filho.
Camada 3 — Capacidade do Provider para o modo sintetizado
Âmbito. Regido pela verificação de capacidade do modo sintetizado do fornecedor associado:
- O suporte do modo sintetizado (
workload:) depende da capacidade do fornecedor associado, não da presença deworkloadSchema: uma Recipeworkload:associada a um fornecedor que não consegue sintetizar é rejeitada aqui. O catálogo da biblioteca padrão declaraworkloadSchemanos fornecedores capazes de síntese por convenção — nospec.provider.workloadSchemado Plugin de renderização de fornecedores — como o contrato de tradução documentado. Esse corpo deworkloadSchemaé, por sua vez, compilado para JSON Schema 2020-12 quando o Plugin é carregado, uma verificação estrutural de aceitação que rejeita um esquema malformado no carregamento e não na renderização.
Execução da validação. Na renderização base, depois de o valuesMapping da própria Recipe ter sido resolvido. A camada 3 condiciona o despacho no modo sintetizado à capacidade do fornecedor.
Formato do erro. Uma recusa por capacidade é atribuída ao domínio de autoria do catálogo, pelo que o seu relatório abre com um cabeçalho entre parênteses retos que contém essa categoria e a instância responsável pela falha. A mensagem abre com a frase fixa que enuncia a condição e depois indica o nó, o fornecedor e os tipos que esse fornecedor suporta:
[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 synthesizedO cabeçalho [CATALOG_ERROR] assinala que a entidade do catálogo está em erro, e não o Aggregate do programador. Num terminal, o cabeçalho contém também o código curto da condição — E0265 para esta, que a tabela de todas as condições resolve — e a mensagem passa para uma linha própria indentada; a forma numa linha acima é a que chega a um registo. A frase inicial é fixa por condição, pelo que é a parte a usar na correspondência quando se trabalha a partir do texto; tudo o que se segue varia com o nó em erro.
Uma salvaguarda relacionada protege o próprio despacho para fornecedores: quando mais do que um Plugin de renderização de fornecedores serve o mesmo alvo, o espaço de trabalho resolve a ambiguidade através de uma associação de fornecedor em .aggrega-config.yaml, escolhida no aggrega pull e registada no lockfile. Sem associação e com exatamente um Plugin candidato, é usado esse candidato; sem associação e com mais do que um candidato, o build é interrompido de forma explícita, indicando os plugins candidatos. A ambiguidade é resolvida por espaço de trabalho no ponto de utilização, não por uma regra de unicidade válida para todo o catálogo.
Validação do conteúdo de Workload por fornecedor. O
spec.provider.workloadSchemade um Plugin de renderização de fornecedores documenta como o fornecedor traduz um Workload e marca o fornecedor como capaz de sintetizar um; não valida nada. Todo o corpo de Workload é validado face ao esquema Workload da plataforma, qualquer que seja o fornecedor.
Camada 4 — Validação de valores das associações de anotações
Âmbito. Valores de anotação escritos em fronteiras da Release / componentes de fronteira ou em subsistemas / instâncias de componente do Aggregate, quando uma associação do Manifest em mappings.features.annotations.<key> declara o encaminhamento através de listas de caminhos pontuados maps.infra e/ou maps.values. Cada caminho declarado percorre o spec.schema.<pillar> da Feature de destino até uma propriedade folha; a contribuição do valor da anotação nessa folha é validada face ao tipo declarado pelo esquema da Feature. A validação passa pela própria declaração JSON Schema 2020-12 da Feature — as associações declaram apenas o encaminhamento, não fragmentos de validação.
Execução da validação. A subfase de expansão de anotações da resolução, depois da validação dos alvos de associação do Manifest (a verificação no carregamento do catálogo que confirma que cada caminho declarado existe no esquema da Feature referenciada) e a par da validação de esquemas da camada 2 sobre anexos explícitos. Para cada anotação efetiva por componente: analisar o valor como um escalar, um mapa estruturado ou um null explícito; encaminhar por subchave através da declaração maps da associação, agrupada por pilar, com a imposição lado-versus-pilar (o lado do Aggregate aciona maps.values; o lado da Release aciona maps.infra); validar o valor de execução por folha face ao tipo declarado pelo esquema da Feature no pilar encaminhado. Vários erros de subchave são recolhidos e todos emitidos antes da interrupção.
Formato do erro. Os erros de validação de esquema nesta camada seguem o formato da camada 2 — entidade, caminho (chave da anotação mais encaminhamento da subchave), detalhe da restrição. As violações da partição lado-versus-pilar e as falhas de encaminhamento ambíguo são atribuídas ao documento em que o valor da anotação foi escrito, pelo que uma falha contida num Aggregate abre um cabeçalho [DEVELOPER_ERROR] e uma contida numa Release abre um cabeçalho [OPS_ERROR], e ambas indicam a chave da anotação, o pilar encaminhado, o lado de autoria e a localização na fonte.
Uma única convenção de formatação de erros em todas as camadas
As quatro camadas partilham uma convenção observável: toda a falha de validação atribuível ao Aggrega tem um formato de caminho mais justificação que indica o campo infrator e a restrição que o rejeitou.
- Os erros da camada 1 (envelope) e da camada 2 (esquemas dos pilares) abrem com o mesmo cabeçalho entre parênteses retos — a categoria do documento em erro e o código curto da condição, como
[CATALOG_ERROR E0215]para uma incompatibilidade do envelope numa entidade do catálogo e[DEVELOPER_ERROR E0168]para um valor de um Aggregate que um esquema de pilar recusa — seguido do caminho do campo e da regra do esquema violada. - Os erros da camada 3 (fonte do Provider / Workload) são, por definição, atribuíveis a entidades do catálogo — o par Recipe + Provider escreveu o esquema que rejeitou a entrada do programador. São atribuídos ao domínio de autoria do catálogo, e a atribuição chega-lhe no cabeçalho entre parênteses retos do diagnóstico e não como uma palavra escrita na mensagem: um relatório que interrompe a execução abre com
[CATALOG_ERROR E0nnn], em que a categoria indica o domínio e o código curto indica a condição. Faça a correspondência pelo código curto, que é fixo depois de emitido. - Os erros da camada 4 (validação de valores das associações de anotações) seguem o formato da camada 2 — o esquema da Feature que valida reside no
spec.schemada Feature referenciada, e os valores de execução fluem através do encaminhamentomapsda associação do Manifest para esse esquema para a verificação de tipos por folha.
Para o inventário completo das sentinelas com prefixo Aggrega e das superfícies que as produzem, consulte errors/error-translation.md. Para o catálogo por erro (as regras de formato da Recipe [CATALOG_ERROR], condição a condição), consulte errors/fatal-halts.md.
Interação entre camadas quando os campos se sobrepõem
O mesmo campo escrito pode ser regido por mais do que uma camada. O containers.<name>.ports.<port> de um Workload é verificado pela camada 1 como parte da forma estrutural do esquema Workload; a camada 2 não o alcança, uma vez que o conteúdo de um Workload é uma estrutura interna da Recipe e não um pilar de Component; e o workloadSchema de um fornecedor não verifica nada — pelo que uma restrição como recusar uma porta abaixo de 1024 pertence ao esquema do Component ou a uma asserção, onde a camada que dispara a indica.
Resumo do posicionamento no pipeline
| Camada | Âmbito | Executa em | Prefixo do erro |
|---|---|---|---|
| 1 — Envelope de JSON Schema | Forma estrutural (apiVersion, kind, metadata, spec de nível superior) | Resolução (carregamento) | a categoria do documento com E0215 — [CATALOG_ERROR E0215] para uma entidade do catálogo |
2 — Esquemas dos pilares (schema: / featuresSchema / usesSchema) | Validação de dados por pilar (values, infra, secrets, uses) | Resolução (depois do envelope) | a categoria do documento de autoria com o código curto da condição — [DEVELOPER_ERROR E0168] para um valor de um Aggregate |
| 3 — Verificação de capacidade do Provider | Suporte do modo sintetizado (capacidade do fornecedor) | Renderização base | [CATALOG_ERROR] |
| 4 — Validação de valores das associações de anotações | Contribuições de valores de anotação encaminhadas para o spec.schema da Feature de destino através dos caminhos maps da associação do Manifest | A subfase de expansão de anotações da resolução, a par da camada 2 | erro de validação de esquema; as superfícies lado-versus-pilar / de encaminhamento ambíguo abrem o domínio próprio do documento de autoria — [DEVELOPER_ERROR] a partir de um Aggregate, [OPS_ERROR] a partir de uma Release |
Referências cruzadas
errors/error-translation.md— inventário das sentinelas com prefixo Aggrega e das superfícies que as produzem.errors/fatal-halts.md— catálogo por erro de cada interrupção fatal que o compilador emite.vocabulary/data-pillars.md— os pilares de dados (values,infra,parameters,locals,features:,uses:eprovides) que a camada 2 valida.entities/component.md— superfície de autoria do Component paraschema:/featuresSchema/usesSchema.entities/plugin.md— superfície de autoria do Plugin de renderização de fornecedores paraspec.provider.workloadSchema.entities/manifest.md— superfície de associaçãofeatures.annotationsdo Manifest (camada 4).providers/well-known-annotations.md— análise dos valores de anotação, encaminhamento por subchave de valores estruturados, exclusão com null por subchave e composição entre lados que a camada 4 valida.