Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Autoria em forma compacta

A forma compacta é uma notação abreviada declarativa em formato YAML para JSON Schema 2020-12. Os autores escrevem as restrições por campo como mapas YAML em estilo de fluxo inline (port: { type: integer, min: 1, max: 65535, default: 8080 }); os nós de objeto intermediários são o aninhamento natural do YAML; as referências usam o $ref: padrão do JSON Schema. O compilador transforma a forma compacta em JSON Schema 2020-12 antes que qualquer validação seja executada, de modo que a validação, o relato de erros e toda ferramenta que lê um esquema trabalham sobre o JSON Schema resolvido, qualquer que seja a forma em que ele foi escrito.

Esta página documenta o vocabulário da forma compacta, as convenções estruturais, o despacho entre objetos em forma inferida e explícita, a semântica de fechamento, a heterogeneidade de type: que permite arrays de tipos permitidos, as palavras-chave reservadas em cada escopo em forma inferida e o namespace de extensão x-aggrega-*. Para a semântica de resolução de $ref: entre documentos, veja cross-document-ref.md. Para a gramática de autoria do bloco de asserções, veja templates/assertions-block.md. Para o conjunto de pilares de dados (values:, infra:, provides:, uses:, features:, locals:, parameters:), veja data-pillars.md.

A forma compacta é a superfície de autoria padrão para schema:, parameters: e as entradas de SchemaLibrary. JSON Schema em YAML é uma opção de autoria equivalente; ambas as formas são de primeira classe e podem ser combinadas em um mesmo esquema. As duas formas são compiladas para o mesmo documento JSON Schema resolvido; as ferramentas a jusante e a validação são indiferentes ao caminho de autoria.

Vocabulário

As palavras-chave da forma compacta são as das tabelas abaixo. Os autores as aprendem uma vez e as aplicam em schema:, parameters: e nas entradas de SchemaLibrary.

Palavras-chave de tipo e identidade

Palavra-chaveSignificadoCompila para JSON Schema
typeTipo do campo (string, integer, number, boolean, object, array ou um array de tipos permitidos)type:
descriptionDocumentação legível por humanosdescription:
defaultValor padrão quando o campo está ausentedefault:
requiredMarcador por folha (required: true) para campos que precisam estar presentesAdiciona o nome do campo ao array required: do pai

Palavras-chave de restrição

Palavra-chaveSignificadoCompila para JSON Schema
enumValores permitidos (lista)enum:
constO único valor permitido — um escalar, um mapa ou uma listaconst:
minValor mínimo (numérico) ou comprimento mínimo (string/array)minimum: (numérico); minLength: (string); minItems: (array) — escolhido conforme type:
maxValor ou comprimento máximo, paralelo a minmaximum: / maxLength: / maxItems:
minLength / maxLengthRestrições explícitas de comprimento de stringMapeamento direto para minLength: / maxLength: (use quando min/max seriam ambíguos)
patternPadrão regex para stringspattern:
formatFormato nomeado que uma string precisa ter — um de email, uri, hostname, ipv4, ipv6, uuid, date-time, date (veja Formatos nomeados)format:

No bloco parameters: de um Aggregate, algumas delas também são verificadas na própria declaração, antes que qualquer valor da Release seja lido. Os minLength e maxLength próprios de um parâmetro são zero ou mais — um negativo é recusado quando o Aggregate é carregado — e todo pattern, inclusive um dentro de um contrato items, properties ou valuesType aninhado, precisa ser uma expressão regular que compila, já que o padrão é compilado quando o contrato do parâmetro é lido. Todo format, em qualquer profundidade, precisa ser um dos formatos nomeados abaixo. Um min ou max em um parâmetro booleano ou de objeto também é recusado, já que o par não limita nada nesses tipos. Cada falha interrompe o build nomeando o parâmetro, quer uma Release o forneça ou não. Um limite de comprimento dentro de um contrato aninhado não está sujeito a esse piso; veja entities/aggregate.md para saber onde cada verificação é executada.

Formatos nomeados

format nomeia a forma que um valor string precisa ter. Os nomes são os que a especificação JSON Schema define, escritos como ela os escreve, e cada um verifica o que a especificação define como seu significado:

NomeUm valor conforme éDefinido por
emailuma caixa de correio: uma parte local (átomos separados por pontos, ou uma string entre aspas), @, depois um domínio ou um literal de endereço entre colchetes — ops@example.com. Um nome de exibição como Joe <joe@example.com> não é uma caixa de correioRFC 5321, seção 4.1.2 (Mailbox)
urium URI absoluto: um esquema, :, depois o resto, com todo caractere fora do alfabeto de URI codificado por porcentagem — https://example.com/a%20b, s3://bucket/key. Uma referência relativa como /path não é umRFC 3986 (URI)
hostnameum nome de host: rótulos separados por pontos formados por letras, dígitos e hifens, cada um com 1–63 caracteres que não começa nem termina com hífen, 253 caracteres no máximo no total — db-primary.data.svc.cluster.local. Um rótulo Punycode (xn--…) é aceito como está escrito; um curinga *, um sublinhado ou um ponto final nãoRFC 1123, seção 2.1
ipv4quatro números decimais de 0 a 255, separados por pontos — 192.0.2.1RFC 2673, seção 3.2 (dotted-quad)
ipv6um endereço IPv6 em qualquer uma de suas formas de texto — completa, comprimida com :: ou terminando em um endereço IPv4 — 2001:db8::1. Uma zona (%eth0) ou um comprimento de prefixo (/64) não faz parte de um endereçoRFC 4291, seção 2.2
uuid32 dígitos hexadecimais em grupos de 8-4-4-4-12 separados por hifens, em maiúsculas ou minúsculas — 2eb8aa08-aa98-11ea-b4aa-73b441d16380RFC 4122, seção 3
date-timeum timestamp com um deslocamento — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00, um dia que existe no seu mês e um segundo bissexto apenas às 23:59 UTCRFC 3339, seção 5.6 (date-time)
dateuma data de calendário — 2026-09-28 — cujo dia existe no seu mês e anoRFC 3339, seção 5.6 (full-date)

Um formato julga uma string e nada mais: um valor de outro tipo cabe ao seu type julgar. E ele julga apenas a sintaxe do valor — um nome de host nunca é resolvido, um URI nunca é buscado, uma caixa de correio nunca é contatada —, de modo que a verificação dá a mesma resposta em todo build e não precisa de rede.

A verificação é executada onde quer que um valor seja validado contra o seu esquema: os parameters: de um Aggregate, os values e infra que os pilares schema: de um Component ou de uma Feature restringem, os values e infra por aresta que os esquemas de payload de um socket usesSchema: restringem, e toda entrada de SchemaLibrary que esses esquemas alcançam. Os nomes de formato de um pilar provides são julgados quando o catálogo é carregado, como os de qualquer outro esquema; os valores que uma Recipe publica não são validados contra o pilar, então nenhum formato é verificado neles. Dentro de allOf, anyOf, oneOf e not, um valor que falha no seu formato é um valor que falha nesse ramo, exatamente como um valor que falha em qualquer outra restrição. Um valor não conforme é recusado nomeando o campo, o valor e o formato.

Um nome fora da tabela é recusado quando o esquema é carregado, quer algum valor o alcance ou não, e a recusa lista os nomes suportados — assim, um erro de digitação como emial é um diagnóstico em vez de uma restrição que não verifica nada. Para uma entrada de SchemaLibrary, execute aggrega validate sobre o catálogo inteiro para ver o nome com falha: uma Release cujos esquemas alcançam a entrada também é recusada, mas informa a biblioteca como não encontrada. password não é um formato: um campo que carrega material secreto declara em vez disso sensitive: true.

Um limite se aplica a formas alcançadas indiretamente. Quando a forma de um campo vem por meio de um $ref: que carrega outras palavras-chave ao lado (um mapa properties:, por exemplo), por meio do then: ou do else: de um when:, ou por meio de um ponteiro para uma propriedade declarada, o seu format é verificado nos campos que a forma declara diretamente e por meio de allOf — mas não dentro de um ramo anyOf, oneOf, not ou condicional dentro dessa forma.

Palavras-chave de composição e referência

Palavra-chaveSignificadoCompila para JSON Schema
$refReferência a um fragmento JSON Pointer ou a uma entrada externa de SchemaLibrary$ref:
allOf / anyOf / oneOfComposição do JSON SchemaAs mesmas palavras-chave
patternPropertiesMapa com chaves regexA mesma palavra-chave
valuesTypeAbreviação para mapas de valores tipados (por exemplo, “objeto cujos valores são todos strings”)additionalProperties: { type: <X> }

Palavras-chave de contêiner

Palavra-chaveSignificadoCompila para JSON Schema
itemsForma dos elementos do arrayitems: (forma compacta recursiva ou JSON Schema)
propertiesDeclaração explícita dos filhos (raramente necessária; normalmente implícita pela estrutura YAML)properties:
additionalPropertiesSe propriedades não declaradas são permitidas (false em um objeto em forma inferida, onde o compilador o adiciona; em um type: object explícito, cabe a você escrevê-lo, e o padrão do próprio JSON Schema, true, se aplica onde você não o faz)additionalProperties:

Palavras-chave específicas do Aggrega

Palavra-chaveSignificado
validatePredicado de template Go por campo que retorna um booleano; false interrompe a validação com validateMessage:
validateMessageMensagem de erro que acompanha uma falha de validate:
whenAplicação condicional de uma subárvore; predicado de template Go que determina se as restrições do nó se aplicam
sensitiveDeclara que esta folha carrega material secreto. Compila para x-aggrega-sensitive: true. Veja “Declaring a leaf sensitive (Declarar uma folha sensível)” abaixo
$jsonschemaVia de escape — subdocumento JSON Schema completo incorporado neste nó
$modeAnotação de despacho opcional para casos ambíguos (raramente necessária; veja “Inferred vs explicit object form (Forma inferida e forma explícita dos objetos)” abaixo)

As palavras-chave emprestadas do JSON Schema ($ref, allOf, format etc.) reutilizam uma sintaxe idêntica à do JSON Schema, de modo que os autores que já conhecem JSON Schema as reconhecem imediatamente.

Uma palavra-chave cujo valor é um dado carrega esse valor como foi escrito. Um mapa ou uma lista dado a default, enum ou const é o próprio valor, nunca um esquema aninhado: endpoint: { type: object, default: { host: db, port: 5432 } } define esse objeto como padrão de endpoint, e mode: { type: object, const: { kind: fast } } admite exatamente esse objeto — assim como mode: { const: { kind: fast } }, já que const, como enum, torna o nó uma folha por si só. O mesmo vale dentro de uma via de escape $jsonschema:.

Como uma folha em forma compacta é estruturada

A unidade de autoria é um nó folha — um campo com um dict de restrições:

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

Padrões comuns:

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 folha ocupa uma linha. O dict de restrições captura tudo sobre a forma do campo; a estrutura do nó pai captura a localização do campo.

Objetos aninhados

A estrutura dos objetos espelha o aninhamento YAML. O aninhamento profundo funciona diretamente, com cada folha ainda em uma linha:

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 }

O compilador infere a estrutura dos objetos a partir da hierarquia YAML. Os nós intermediários (aqui: primary, resources, requests, limits, auth) são tipos de objeto que contêm os filhos aninhados. O compilador emite blocos type: object e properties: explícitos no JSON Schema resolvido; o autor não os escreve.

Forma inferida e forma explícita dos objetos

Um escopo de objeto em forma compacta pode ser escrito de duas maneiras:

Forma inferida — os filhos diretamente sob a chave pai, sem declaração type: object:

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

O compilador reconhece o escopo como um objeto porque seus filhos são declarações de propriedades. Ele emite type: object, properties: { ... } e injeta automaticamente additionalProperties: false em tempo de compilação. A semântica de fechamento faz parte do contrato da forma inferida: erros de digitação em campos escritos pelos desenvolvedores falham de forma visível.

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

O compilador NÃO injeta additionalProperties: false na forma explícita. Os autores que declaram type: object assumem total responsabilidade pela decisão de fechamento; a forma explícita é a superfície para mapas realmente abertos (additionalProperties: true) e para objetos que precisam de outras palavras-chave do JSON Schema (patternProperties, propertyNames, unevaluatedProperties).

Critério de autoria: use a forma inferida para objetos fechados comuns (o caso comum nos esquemas do catálogo). Use a forma explícita quando o objeto deve ser realmente aberto, ou quando o esquema exige palavras-chave do JSON Schema que a forma compacta não suporta diretamente.

Semântica de fechamento

Por convenção, os objetos em forma inferida da forma compacta são fechados: propriedades não declaradas produzem um erro de validação. O compilador emite automaticamente additionalProperties: false em todo escopo de objeto em forma inferida. Isso corresponde à disciplina do catálogo de que erros de digitação falham de forma visível.

Para abrir um objeto (permitindo propriedades adicionais arbitrárias), use a forma explícita com additionalProperties: true:

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

Para o padrão comum “objeto cujos valores compartilham todos um tipo” (por exemplo, um mapa de string → string para rótulos), use valuesType::

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

valuesType: <type> compila para additionalProperties: { type: <type> }. É um padrão frequente o bastante para merecer uma abreviação de uma única palavra-chave.

O nome de tipo simples acima é a grafia de schema: e de SchemaLibrary. Em um slot parameters: de um Aggregate, escreva o valor como um contrato em vez disso — valuesType: { type: string }. O mesmo vale para as outras duas palavras-chave cujo valor é ele próprio um contrato, items: e cada entrada sob properties:, porque uma declaração de parâmetro e todo contrato aninhado nela têm uma única forma. Um nome de tipo simples em qualquer uma dessas três posições em um slot de parâmetro é recusado, e o diagnóstico nomeia qual contrato aninhado o continha. Veja entities/aggregate.md para o vocabulário completo dos slots de parâmetros.

Campos obrigatórios

Campos obrigatórios usam required: true por folha:

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 }

O compilador coleta todos os marcadores required: true dentro de um escopo de objeto e os emite como o array required: [field1, field2] do JSON Schema. O marcador conta onde quer que a propriedade seja declarada: em um escopo em forma inferida e em uma propriedade dentro de um bloco properties: explícito.

Um consumidor que traz uma entrada de SchemaLibrary para o seu esquema via $ref: pode nomear os seus requisitos de qualquer uma das duas maneiras — um array required: [name1, name2] no nível do pai ao lado da referência, ou um marcador required: true em uma propriedade que ele declara ali sob properties:. Veja cross-document-ref.md §“required: syntax under cross-document $ref: (sintaxe dos campos obrigatórios sob uma referência entre documentos)” para a regra completa.

Arrays

Arrays usam type: array com items: descrevendo a forma dos 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 o caso comum “array de escalares tipados”, a forma inline ocupa uma linha. Para arrays de objetos, items: introduz um esquema aninhado em forma compacta.

A palavra-chave type: — escalar ou array de tipos

type: aceita um único valor (type: string) ou um array de tipos permitidos (type: [string, integer, boolean]). A forma de array é a expressão padrão do JSON Schema 2020-12 para “este campo aceita um de vários tipos”:

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

Quando type: carrega um array, o espaço de valores é a união dos espaços de valores dos tipos nomeados. Os autores que escrevem esquemas que consomem a forma de array precisam tratar as duas formas a jusante — o campo type do JSON Schema resolvido contém uma string ou um array, e os consumidores que percorrem o esquema resolvido verificam as duas formas.

Palavras-chave reservadas em cada escopo em forma inferida

O despacho da forma inferida reconhece um pequeno conjunto de palavras-chave que têm significado no nível do vocabulário da forma compacta: description, type, default, required, as palavras-chave de restrição (enum, const, min, max, pattern, format etc.) e as palavras-chave específicas do Aggrega (validate, validateMessage, when, sensitive). Quando qualquer uma dessas palavras-chave aparece como nome de campo em um escopo de objeto em forma inferida, o compilador lê o escopo que a envolve como uma folha de restrição em vez de como um objeto: a palavra-chave é tomada como uma restrição, não como uma propriedade filha, e toda outra chave nesse escopo precisa então ser também uma palavra-chave, de modo que a primeira que não for é recusada como palavra-chave desconhecida.

sensitive merece menção específica aqui, porque é um nome muito mais plausível para um campo real escrito por um desenvolvedor do que as outras palavras-chave específicas do Aggrega. Um esquema que realmente precisa de uma propriedade chamada sensitive — um componente cujos values expõem uma flag sensitive própria, por exemplo — precisa declarar explicitamente o escopo que a envolve, exatamente como faria para uma propriedade chamada type ou default. A forma explícita abaixo ou $mode: jsonschema no escopo envolvente consegue isso: sob $mode: jsonschema o nó inteiro é lido como JSON Schema escrito pelo autor, onde sensitive é conteúdo comum e não a palavra-chave da forma compacta.

Para esquemas que precisam de uma propriedade com o nome de uma palavra-chave reservada (por exemplo, um contrato de Component com um campo description: escrito pelo desenvolvedor, ou um campo type:, ou um campo default:), use a forma explícita para o escopo em questão:

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

A forma explícita contorna o despacho — properties: enumera os filhos explicitamente, então a colisão de palavras-chave não ocorre.

Essa restrição se aplica em cada escopo em forma inferida, recursivamente. Um objeto aninhado em forma inferida que contém uma propriedade com o nome de uma palavra-chave reservada é lido como uma folha de restrição nesse escopo. A correção é a mesma: mudar o escopo em questão para a forma explícita.

Referências

As referências tomam emprestado o $ref: do JSON Schema sintática e semanticamente:

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

Blocos $defs: dentro de um esquema em forma compacta declaram definições reutilizáveis. Cada entrada é ela própria um esquema em forma compacta (ou JSON Schema, ou misto). A referência é feita pelo fragmento JSON Pointer #/$defs/<Name>:

Declare o bloco dentro do pilar cujos campos o referenciam, ao lado desses campos — não ao lado do pilar. Um bloco schema: aceita no seu próprio nível superior apenas os nomes dos três pilares de dados, então um $defs: escrito como irmão de values: é recusado quando a entidade é carregada, com um erro que nomeia a chave em questão e o conjunto de pilares que o bloco pode conter. O ponteiro se escreve #/$defs/<Name> em ambos os 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 referências entre documentos que apontam para entradas de SchemaLibrary, veja cross-document-ref.md. Para a expansão da forma abreviada de URI OCI, veja uri-grammar.md.

Apontar uma referência para uma definição, não para uma propriedade

Um ponteiro que nomeia uma entrada $defs: — #/$defs/PodResources — é a forma a preferir. Um ponteiro é válido onde quer que o JSON Schema permita um, então um ponteiro para uma propriedade declarada também é aceito e aplicado, mas é relatado com menos precisão, e vale a pena conhecer a diferença antes de escrever um.

Um campo cuja forma vem de uma entrada $defs: é verificado campo a campo: uma falha é relatada no caminho do valor que está de fato errado, e toda falha sob esse campo é relatada, não apenas a primeira.

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

Um cpu inválido aqui é relatado em primary.resources.requests.cpu.

Um campo cuja forma vem de um ponteiro para uma propriedade declarada é verificado como parte do documento como um todo. As restrições continuam valendo e um documento que as viola continua sendo interrompido — mas a falha é relatada no campo que carrega o ponteiro em vez de no valor dentro dele, e quando vários desses campos estão errados ao mesmo tempo apenas um deles é nomeado.

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

Um cpu inválido sob secondary é relatado em secondary.resources.

As duas formas de escrita aceitam e recusam os mesmos documentos, exceto por um limite em format indicado em Formatos nomeados: através do ponteiro, um format dentro de um ramo anyOf, oneOf ou not da forma não é verificado. Fora isso, o que muda é quanto a mensagem informa a você, o que importa sobretudo em um editor, onde o marcador é posicionado a partir desse caminho. O mesmo vale para uma entrada $defs: cujo próprio ponteiro volta a apontar para as propriedades: alcançar uma definição através dela herda o relato menos preciso.

Forma condicional via when:

O JSON Schema 2020-12 expressa forma condicional via if/then/else. A forma compacta oferece when: como uma abreviação mais direta: um predicado de template Go que, se verdadeiro, aplica o restante das restrições do nó; se falso, o nó é tratado como se suas restrições não existissem.

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

O predicado é avaliado sobre os valores da instância do pai. $ refere-se ao escopo de objeto ao redor. Quando architecture é replication, as restrições (required: true, o replicaCount: min: 2 adicional) se aplicam além do NodePool referenciado. Quando architecture é standalone, essas restrições ficam inativas.

O predicado tem acesso às funções padrão de template Go (Sprig). O compilador compila when: para o if/then/else do JSON Schema mais um wrapper que avalia o predicado de template Go antes da execução da validação. O determinismo é preservado porque o predicado é puro em relação à instância.

Validação personalizada por campo via validate: e validateMessage:

Algumas restrições não podem ser expressas com min / max / pattern / enum. Para elas, a forma compacta oferece validate: — um predicado de template Go que, se falso, interrompe a validação com um erro 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"

O predicado é executado sobre o valor do campo (acessível como .); o escopo de objeto ao redor é $. Se o predicado retornar false, a validação produz um erro usando validateMessage: (ou uma mensagem padrão, se não for fornecida).

validate: trata casos além do vocabulário padrão do JSON Schema: validação semântica personalizada (verificação do formato semver, conteúdo JSON de uma string), regras entre campos mas de escopo estreito em que a restrição de um campo depende de um irmão, e restrições que não justificam um bloco assertions: completo.

validate: difere de when: no papel: when: determina se as restrições se aplicam; validate: é ele próprio uma restrição.

Para regras realmente entre campos com escopo amplo, em que nenhum campo isolado é “aquele que está sendo validado”, use o bloco dedicado assertions:. Veja templates/assertions-block.md.

Declarar uma folha sensível — sensitive:

Uma folha de values, infra ou provides pode declarar que o dado que descreve carrega 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 compila para a palavra-chave de extensão x-aggrega-sensitive: true nesse nó no JSON Schema resolvido, ao lado das outras anotações x-aggrega-*. O compilador a lê para derivar quais vinculações em uma implantação lidam com material declarado sensível, e carrega esse fato derivado no grafo compilado.

Declare-o no dado, não no seu localizador. A distinção é todo o propósito da palavra-chave e é fácil invertê-la. O material de uma credencial é sensível; o nome do recurso que o contém e a chave de dados dentro desse recurso não são — ambos são públicos, e ambos são renderizados em texto claro em todo consumidor que referencia o recurso. Marcar um localizador afirma algo falso sobre ele e propaga esse erro para tudo a jusante que lê a declaração. No exemplo acima, origin está marcado e key deliberadamente não está.

A afirmação complementar — o que quer que se vincule a este ponto lida com material secreto, independentemente do que o preenchimento declara sobre suas próprias folhas — não é de forma alguma uma declaração de folha. É sensitive em um slot de associação; veja entities/component.md “Attachment Slots (Slots de associação)”.

Declarar um objeto inteiro sensível

A palavra-chave pode ficar em um objeto em vez de em um escalar, e então cobre tudo abaixo desse objeto — os próprios filhos do objeto e qualquer coisa aninhada mais abaixo. É a declaração a preferir quando um bloco inteiro é material e marcar cada folha separadamente deixaria sem marcação a próxima folha que alguém adicionar.

Os filhos do objeto precisam ficar em um bloco properties: explícito. Este é o único lugar em que a forma inferida dos objetos não serve, e vale a pena conhecer o motivo em vez de contorná-lo:

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

Escrever os filhos diretamente ao lado do marcador, como a forma inferida dos objetos permite em todos os outros lugares, é recusado em tempo de compilação — o primeiro filho é relatado como uma palavra-chave desconhecida, posicionada na própria chave do filho:

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

A recusa é correta, e não uma limitação a contornar. Um nó é lido como uma folha de restrição assim que carrega uma palavra-chave da forma compacta, e sensitive: é uma — então, a partir desse ponto, toda chave irmã precisa ser também uma palavra-chave, e password não é. O bloco properties: é o que diz “as chaves abaixo são nomes de propriedades, não mais palavras-chave”, e é a mesma desambiguação que Forma inferida e forma explícita dos objetos descreve. Ler o diagnóstico como “o marcador não pode ficar em um objeto” é a leitura equivocada a evitar: ele pode, e o bloco é a maneira de dizer isso.

Uma folha dentro de um objeto declarado não precisa de um marcador próprio. Adicionar um é inofensivo e não diz nada de novo, já que a declaração do objeto já a cobre.

O que a palavra-chave não faz

O nome sugere suposições que a palavra-chave não justifica, então vale declarar claramente o seu teto:

  • Ela não criptografa nada. É uma anotação em uma declaração, não um mecanismo de confidencialidade.
  • Ela não valida nem recusa, exceto onde os parâmetros de um template do CloudFormation são preenchidos. Nenhum valor é aceito ou recusado porque uma folha é declarada sensível, e nenhum resultado do build muda — exceto que, onde o valuesMapping de uma Recipe ou de uma FeatureRecipe do CloudFormation lê uma folha declarada sensível para preencher os parâmetros de um template de origem externa, todo literal que esse mapping vincula interrompe o build, de modo que dois builds que diferem apenas pela declaração podem terminar de forma diferente. Veja A secret bound to a CloudFormation parameter would be written into the template (Um segredo associado a um parâmetro do CloudFormation seria escrito no template).
  • Ela não garante que a saída renderizada esteja livre de material. Se um artefato carrega material depende de qual preenchimento um autor vinculou e do que o autor escreveu nos seus values — veja architecture/08-credential-model.md “What the compiler does and does not guarantee (O que o compilador garante e o que não garante)”. Um valor declarado sensível que um autor forneceu inline é renderizado exatamente como um não declarado, onde quer que o build o renderize.
  • Ela não impõe um mecanismo de entrega. Não pode transformar um valor inline em uma referência a um store, e não restringe o que a allowlist inject de um slot permite.
  • Ela não interrompe um build, exceto por meio dessa recusa do CloudFormation. Os avisos que ela gera em tempo de build, descritos abaixo, são alertas consultivos: o build é executado até o fim e grava seus artefatos. Tornar um aviso fatal é uma escolha da organização, expressa como uma política de governança vinculada ao build, não algo que a palavra-chave faça por conta própria. A recusa do provedor do CloudFormation acima é a exceção: ela interrompe o build, porque um literal escrito em um template pode ser lido por qualquer pessoa que possa ler a stack.
  • Ela não muda nenhum byte renderizado na maioria dos destinos, e nesses nunca mudará. Uma plataforma de destino que tem uma noção própria de sensibilidade é onde uma declaração tem onde aterrissar; um destino sem nenhuma não oferece nada para ela mudar, permanentemente. O Terraform é o único destino da biblioteca padrão que tem tal primitiva: onde a entrada de um módulo vendorizado recebe material que um autor declarou sensível, a saída renderizada ganha um arquivo de override gerado que declara o atributo de sensibilidade próprio do Terraform para essa entrada — veja providers/terraform.md “Declared-sensitive module inputs (Entradas de módulo declaradas sensíveis)”. Em todos os outros casos, declarar uma folha sensível em um catálogo existente deixa todo artefato renderizado idêntico.

O que ela muda no que a ferramenta imprime

A única coisa que uma declaração muda de fato é o que a ferramenta imprime para uma pessoa ler: sua saída de depuração e o texto de uma recusa, descrito abaixo. Nas superfícies de depuração, um valor declarado sensível é substituído pelo texto fixo <redacted>:

  • o rastreamento por passagem que aggrega build --trace grava em .trace/;
  • o bloco Values: por nó que aggrega inspect imprime para um Aggregate;
  • o bloco de vinculações por folha que aggrega inspect imprime para uma Release resolvida.

A chave é sempre mantida e apenas o seu valor é substituído, de modo que quem lê ainda vê que a folha foi escrita e que algo foi ocultado. Uma folha que o autor não declarou imprime seu valor literalmente ao lado de uma irmã ocultada — a substituição segue a declaração e nada mais, então um campo chamado password que não carrega nenhuma declaração é impresso, e um campo declarado chamado key não é.

Uma declaração alcança toda folha abaixo dela, e alcança as três superfícies da mesma forma. Onde a declaração fica em um objeto, cada valor aninhado dentro desse objeto também é ocultado, em qualquer profundidade — a declaração do objeto os nomeia, então ocultá-los não afirma nada que o autor não tenha escrito. A correspondência é feita sobre segmentos de caminho inteiros e não sobre o texto, de modo que uma irmã cujo nome apenas começa com um nome declarado não é afetada: declarar dbPassword não oculta dbPasswordHint.

A ocultação do rastreamento pode ser desativada para um único build, quando o valor ocultado é justamente o que está sendo depurado: aggrega build --trace --trace-unredacted grava os valores nos arquivos de rastreamento e marca cada um desses arquivos com um cabeçalho que o indica. É uma escolha no momento da invocação, sem nenhuma configuração, alcança apenas o rastreamento e está documentada com cli/aggrega-build.md “Showing the withheld values (Mostrar os valores ocultados)”. Os layouts de aggrega inspect têm a sua própria, --unredacted, documentada com cli/aggrega-inspect.md “Showing the withheld values (Mostrar os valores ocultados)”.

Os limites desse comportamento importam mais do que o próprio comportamento.

Artefatos renderizados nunca são mascarados. Tudo o que está sob dist/ é emitido exatamente como a renderização o produziu, porque é o que se implanta: um marcador de posição escrito em um manifesto seria uma implantação quebrada em vez de uma protegida. O mascaramento cobre o que a ferramenta imprime, nunca o que ela escreve. Ler uma declaração como uma promessa de que dist/ é seguro para publicar é o único equívoco a evitar — o teto descrito acima não muda, e dist/ continua tão sensível quanto a vinculação que mais carrega material.

Há uma coisa que uma declaração pode acrescentar a um artefato renderizado, e não é mascaramento: onde um destino tem uma primitiva de sensibilidade própria, a declaração é renderizada nela. O valor continua sendo escrito por inteiro — nada é ocultado nem substituído — e o que o artefato ganha é a marcação própria do destino ao lado dele, para que as ferramentas do destino possam tratar o valor como o autor o declarou. Terraform é o destino que oferece uma hoje, e o que o atributo dele garante e não garante está em providers/terraform.md “Declared-sensitive module inputs (Entradas de módulo declaradas sensíveis)”. Essa marcação só viaja onde a identidade do nome renderizado é recuperada da própria declaração; onde um template inventou o nome, a marcação fica ausente em vez de aproximada, porque marcar um valor que o autor não declarou afirmaria algo falso sobre ele. Onde esse template é um valuesMapping — o de uma Recipe, ou o da FeatureRecipe de uma Feature vinculada a um componente — o build informa isso, como descrito mais abaixo.

O mascaramento alcança o que uma declaração nomeia, mais o que se vê um template ler. Uma folha declarada em um pilar values ou infra, e uma chave de entrega que carrega material de uma chave provides declarada sensível, são ambas identificadas pelo nome e ocultadas. Um valor que um template calculou fica sob uma chave que ninguém declarou, então o que o identifica é, em vez disso, a referência que o autor escreveu: no rastreamento, uma entrada locals: ou um campo source: cujo template lê uma folha declarada sensível é ocultado, e também uma entrada locals: que lê uma irmã já ocultada. A leitura é deliberadamente conservadora — alcançar um objeto inteiro alcança cada folha declarada abaixo dele, e um template que repassa a totalidade dos seus dados alcança todas elas — então uma referência que não pode ser resolvida oculta em vez de imprimir.

Um documento renderizado é mostrado como uma nova renderização, e informa isso. O Workload analisado do rastreamento é um documento que o template da Recipe produziu: nada nele registra de qual declaração veio cada caractere, então não há nenhuma chave em que substituir dentro dele, e recuperar o vínculo campo a campo significaria inspecionar o conteúdo de um valor — o que o compilador não faz. O que o rastreamento mostra em vez disso é o mesmo template workload: avaliado novamente contra um contexto cujos dados declarados sensíveis já são lidos como o texto de substituição, anunciado em uma entrada workload_note ao lado do documento. Como o template vê uma string onde havia uma string, a nova renderização mantém a forma do documento emitido e o texto de substituição ocupa a posição própria do dado ocultado. Restam duas diferenças e a nota indica ambas: um template que se ramifica pelo conteúdo de um valor renderiza de outra forma contra o texto de substituição, e um dado que o eixo não nomeia é repassado sem alteração. É uma visão de depuração do que foi renderizado, nunca uma cópia dele.

Os valores de um nó consumido são ocultados de acordo com as declarações desse nó, nas duas superfícies para as quais a aresta os leva. Uma visão de aresta uses reproduz o que um componente de destino publicou, então quem a rege é o schema próprio do destino: uma chave provides que o destino declarou sensível é ocultada no rastreamento do consumidor mesmo quando o consumidor não declara nada. Onde o próprio bloco inject da aresta roteia essa chave para uma chave de entrega do componente consumidor, essa chave de entrega também é ocultada — a mesma regra que o mapeamento inject de uma vinculação segue, lendo a mesma declaração, de modo que as duas fiações não podem divergir. Os layouts de aggrega inspect mostram os pilares próprios de um nó e as vinculações dele, não os valores publicados de um nó consumido, então nada ali carrega uma visão entre nós a ocultar.

Uma vinculação escrita em uma conexão é ocultada de acordo com as declarações da sua própria Feature, em cada superfície que a mostra. O rastreamento a mostra sob a visão da aresta uses dessa conexão, em .context.uses.<alias>.features.<slot>, e aggrega inspect a imprime sob a linha da conexão em uma Release resolvida. Em ambas, uma folha values ou infra que a sua Feature declara sensível é ocultada exatamente como é na mesma Feature vinculada diretamente ao componente, e no rastreamento também é ocultada uma chave do provides resolvido da vinculação que a Feature declara sensível. O tipo, a versão, os rótulos e cada folha e chave provides não declaradas são impressos literalmente, de modo que um localizador publicado continua legível ao lado do material que ele localiza. Um slot que declara sensitive: true, no componente ou em um socket, marca a vinculação como manipuladora de material secreto e não oculta nenhuma folha por conta própria — quais folhas são ocultadas cabe à Feature declarar.

As projeções legíveis por máquina são literais por contrato, e precisam do mesmo tratamento que os arquivos de onde vieram. aggrega inspect --raw emite uma entidade exatamente como foi escrita, e aggrega inspect --output yaml reproduz a entidade escrita para cada tipo, uma Release incluída. Nenhuma das duas substitui nada, e isso é deliberado: essas são as saídas que um script analisa e que um diff compara, então uma saída que ocultasse silenciosamente parte de si mesma representaria de forma errada a entrada que afirma reproduzir e quebraria a ida e volta da qual seus consumidores dependem. Declarar uma folha sensível não basta para mantê-la fora dessas saídas: encaminhe-as, armazene-as e compartilhe-as como você faria com o próprio Aggregate e a própria Release.

O grafo compilado é a única projeção legível por máquina que oculta, onde quer que seja entregue. --ir-graph, em aggrega inspect, aggrega validate e aggrega build, escreve o grafo que a execução resolveu como JSON ao lado do que o comando já produz, e o aggrega/irGraph do daemon responde a um editor com o mesmo grafo; em cada caso, um valor que um autor declarou sensível é substituído exatamente como nos layouts legíveis. --unredacted ao lado de --ir-graph imprime esses valores em vez disso, e o mesmo faz o campo unredacted na solicitação ao daemon. Assim, o grafo lido de um comando e o grafo lido pelo protocolo do daemon são o mesmo documento sob a mesma regra de tratamento, e um pipeline ou um cliente que precise dos valores escritos tem de pedi-los.

O que uma recusa diz sobre um valor declarado

Uma recusa gerada por um template que lê um valor que um autor declarou sensível não carrega esse valor. Quando um template interrompe o build — uma asserção que chama fail, uma expressão que não pode ser avaliada, uma saída que não é lida como o documento que o template deve produzir — e uma das referências dele alcança um dado declarado sensível, o que é informado vem de avaliar o mesmo template uma segunda vez, contra um contexto em que cada dado declarado sensível já é lido como <redacted> — a menos que o template tenha parado em uma frase que ele mesmo escreve por extenso, o primeiro caso abaixo:

assertion failed: the admin password <redacted> must be supplied as a reference
  • Um fail cuja frase está escrita por extenso no template é informado como foi escrito. Quando a chamada que interrompeu o build é fail com uma única string entre aspas — fail "…", sem nada passado a ele por pipe e nada composto em sua frase —, a recusa carrega essa frase, seja o que for que o valor contenha e qualquer que seja o ramo que levou à chamada, porque a frase não cita nada do que o template leu: uma asserção que recusa uma origem com a forma errada mostra a própria explicação da forma. Uma frase construída de qualquer outra maneira — printf, um campo, uma variável, um valor passado por pipe para fail — é informada pelos casos a seguir.
  • Onde a segunda avaliação falha na mesma expressão pelo mesmo motivo, a falha dela é a informada. A própria frase do autor é preservada com <redacted> onde o valor estava, e um valor que o template codificou, colocou entre aspas ou transformou de outra forma também é ocultado, porque a substituição acontece antes da transformação.
  • Onde não falha, a recusa nomeia a expressão que falha e diz que o texto dela é ocultado. Trata-se de um template cujo comportamento dependia do que o valor contém — ele tomou outro ramo, ou falhou em outro lugar, contra o texto de substituição — então nada do que ele compôs pode ser mostrado. Para que uma recusa assim se explique, escreva a frase dela por extenso na chamada a fail, como descreve o primeiro caso. A recusa ainda interrompe o build, e mantém o seu código.
  • Um Workload renderizado que o schema do Workload rejeita é redigido a partir do schema. Os campos do documento não carregam nenhum vínculo de volta aos dados que o template dele leu, então, onde esse template leu um dado declarado sensível, cada achado que poderia citar um valor enuncia em vez disso a restrição, com <redacted> no lugar do valor e um aviso que explica por quê. Nenhum conselho derivado do valor é dado, e um achado que não cita nenhum valor — uma chave ausente, uma chave que o Workload não admite — é lido como sempre:
.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)
  • Uma entrada with de uma etapa do pipeline recusada pelo contrato de entrada declarado da etapa é redigida a partir do contrato onde o template with lê um dado declarado sensível: cada posição que falha na entrada e a palavra-chave do schema que a recusou, seguidas de um aviso que explica por quê, e nada do que a entrada carregava.
  • Uma recusa que nomeia uma coordenada source: é redigida a partir do que nada declarado produziu onde um template source: produziu essa coordenada lendo um dado declarado sensível — a fonte não está no lockfile nem no cache, o arquivo compactado dela em cache não corresponde ao que o lockfile registra, ou o pin registrado ao lado da entidade diverge do lockfile. Cada linha que uma recusa assim imprime nomeia as coordenadas que a busca usou, então nomeia a fonte pela url e pela versão ou referência em que ela foi pedida — onde as tinha lido — com <redacted> no lugar de cada uma que um template assim produziu, e diz que o motivo dela é ocultado. Ela mantém o seu código e a correção que o build dá para esse 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

O que conta como declarado é o que as declarações nomeiam, em cada parte do contexto que um template pode ler: os values e infra próprios do componente, as Features vinculadas a ele e a cada uma das conexões dele, uma chave de entrega que carrega material declarado, uma chave provides que o seu Component declara sensível, cada entrada de uma lista que o contexto carrega, descrita mais abaixo, e uma entrada locals: calculada a partir de qualquer um deles. Um template que não lê nenhum deles informa exatamente como faria sem nenhuma declaração em lugar nenhum, byte a byte, então só uma recusa gerada por um template que leu um valor declarado é informada de outra forma. A leitura é a mesma que o rastreamento usa, obtida das referências que um template escreve: alcançar um objeto inteiro alcança cada folha declarada abaixo dele, então pode ocultar texto que não continha nenhum valor. Um template que repassa a totalidade dos seus dados de uma vez — o ponto ou $ sem nada depois, passado a uma função como toJson, impresso, ou passado a um template que ele invoca pelo nome — lê cada valor declarado neles, então a recusa dele é informada da mesma forma; dentro de um corpo range ou with o ponto é o valor que esse corpo itera ou nomeia, e repassá-lo lê apenas o que esse valor contém. Nada aqui depende de --trace-unredacted: essa flag alcança apenas os arquivos de rastreamento, e uma recusa é lida da mesma forma com e sem ela.

Um valor declarado é ocultado onde quer que esteja, inclusive dentro de uma lista. As entradas de uma mesma lista são regidas por entidades diferentes, e cada entrada é ocultada de acordo com as suas. Na visão .boundary que uma FeatureRecipe de escopo de fronteira lê, cada conexão listada em internal_uses_edges, outgoing_cross_boundary_uses_edges, incoming_cross_boundary_uses_edges e cross_boundary_uses_edges carrega os provides que o seu destino publica, ocultados onde o Component do destino declara a chave sensível, e cada entrada de feature_attachments carrega os infra dessa vinculação, ocultados onde a sua Feature declara a folha. No contexto de uma Feature vinculada a um componente, cada entrada de .context.used_by carrega o que o componente que se conecta publica, ocultado onde o Component do componente que se conecta declara a chave. A mesma chave em uma entrada cuja entidade não declara nada é citada como está, e uma entrada locals: calculada a partir de uma entrada ocultada é ocultada junto com ela. Percorrer uma lista, ou alcançar uma das entradas dela por meio de index, lê a lista inteira, então conta como ler o que cada entrada carrega:

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

Isso alcança o texto de uma recusa que o build gera. O que um provedor fica sabendo sobre qual parte da sua entrada veio de um valor declarado — os valores que um valuesMapping produziu, um documento workload: renderizado, cada entrada artifacts:, cada campo de uma entrada omits: — não conta um valor lido de dentro de uma lista, então o tratamento próprio que um provedor dá a um valor declarado, incluindo a recusa do CloudFormation de um literal associado descrita acima, não alcança nenhum desses.

Algumas recusas ficam fora disso. O texto que um plugin escreve — a recusa própria de um provedor ou de uma etapa do pipeline — é a frase do plugin, repassada como o plugin a escreveu. Um template avaliado fora das asserções do build e da renderização dele — a interpolação de parâmetros e as verificações de parâmetros em um Aggregate, os templates when: e validate: de um schema, e a resolução de uma coordenada source: que registra o seu pin — informa a sua falha como ela falhou.

O aviso do build para um valor que viaja como literal

Um build imprime um aviso por chave de entrega que carrega material declarado sensível como valor literal. Ele dispara quando o bloco inject de uma vinculação roteia uma chave provides que a Feature da vinculação declarou sensível para uma chave de entrega do componente consumidor, e o valor é de fato entregue:

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

Três coisas nele são deliberadas.

Ele informa como um valor viaja, não que algo esteja errado. Entregar um literal é frequentemente a única coisa que um destino aceita, e toda uma família de vinculações existe exatamente para isso. O aviso diz a um autor qual valor segue esse caminho e onde, para que a escolha fique visível em vez de implícita; ele não afirma que a escolha seja um erro.

É um alerta e nunca uma interrupção. O build é bem-sucedido e grava seus artefatos sem alteração. Uma organização que queira que uma credencial entregue como literal faça o build falhar expressa isso como uma política de governança sobre o build, que é onde uma rejeição cabe — uma regra que algumas implantações precisam quebrar não é um comportamento padrão do compilador.

Ele é decidido a partir da fiação, nunca do valor. O aviso lê a sensibilidade que um schema declarou mais a entrega que o autor escreveu. Nenhum valor é inspecionado, então um campo nunca é presumido como credencial pelo nome ou pelo conteúdo, e um valor não declarado que por acaso contém uma senha não gera nada.

Dois casos ficam deliberadamente em silêncio. Uma chave de entrega cuja chave provides referenciada não publica nada não entrega nenhum literal e não informa nada — o aviso segue uma entrega que aconteceu. E um slot cuja allowlist inject está vazia deixa a entrega para a Recipe, então o autor não escreveu nenhuma chave de entrega a informar e não tem nada sobre o que agir.

O aviso é uma classe própria, identificada pelo próprio código, e --no-unsupported-field-warnings não o silencia: essa flag cobre as notificações de fidelidade de um destino, que são um julgamento diferente silenciado por motivos diferentes. Ele também chega ao editor, onde aparece como um problema no Aggregate, sempre que o servidor de linguagem está em execução com --build-on-inspect (ou a chave de configuração serve.build_on_inspect) ativado. Essa configuração fica desativada por padrão por consistência com aggrega inspect: o comando de terminal nunca chega à etapa de renderização ao inspecionar um grafo, então também não gera tal aviso, e uma inspeção no editor que também não gera nenhum está mostrando a você a mesma coisa que o terminal. Ativar a configuração é como você pede ao editor a camada adicional, e nada é gravado em disco quando você faz isso — a etapa é executada e os artefatos dela são descartados. Ela acrescenta os avisos que um build gera ao renderizar, e nenhuma das verificações nas quais um build é interrompido. Cada problema publicado nomeia a camada que o gerou, para que um editor possa manter este aviso separado dos que as etapas de resolução e de análise informam.

O aviso do build para um valor que um mapeamento renderiza sem marcação

Um build imprime um aviso por folha values declarada sensível cuja marcação uma renderização não consegue carregar enquanto o autor ainda tem a alavanca sobre ela. Ele dispara em uma renderização a partir de um source: cujos valores são a saída de um valuesMapping — o de uma Recipe, sobre uma folha que o seu Component declara, ou o da FeatureRecipe de uma Feature vinculada a um componente, sobre uma folha que essa Feature declara. As chaves de saída do mapeamento são invenção dele, então nenhuma declaração nomeia nenhuma delas e o destino não recebe nenhuma marcação por chave para a folha:

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; ...

A linha nomeia a folha na sua coordenada escrita e a Recipe ou a FeatureRecipe cujo mapeamento condiciona a junção, porque a declaração e o mapeamento são escritos em duas entidades diferentes; a linha de uma vinculação começa com o nome sob o qual ela está vinculada, para que duas vinculações de uma mesma Feature em um mesmo componente sejam distinguidas. Remover o mapeamento é a alavanca: sem ele, os valores que uma renderização a partir de uma fonte recebe são indexados pelos caminhos das folhas declaradas, e a marcação viaja com eles. Uma renderização só de artefatos e uma renderização só de workload ficam em silêncio, porque não entregam ao seu destino nenhum mapa de valores, e o mesmo vale para uma Feature vinculada a uma fronteira, que renderiza contra um pilar values vazio — o teto descrito acima é permanente ali, e um alerta não nomearia nada a fazer. Assim como o aviso para um valor que viaja como literal, é um alerta e nunca uma interrupção, não muda nenhum byte renderizado, é uma classe própria com seu próprio código, sensitivity-not-conveyed, e --no-unsupported-field-warnings não o silencia. Avisos e saída do linter traz a forma completa dele.

Onde a declaração é lida, e onde não é

A palavra-chave é lida no nó em que está, e a leitura então segue cada via pela qual uma declaração pode alcançar esse dado: mapas de propriedades aninhados, cada ramo de composição e o destino de um $ref. Um ramo e um destino de referência se compõem ambos sobre a propriedade que os carrega, então uma declaração encontrada por qualquer um deles é coletada para essa propriedade; só uma descida por properties estende o caminho.

Um marcador é lido esteja ele ao lado de uma dessas palavras-chave ou dentro do que a palavra-chave alcança, então duas formas não precisam de posicionamento deliberado:

  • Ao lado de um $ref, ou dentro do destino da referência. Um marcador na folha que faz a referência declara essa folha. Um marcador no schema referenciado também é coletado para a folha que faz a referência, no caminho dessa folha mais a cadeia abaixo dele — nunca em um caminho dentro da definição, onde nenhum valor escrito vive.
  • Ao lado de uma palavra-chave de composição (allOf / anyOf / oneOf), ou dentro das properties próprias de um ramo. Um ramo se compõe sobre o objeto que o carrega, então se desce em cada ramo — incluindo os ramos condicionais de um nó escrito como JSON Schema — e uma declaração dentro de um deles é coletada no caminho próprio da propriedade que compõe mais a cadeia dela.

Uma forma precisa, sim, que o marcador seja posicionado deliberadamente:

  • Na própria folha array, não no seu tipo de elemento items. Um array cujos elementos carregam material é declarado sensível no array, porque um tipo de elemento não é um mapa de propriedades e não se desce nele.

parameters: é um vocabulário diferente

sensitive não faz parte do vocabulário de contrato tipado de parameters:. Um Aggregate que o declara em uma entrada de parâmetro é recusado quando o Aggregate é carregado, com um diagnóstico do envelope do documento que informa unexpected property: "sensitive" posicionado na própria chave problemática — o mesmo tratamento que qualquer chave fora desse vocabulário recebe, já que o contrato de parâmetros é um objeto fechado.

A assimetria é deliberada: o eixo de sensibilidade cobre os três pilares de dados que uma entidade de catálogo declara, e um parâmetro é uma entrada do contrato de ambiente em vez de uma folha de pilar. Elevar material de credencial por meio de um parâmetro está documentado em architecture/08-credential-model.md “Legacy charts that demand a formatted string (Charts legados que exigem uma string formatada)”, que declara a troca que esse caminho faz.

Composição com allOf, anyOf, oneOf

As palavras-chave de composição funcionam como no 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 }

O compilador emite as mesmas palavras-chave de composição no JSON Schema resolvido. Cada uma das entradas que compõem pode ser forma compacta, JSON Schema ou referências $ref:. A mistura dentro de uma composição é suportada.

A via de escape — $jsonschema:

Para casos além do vocabulário da forma compacta ($dynamicRef, unevaluatedProperties, composição not: profunda, tipos recursivos), qualquer nó pode passar para o 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 }

O bloco $jsonschema: contém YAML de JSON Schema; o compilador o trata como uma passagem transparente — o conteúdo vai diretamente para o documento JSON Schema resolvido na posição desse nó. A validação, o relato de erros e as ferramentas trabalham todos sobre o documento resolvido; a via de escape é puramente uma conveniência de escrita.

Um ramo not: pode conter uma description: dizendo por que a forma que ele exclui é recusada. Um valor que corresponde a esse ramo é então recusado com a descrição como motivo, impressa em uma única linha, no lugar do texto genérico “not allowed here (não permitido aqui)” — então escreva-a como a frase que o autor do valor recusado deve ler. Somente uma descrição escrita no próprio ramo not: é usada; uma em uma entrada de $defs que o ramo apenas referencia não é.

Cada nó dentro do bloco é lido como JSON Schema, e uma palavra-chave da forma compacta escrita ali mantém o seu significado compacto (min: 3 em uma string continua sendo um comprimento mínimo). Um $ref no bloco é resolvido como um de fora: #/$defs/Foo nomeia uma entrada do $defs: do pilar, então o exemplo declara Foo ali, e uma referência que nomeia uma entrada que ninguém declarou é recusada quando a entidade é carregada. $dynamicRef é resolvido contra um $dynamicAnchor, então uma forma recursiva pode ser escrita; um valor que falha no fundo da recursão é relatado no campo que o contém — tree.children, para um name inválido dois níveis abaixo em uma árvore cujos itens children são { $dynamicRef: "#node" }.

Um limite se aplica a unevaluatedProperties e unevaluatedItems. Escrita em um nó que também carrega uma referência, uma palavra-chave de composição (allOf, anyOf, oneOf), uma condicional ou um schema dependente, qualquer uma das duas é carregada mas não é aplicada — e unevaluatedItems também não é aplicada ao lado de contains. No exemplo acima, unevaluatedProperties: false fica ao lado de allOf, então { name: n, extra: 1 } é aceito embora nem Foo nem patternProperties declarem extra.

A via de escape $jsonschema: é por nó, não por documento. Um schema pode usar a forma compacta para as partes simples, a via de escape para JSON Schema para o único campo complexo e $ref: para formas compartilhadas — tudo em um único documento.

Misturar forma compacta e JSON Schema em um único documento

A forma compacta e o JSON Schema podem ser misturados livremente em qualquer fronteira entre nós. A regra de despacho é guiada pela forma do conteúdo:

  • Um nó que contém $jsonschema: é tratado como JSON Schema (a via de escape).
  • Um nó que contém palavras-chave de nível superior no estilo JSON Schema (type:, properties:, additionalProperties:, if: etc.) é tratado como JSON Schema (a forma explícita).
  • Um nó que contém apenas entradas nome de propriedade → schema filho (sem palavras-chave reservadas do JSON Schema) é tratado como forma compacta (forma inferida).
  • Um nó com apenas $ref: é uma passagem de referência.
  • Um nó com allOf: / anyOf: / oneOf: é uma composição; cada entrada é despachada de forma independente.

Para folhas em forma compacta, o padrão usual é field_name: { type: ..., constraints... } — um mapa YAML que contém um vocabulário conhecido da forma compacta. O despacho reconhece dicionários de restrições pelas chaves.

Para o raro caso ambíguo (p. ex., um schema em forma compacta com um campo literalmente chamado type que o despacho em forma inferida interpretaria como a palavra-chave do JSON Schema), a forma explícita é a correção canônica — veja “Reserved keywords at every inferred-form scope (Palavras-chave reservadas em cada escopo em forma inferida)” acima.

Importar um contrato de um arquivo — $import:

Um contrato não precisa ficar dentro da entidade que o declara. $import: nomeia um arquivo de onde lê-lo:

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

Todo o spec.schema vem então desse arquivo, que é escrito exatamente como o bloco que ele substitui — pilares no topo, forma compacta ou YAML de JSON Schema abaixo:

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 }

Um único pilar pode ser importado sozinho, com seus irmãos escritos inline ao lado dele:

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

A mesma forma funciona no valueSchema: e no infraSchema: de um socket usesSchema:.

As regras que o regem:

  • $import: é a única chave na posição em que aparece. Um irmão escrito ao lado dele é recusado, em vez de um dos dois ser descartado.
  • Um caminho relativo é lido em relação ao diretório que contém o arquivo da entidade que o declarou, nunca em relação ao diretório a partir do qual um build é executado — a mesma base que valuesMapping:, workload: e artifacts: usam. Ele precisa ficar dentro desse diretório, porque cada arquivo que uma publicação da entidade carrega é tirado dali: um caminho que sai dele, ou um caminho absoluto, nomeia um arquivo que não viajaria com a entidade e é recusado — veja A path names content outside the entity’s own directory (Um caminho nomeia conteúdo fora do diretório da própria entidade). Um schema que várias entidades compartilham pertence a uma SchemaLibrary, referenciada com $ref:.
  • O arquivo importado viaja com a entidade. Uma entidade publicada carrega cada arquivo que o seu schema importa, incluindo cada arquivo de uma cadeia, de modo que uma cópia obtida de um registro lê o mesmo contrato e valida os valores escritos em relação a ele — veja aggrega push.
  • O arquivo importado carrega conteúdo de schema, não um documento de entidade. Um arquivo cujo conteúdo não é um mapa YAML é recusado, com o nome do arquivo.
  • Um arquivo importado pode ser ele próprio um único $import:, que é resolvido recursivamente; uma cadeia que retorna a um arquivo que já está sendo lido é recusada, com o nome da cadeia.

A importação é lida quando a entidade é carregada, então cada superfície que lê essa entidade vê o mesmo contrato: aggrega validate, um build, aggrega push, aggrega inspect e o editor. Um arquivo que não pode ser lido, ou um conteúdo que não é um schema, é recusado nesse ponto em vez de deixar o contrato sem aplicação — e um push o recusa antes que qualquer coisa seja publicada.

$import: e $ref: não são intercambiáveis. $import: nomeia um arquivo e substitui um conteúdo inteiro; $ref: nomeia uma entrada de SchemaLibrary pela identidade e se compõe em qualquer nó. Um valor $import: que carrega uma identidade de biblioteca ou um host de registro é recusado com uma orientação para $ref:. Veja cross-document-ref.md.

Namespace de extensões do Aggrega — x-aggrega-*

A forma compacta reconhece qualquer palavra-chave com o prefixo x-aggrega- como uma extensão específica do Aggrega. O namespace é aberto: novas anotações entram no catálogo sem edições de vocabulário por palavra-chave. Autores que escrevem x-aggrega-selector, x-aggrega-narrowed-from ou anotações futuras fazem o seu conteúdo chegar ao escopo certo no JSON Schema resolvido sem recusa em tempo de compilação.

O prefixo do namespace importa: um erro de digitação como x-agrega-source (faltando um g) NÃO é reconhecido como palavra-chave de extensão e seria recusado pela semântica de objeto fechado nos escopos em forma inferida. O escopo do prefixo funciona como uma rede de detecção de erros de digitação para a superfície de anotações do catálogo.

Anotações x-aggrega-* específicas são emitidas pelo compilador em pontos bem conhecidos do pipeline:

  • x-aggrega-selector: — emitida pela síntese de usesSchema: e featuresSchema: para carregar a string do seletor que visa os Components provedores compatíveis.
  • x-aggrega-sensitive: — emitida por uma folha que declara sensitive: true. Veja Declarar uma folha sensível acima.

Autores de catálogo que escrevem as próprias palavras-chave de extensão usam o mesmo namespace; as ferramentas a jusante que consomem o JSON Schema compilado leem chaves x-aggrega-* sem colidir com o espaço de palavras-chave próprio do JSON Schema.

Exemplo completo — schema de Component do MariaDB

Um schema de Component representativo em forma compacta para um datastore MariaDB, mostrando a forma inferida do começo ao fim, restrições de folha mistas, referências, forma condicional e um oneOf completo para o bloco de autenticação:

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, o mesmo contrato explicita em cada objeto type: object, properties: e additionalProperties: false, e lista novamente cada campo obrigatório no required: do seu pai, então fica consideravelmente mais longo. O ganho de compacidade se acumula em contratos de Component maiores e é significativo o bastante para tornar a forma compacta a superfície de escrita padrão para schema:, parameters: e entradas de SchemaLibrary.

Referências cruzadas

  • Para a semântica de resolução de $ref: entre documentos (a sintaxe de required: ao lado de uma referência entre documentos; a expansão de cadeias de biblioteca para biblioteca; o consumidor que restringe a biblioteca): cross-document-ref.md.
  • Para a gramática de escrita do bloco assertions: (regras entre campos que validate: em forma compacta não consegue expressar): templates/assertions-block.md.
  • Para o conjunto de pilares de dados que hospeda os schemas em forma compacta (values:, infra:, provides:, uses:, features:, locals:, parameters:): data-pillars.md.
  • Para as regras de expansão da forma abreviada de URI OCI (domínio padrão, segmento de registro, fallback de versão, expansão do publicador): uri-grammar.md.
  • Para a escrita da entidade SchemaLibrary (onde vivem no catálogo os schemas referenciáveis com $ref:): ../entities/schemalibrary.md.