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

Criação 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 intermédios são o aninhamento natural do YAML; as referências utilizam o $ref: normalizado do JSON Schema. O compilador transforma a forma compacta em JSON Schema 2020-12 antes de qualquer validação ser executada, pelo que a validação, o relato de erros e todas as ferramentas que leem um esquema trabalham sobre o JSON Schema resolvido, seja qual for a forma em que 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 fecho, a heterogeneidade de type: que permite arrays de tipos permitidos, as palavras-chave reservadas em cada âmbito em forma inferida e o namespace de extensão x-aggrega-*. Para a semântica de resolução de $ref: entre documentos, ver cross-document-ref.md. Para a gramática de criação do bloco de asserções, ver templates/assertions-block.md. Para o conjunto de pilares de dados (values:, infra:, provides:, uses:, features:, locals:, parameters:), ver data-pillars.md.

A forma compacta é a superfície de criação predefinida para schema:, parameters: e as entradas de SchemaLibrary. JSON Schema em YAML é uma opção de criação equivalente; ambas as formas são de primeira classe e podem ser combinadas num 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 criação.

Vocabulário

As palavras-chave da forma compacta são as das tabelas abaixo. Os autores aprendem-nas uma vez e aplicam-nas 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 predefinido quando o campo está ausentedefault:
requiredMarcador por folha (required: true) para campos que têm de 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 consoante type:
maxValor ou comprimento máximo, paralelo a minmaximum: / maxLength: / maxItems:
minLength / maxLengthRestrições explícitas de comprimento de stringCorrespondência direta com minLength: / maxLength: (a utilizar quando min/max seriam ambíguos)
patternPadrão regex para stringspattern:
formatFormato com nome que uma string tem de ter — um de email, uri, hostname, ipv4, ipv6, uuid, date-time, date (ver Formatos com nome)format:

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

Formatos com nome

format nomeia a forma que um valor de string tem de 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 o 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 parênteses retos — ops@example.com. Um nome de apresentação como Joe <joe@example.com> não é uma caixa de correioRFC 5321, secção 4.1.2 (Mailbox)
urium URI absoluto: um esquema, :, depois o resto, com qualquer carácter fora do alfabeto de URI codificado com percentagem — https://example.com/a%20b, s3://bucket/key. Uma referência relativa como /path não o éRFC 3986 (URI)
hostnameum nome de anfitrião: etiquetas separadas por pontos compostas por letras, dígitos e hífenes, cada uma com 1–63 caracteres e que não começa nem termina com hífen, 253 caracteres no máximo no total — db-primary.data.svc.cluster.local. Uma etiqueta Punycode (xn--…) é aceite tal como está escrita; um carácter universal *, um sublinhado ou um ponto final nãoRFC 1123, secção 2.1
ipv4quatro números decimais de 0 a 255, separados por pontos — 192.0.2.1RFC 2673, secção 3.2 (dotted-quad)
ipv6um endereço IPv6 em qualquer uma das suas formas de texto — completa, comprimida com :: ou terminada num endereço IPv4 — 2001:db8::1. Uma zona (%eth0) ou um comprimento de prefixo (/64) não faz parte de um endereçoRFC 4291, secção 2.2
uuid32 dígitos hexadecimais em grupos de 8-4-4-4-12 separados por hífenes, em maiúsculas ou minúsculas — 2eb8aa08-aa98-11ea-b4aa-73b441d16380RFC 4122, secção 3
date-timeum carimbo temporal com um desvio — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00, um dia que existe no seu mês e um segundo intercalar apenas às 23:59 UTCRFC 3339, secção 5.6 (date-time)
dateuma data de calendário — 2026-09-28 — cujo dia existe no seu mês e anoRFC 3339, secção 5.6 (full-date)

Um formato julga uma string e nada mais: um valor de outro tipo cabe ao seu type julgar. E julga apenas a sintaxe do valor — um nome de anfitrião nunca é resolvido, um URI nunca é obtido, uma caixa de correio nunca é contactada —, pelo que a verificação dá a mesma resposta em todas as compilações e não precisa de rede.

A verificação é executada onde quer que um valor seja validado face ao 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 cada 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 face ao pilar, pelo que nenhum formato é verificado neles. Dentro de allOf, anyOf, oneOf e not, um valor que falha o seu formato é um valor que falha esse ramo, exatamente como um valor que falha qualquer outra restrição. Um valor não conforme é recusado com a indicação do campo, do valor e do formato.

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

Um limite aplica-se às formas alcançadas indiretamente. Quando a forma de um campo chega através de um $ref: que tem outras palavras-chave ao lado (um mapa properties:, por exemplo), através do then: ou do else: de um when:, ou através de um ponteiro para uma propriedade declarada, o seu format é verificado nos campos que a forma declara diretamente e através 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
valuesTypeAbreviatura para mapas de valores tipados (por exemplo, «objeto cujos valores são todos strings»)additionalProperties: { type: <X> }

Palavras-chave de contentor

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 através da estrutura YAML)properties:
additionalPropertiesSe as propriedades não declaradas são permitidas (false num objeto em forma inferida, onde o compilador o acrescenta; num type: object explícito, cabe ao autor escrevê-lo, e o valor predefinido do próprio JSON Schema, true, aplica-se onde este não o faz)additionalProperties:

Palavras-chave específicas do Aggrega

Palavra-chaveSignificado
validatePredicado de template Go por campo que devolve 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 contém material secreto. Compila para x-aggrega-sensitive: true. Ver «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; ver «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, pelo que os autores que já conhecem o JSON Schema as reconhecem de imediato.

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

Como se estrutura uma folha em forma compacta

A unidade de criação é 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 capta tudo sobre a forma do campo; a estrutura do nó pai capta a localização do campo.

Objetos aninhados

A estrutura dos objetos reflete o aninhamento YAML. O aninhamento profundo funciona diretamente, com cada folha ainda numa 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 intermédios (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 âmbito de objeto em forma compacta pode ser escrito de duas formas:

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 âmbito como um objeto porque os seus filhos são declarações de propriedades. Emite type: object, properties: { ... } e injeta automaticamente additionalProperties: false no momento da compilação. A semântica de fecho faz parte do contrato da forma inferida: os erros de escrita em campos criados pelos programadores 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 fecho; a forma explícita é a superfície para mapas genuinamente abertos (additionalProperties: true) e para objetos que precisam de outras palavras-chave do JSON Schema (patternProperties, propertyNames, unevaluatedProperties).

Critério de criação: utilizar a forma inferida para objetos fechados comuns (o caso habitual nos esquemas do catálogo). Utilizar a forma explícita quando o objeto deve ser genuinamente aberto, ou quando o esquema requer palavras-chave do JSON Schema que a forma compacta não suporta diretamente.

Semântica de fecho

Por convenção, os objetos em forma inferida da forma compacta são fechados: as propriedades não declaradas produzem um erro de validação. O compilador emite automaticamente additionalProperties: false em cada âmbito de objeto em forma inferida. Isto corresponde à disciplina do catálogo de os erros de escrita falharem de forma visível.

Para abrir um objeto (permitindo propriedades adicionais arbitrárias), utiliza-se 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 partilham todos um tipo» (por exemplo, um mapa de string → string para etiquetas), utiliza-se 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 suficientemente frequente para merecer uma abreviatura de uma única palavra-chave.

O nome de tipo simples acima é a grafia de schema: e de SchemaLibrary. Num slot parameters: de um Aggregate, o valor escreve-se antes como um contrato — valuesType: { type: string }. O mesmo se aplica às 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 cada contrato aninhado nela têm uma única forma. Um nome de tipo simples em qualquer uma dessas três posições num slot de parâmetro é recusado, e o diagnóstico nomeia o contrato aninhado que o continha. Ver entities/aggregate.md para o vocabulário completo dos slots de parâmetros.

Campos obrigatórios

Os campos obrigatórios utilizam 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 recolhe todos os marcadores required: true dentro de um âmbito de objeto e emite-os como o array required: [field1, field2] do JSON Schema. O marcador conta onde quer que a propriedade seja declarada: num âmbito em forma inferida e numa propriedade dentro de um bloco properties: explícito.

Um consumidor que traz uma entrada de SchemaLibrary para o seu esquema através de $ref: pode nomear os seus requisitos de qualquer uma das duas formas — um array required: [name1, name2] ao nível do pai ao lado da referência, ou um marcador required: true numa propriedade que declara aí sob properties:. Ver 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

Os arrays utilizam type: array com items: a descrever 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 normalizada 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: contém 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 têm de 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 âmbito em forma inferida

O despacho da forma inferida reconhece um pequeno conjunto de palavras-chave que têm significado ao 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 destas palavras-chave aparece como nome de campo num âmbito de objeto em forma inferida, o compilador lê o âmbito envolvente como uma folha de restrição e não como um objeto: a palavra-chave é tomada como uma restrição, não como uma propriedade filha, e todas as outras chaves desse âmbito têm então de ser também palavras-chave, pelo que a primeira que não o for é recusada como palavra-chave desconhecida.

sensitive merece uma menção específica aqui, porque é um nome muito mais plausível para um campo real criado por um programador do que as outras palavras-chave específicas do Aggrega. Um esquema que precise genuinamente de uma propriedade chamada sensitive — um componente cujos values exponham uma flag sensitive própria, por exemplo — tem de declarar explicitamente o âmbito envolvente, exatamente como faria para uma propriedade chamada type ou default. A forma explícita abaixo ou $mode: jsonschema no âmbito envolvente consegue-o: com $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: criado pelo programador, ou um campo type:, ou um campo default:), utiliza-se a forma explícita para o âmbito em causa:

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, pelo que a colisão de palavras-chave não surge.

Esta restrição aplica-se em cada âmbito em forma inferida, recursivamente. Um objeto aninhado em forma inferida que contenha uma propriedade com o nome de uma palavra-chave reservada é lido como uma folha de restrição nesse âmbito. A correção é a mesma: passar o âmbito em causa para a forma explícita.

Referências

As referências tomam de empréstimo 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 }

Os 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 faz-se através do fragmento JSON Pointer #/$defs/<Name>:

O bloco declara-se 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, pelo que um $defs: escrito como irmão de values: é recusado quando a entidade é carregada, com um erro que nomeia a chave em causa e o conjunto de pilares que o bloco pode conter. O ponteiro escreve-se #/$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 visam entradas de SchemaLibrary, ver cross-document-ref.md. Para a expansão da forma abreviada de URI OCI, ver 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 o permita, pelo que um ponteiro para uma propriedade declarada também é aceite e aplicado, mas é reportado com menos precisão, e convém conhecer a diferença antes de escrever um.

Um campo cuja forma provém de uma entrada $defs: é verificado campo a campo: uma falha é reportada no caminho do valor que está efetivamente errado, e cada falha sob esse campo é reportada, 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 reportado em primary.resources.requests.cpu.

Um campo cuja forma provém de um ponteiro para uma propriedade declarada é verificado como parte do documento no seu todo. As restrições continuam a aplicar-se e um documento que as viole continua a ser interrompido — mas a falha é reportada no campo que contém o ponteiro e não 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 é reportado em secondary.resources.

As duas formas de escrita aceitam e recusam os mesmos documentos, exceto por um limite em format indicado em Formatos com nome: através do ponteiro, um format dentro de um ramo anyOf, oneOf ou not da forma não é verificado. De resto, o que difere é o quanto a mensagem informa, o que importa sobretudo num editor, onde o marcador é posicionado a partir desse caminho. O mesmo se aplica a 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 através de when:

O JSON Schema 2020-12 exprime a forma condicional através de if/then/else. A forma compacta disponibiliza when: como uma abreviatura mais direta: um predicado de template Go que, se verdadeiro, aplica o resto das restrições do nó; se falso, o nó é tratado como se as 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 âmbito de objeto envolvente. Quando architecture é replication, as restrições (required: true, o replicaCount: min: 2 adicional) aplicam-se além do NodePool referenciado. Quando architecture é standalone, essas restrições ficam inativas.

O predicado tem acesso às funções normalizadas 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 de a validação ser executada. O determinismo é preservado porque o predicado é puro em relação à instância.

Validação personalizada por campo através de validate: e validateMessage:

Algumas restrições não podem ser expressas com min / max / pattern / enum. Para essas, a forma compacta disponibiliza 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 âmbito de objeto envolvente é $. Se o predicado devolver false, a validação produz um erro utilizando validateMessage: (ou uma mensagem predefinida, se não for fornecida).

validate: trata casos para além do vocabulário normalizado do JSON Schema: validação semântica personalizada (verificação do formato semver, conteúdo JSON de uma string), regras entre campos mas de âmbito restrito 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 verdadeiramente entre campos de âmbito alargado, em que nenhum campo isolado é «aquele que está a ser validado», utiliza-se o bloco dedicado assertions:. Ver templates/assertions-block.md.

Declarar uma folha sensível — sensitive:

Uma folha de values, infra ou provides pode declarar que o dado que descreve contém 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 lê-a para derivar que anexos numa implementação tratam material declarado sensível, e transporta esse facto derivado no grafo compilado.

Declara-se no dado, não no seu localizador. A distinção é toda a razão de ser 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 o são — ambos são públicos, e ambos são renderizados em claro em cada consumidor que referencia o recurso. Marcar um localizador afirma algo falso sobre ele e propaga esse erro a tudo o que, a jusante, 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 ligue a este ponto trata material secreto, independentemente do que o preenchimento declara sobre as suas próprias folhas — não é de todo uma declaração de folha. É sensitive num slot de anexação; ver entities/component.md «Attachment Slots (Slots de anexação)».

Declarar um objeto inteiro sensível

A palavra-chave pode estar num objeto em vez de num escalar, e cobre então tudo o que está abaixo desse objeto — os próprios filhos do objeto e tudo o que estiver aninhado mais abaixo. É a declaração a preferir quando um bloco inteiro é material e marcar cada folha separadamente deixaria por marcar a próxima folha que alguém acrescente.

Os filhos do objeto têm de estar num bloco properties: explícito. Este é o único ponto em que a forma inferida dos objetos não serve, e convém conhecer a razão em vez de a contornar:

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 todo o lado, é recusado no momento da compilação — o primeiro filho é reportado 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 contém uma palavra-chave da forma compacta, e sensitive: é uma — pelo que, a partir desse ponto, cada chave irmã tem de ser também uma palavra-chave, e password não 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 num objeto» é a leitura errada a evitar: pode, e o bloco é a forma de o dizer.

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

O que a palavra-chave não faz

O nome sugere pressupostos que a palavra-chave não justifica, pelo que convém declarar claramente o seu teto:

  • Não cifra nada. É uma anotação numa declaração, não um mecanismo de confidencialidade.
  • Não valida nem recusa, exceto onde os parâmetros de um template do CloudFormation são preenchidos. Nenhum valor é aceite ou recusado por uma folha estar declarada sensível, e nenhum resultado da compilação 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, cada literal que esse mapping liga interrompe a compilação, pelo que duas compilações que difiram apenas pela declaração podem terminar de forma diferente. Ver 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).
  • Não garante que a saída renderizada esteja livre de material. Se um artefacto contém material depende de que preenchimento um autor anexou e do que o autor escreveu nos seus values — ver architecture/08-credential-model.md «What the compiler does and does not guarantee (O que o compilador garante e não garante)». Um valor declarado sensível que um autor forneceu inline é renderizado exatamente como um não declarado, onde quer que a compilação o renderize.
  • Não impõe um mecanismo de entrega. Não pode transformar um valor inline numa referência a um store, e não restringe o que a allowlist inject de um slot permite.
  • Não interrompe uma compilação, exceto através dessa recusa do CloudFormation. Os avisos que gera no momento da compilação, descritos abaixo, são advertências: a compilação é executada até ao fim e escreve os seus artefactos. Tornar fatal um aviso é uma escolha de cada organização, expressa como uma política de governação anexada à compilação, não algo que a palavra-chave faça por si só. A recusa do fornecedor do CloudFormation acima é a exceção: interrompe a compilação, porque um literal escrito num template pode ser lido por qualquer pessoa que consiga ler a stack.
  • Não muda nenhum byte renderizado na maioria dos destinos, e nesses nunca o fará. Uma plataforma de destino com uma noção própria de sensibilidade é onde uma declaração tem onde assentar; um destino sem nenhuma não lhe oferece nada para mudar, de forma permanente. O Terraform é o único destino da biblioteca-padrão com uma tal primitiva: onde a entrada de um módulo vendorizado recebe material que um autor declarou sensível, a saída renderizada ganha um ficheiro de substituição gerado que indica o atributo de sensibilidade próprio do Terraform para essa entrada — ver providers/terraform.md «Declared-sensitive module inputs (Entradas de módulo declaradas sensíveis)». Em todos os outros casos, declarar uma folha sensível num catálogo existente deixa idêntico cada artefacto renderizado.

O que muda naquilo que a ferramenta imprime

A única coisa que uma declaração muda de facto é aquilo que a ferramenta imprime para uma pessoa ler: a 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 rastreio por passagem que aggrega build --trace escreve em .trace/;
  • o bloco Values: por nó que aggrega inspect imprime para um Aggregate;
  • o bloco de anexos por folha que aggrega inspect imprime para uma Release resolvida.

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

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

A ocultação do rastreio pode ser desativada para uma única compilação, quando o valor ocultado é precisamente o que está a ser depurado: aggrega build --trace --trace-unredacted escreve os valores nos ficheiros de rastreio e marca cada um desses ficheiros com um cabeçalho que o indica. É uma escolha no momento da invocação, sem qualquer definição de configuração, alcança apenas o rastreio 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.

Os artefactos renderizados nunca são mascarados. Tudo o que está sob dist/ é emitido exatamente como a renderização o produziu, porque é o que se implementa: um marcador de posição escrito num manifesto seria uma implementação avariada em vez de uma protegida. O mascaramento abrange o que a ferramenta imprime, nunca o que escreve. Ler uma declaração como a promessa de que dist/ é seguro para publicar é o único equívoco a evitar — o teto descrito acima mantém-se inalterado, e dist/ continua tão sensível como o seu anexo que mais material transporta.

Há uma coisa que uma declaração pode acrescentar a um artefacto renderizado, e não é mascaramento: onde um destino tem uma primitiva de sensibilidade própria, a declaração é renderizada nela. O valor continua a ser escrito por inteiro — nada é ocultado nem substituído — e o que o artefacto ganha é a marcação própria do destino ao lado dele, para que as ferramentas do destino possam tratar o valor tal como o autor o declarou. Terraform é o destino que oferece uma hoje, e o que o seu atributo garante e não garante encontra-se 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 está 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 anexada a um componente — a compilação indica-o, 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 num pilar values ou infra, e uma chave de entrega que transporta 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, pelo que o que o identifica é, em vez disso, a referência que o autor escreveu: no rastreio, uma entrada locals: ou um campo source: cujo template lê uma folha declarada sensível é ocultado, e o mesmo acontece a 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 transmite a totalidade dos seus dados alcança-as todas — pelo que uma referência que não pode ser resolvida oculta em vez de imprimir.

Um documento renderizado é mostrado como uma nova renderização, e indica-o. O Workload analisado do rastreio é um documento que o template da Recipe produziu: nada nele regista de que declaração veio cada carácter, pelo que 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 rastreio 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 numa entrada workload_note ao lado do documento. Como o template vê uma cadeia onde havia uma cadeia, 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 consoante o conteúdo de um valor renderiza de outra forma contra o texto de substituição, e um dado que o eixo não nomeia é transmitido sem alteração. É uma vista de depuração do que foi renderizado, nunca uma cópia dele.

Os valores de um nó consumido são ocultados segundo as declarações desse nó, em ambas as superfícies para onde a aresta os leva. Uma vista de aresta uses reproduz o que um componente de destino publicou, pelo que é o esquema próprio do destino que a rege: uma chave provides que o destino declarou sensível é ocultada no rastreio do consumidor mesmo quando o consumidor não declara nada. Onde o próprio bloco inject da aresta encaminha 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 um anexo segue, lendo a mesma declaração, pelo que as duas cablagens não podem divergir. Os layouts de aggrega inspect mostram os pilares próprios de um nó e os seus anexos, não os valores publicados de um nó consumido, pelo que nada aí transporta uma vista entre nós a ocultar.

Um anexo escrito numa ligação é ocultado segundo as declarações da sua própria Feature, em cada superfície que o mostra. O rastreio mostra-o sob a vista da aresta uses dessa ligação, em .context.uses.<alias>.features.<slot>, e aggrega inspect imprime-o sob a linha da ligação numa Release resolvida. Em ambas, uma folha values ou infra que a sua Feature declara sensível é ocultada exatamente como o é na mesma Feature anexada diretamente ao componente, e no rastreio também é ocultada uma chave do provides resolvido do anexo que a Feature declara sensível. O seu tipo, a versão, as etiquetas e cada folha e chave provides não declaradas são impressos literalmente, para que um localizador publicado continue legível ao lado do material que localiza. Um slot que declara sensitive: true, no componente ou num socket, marca o anexo como portador de material secreto e não oculta nenhuma folha por iniciativa própria — quais as folhas ocultadas cabe à Feature declarar.

As projeções legíveis por máquina são literais por contrato, e precisam do mesmo tratamento que os ficheiros 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, incluindo uma Release. Nenhuma das duas substitui nada, e isso é deliberado: são as saídas que um script analisa e que um diff compara, pelo que uma saída que ocultasse discretamente parte de si mesma representaria de forma errada a entrada que afirma reproduzir e quebraria a ida e volta de que os seus consumidores dependem. Declarar uma folha sensível não basta para a manter fora dessas saídas: encaminhe-as, guarde-as e partilhe-as como 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 no pedido ao daemon. Assim, o grafo lido a partir de um comando e o grafo lido através do 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 os pedir.

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 transporta esse valor. Quando um template interrompe a compilação — uma asserção que chama fail, uma expressão que não pode ser avaliada, uma saída que não se lê como o documento que o template tem de produzir — e uma das suas referências alcança um dado declarado sensível, o que é comunicado provém de avaliar o mesmo template uma segunda vez, contra um contexto em que cada dado declarado sensível já se lê <redacted> — a menos que o template tenha parado numa frase que ele próprio 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 é comunicado tal como foi escrito. Quando a chamada que interrompeu a compilação é fail com uma única string entre aspas — fail "…", sem nada passado por pipe e nada composto na sua frase —, a recusa transporta 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 sua própria explicação da forma. Uma frase construída de qualquer outra forma — printf, um campo, uma variável, um valor passado por pipe a fail — é comunicada segundo os casos que se seguem.
  • Onde a segunda avaliação falha na mesma expressão pelo mesmo motivo, é a sua falha que é comunicada. A própria frase do autor mantém-se com <redacted> onde estava o valor, 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 seu texto é ocultado. Trata-se de um template cujo comportamento dependia do que o valor contém — tomou outro ramo, ou falhou noutro sítio, contra o texto de substituição — pelo que nada do que compôs pode ser mostrado. Para que uma recusa destas se explique a si própria, escreve-se a sua frase por extenso na chamada a fail, como descreve o primeiro caso. A recusa continua a interromper a compilação, e mantém o seu código.
  • Um Workload renderizado que o esquema do Workload rejeita é redigido a partir do esquema. Os campos do documento não transportam nenhum vínculo de volta aos dados que o seu template leu, pelo que, onde esse template leu um dado declarado sensível, cada constatação que poderia citar um valor enuncia em vez disso a restrição, com <redacted> no lugar do valor e um aviso que explica porquê. Não é dado nenhum conselho derivado do valor, e uma constatação que não cita nenhum valor — uma chave em falta, uma chave que o Workload não admite — lê-se 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 um passo do pipeline recusada pelo contrato de entrada declarado do passo é 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 esquema que a recusou, seguidas de um aviso que explica porquê, e nada do que a entrada transportava.
  • 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 origem não está no lockfile nem na cache, o seu arquivo em cache não corresponde ao que o lockfile regista, ou o pin registado ao lado da entidade não coincide com o lockfile. Cada linha que uma recusa assim imprime nomeia as coordenadas que a pesquisa usou, pelo que nomeia a origem pelo seu url e pela versão ou referência em que foi pedida — onde as tinha lido — com <redacted> no lugar de cada uma que um template assim produziu, e diz que o seu motivo é ocultado. Mantém o seu código e a correção que a compilação 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 anexadas a ele e a cada uma das suas ligações, uma chave de entrega que transporta material declarado, uma chave provides que o seu Component declara sensível, cada entrada de uma lista que o contexto transporta, descrita mais abaixo, e uma entrada locals: calculada a partir de qualquer um deles. Um template que não lê nenhum deles comunica exatamente como faria sem nenhuma declaração em lado nenhum, byte a byte, pelo que só uma recusa gerada por um template que leu um valor declarado é comunicada de forma diferente. A leitura é a mesma que o rastreio usa, obtida das referências que um template escreve: alcançar um objeto inteiro alcança cada folha declarada abaixo dele, pelo que pode ocultar texto que não continha nenhum valor. Um template que transmite 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 invoca pelo nome — lê cada valor declarado neles, pelo que a sua recusa é comunicada da mesma forma; dentro de um corpo range ou with o ponto é o valor que esse corpo itera ou nomeia, e transmiti-lo lê apenas o que esse valor contém. Nada aqui depende de --trace-unredacted: essa flag alcança apenas os ficheiros de rastreio, e uma recusa lê-se 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 segundo as suas. Na vista .boundary que uma FeatureRecipe de âmbito de fronteira lê, cada ligação listada em internal_uses_edges, outgoing_cross_boundary_uses_edges, incoming_cross_boundary_uses_edges e cross_boundary_uses_edges transporta os provides que o seu destino publica, ocultados onde o Component do destino declara a chave sensível, e cada entrada de feature_attachments transporta os infra desse anexo, ocultados onde a sua Feature declara a folha. No contexto de uma Feature anexada a um componente, cada entrada de .context.used_by transporta o que o componente que se liga publica, ocultado onde o Component do componente que se liga declara a chave. A mesma chave numa entrada cuja entidade não declara nada é citada tal como está, e uma entrada locals: calculada a partir de uma entrada ocultada é ocultada com ela. Percorrer uma lista, ou alcançar uma das suas entradas através de index, lê a lista inteira, pelo que conta como ler o que cada entrada transporta:

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

Isso alcança o texto de uma recusa que a compilação gera. O que é dito a um fornecedor sobre que 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, pelo que o tratamento próprio que um fornecedor 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 disto. O texto que um plugin escreve — a recusa própria de um fornecedor ou de um passo do pipeline — é a frase do plugin, transmitida tal como o plugin a escreveu. Um template avaliado fora das asserções da compilação e da sua renderização — a interpolação de parâmetros e as verificações de parâmetros num Aggregate, os templates when: e validate: de um esquema, e a resolução de uma coordenada source: que regista o seu pin — comunica a sua falha tal como falhou.

O aviso da compilação para um valor que viaja como literal

Uma compilação imprime um aviso por cada chave de entrega que transporta material declarado sensível como valor literal. Dispara quando o bloco inject de um anexo encaminha uma chave provides que a Feature do anexo declarou sensível para uma chave de entrega do componente consumidor, e o valor é efetivamente 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 aspetos dele são deliberados.

Comunica 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 anexos existe precisamente para isso. O aviso indica a um autor que valor segue esse caminho e onde, para que a escolha seja visível em vez de implícita; não afirma que a escolha seja um erro.

É uma advertência e nunca uma interrupção. A compilação é bem-sucedida e escreve os seus artefactos sem alteração. Uma organização que pretenda que uma credencial entregue como literal faça falhar a compilação exprime-o como uma política de governação sobre a compilação, que é o lugar de uma rejeição — uma regra que algumas implementações têm de quebrar não é um comportamento predefinido do compilador.

É decidido a partir da cablagem, nunca a partir do valor. O aviso lê a sensibilidade que um esquema declarou mais a entrega que o autor escreveu. Nenhum valor é inspecionado, pelo que nunca se presume que um campo seja uma credencial pelo seu nome ou pelo seu conteúdo, e um valor não declarado que por acaso contenha uma palavra-passe 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 comunica nada — o aviso segue uma entrega que aconteceu. E um slot cuja allowlist inject está vazia deixa a entrega à Recipe, pelo que o autor não escreveu nenhuma chave de entrega a comunicar e não tem nada sobre o que agir.

O aviso é uma classe própria, identificada pelo seu próprio código, e --no-unsupported-field-warnings não o silencia: essa flag abrange as notificações de fidelidade de um destino, que são um juízo diferente silenciado por razões diferentes. Chega também 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 definição está desativada por predefinição por coerência com aggrega inspect: o comando de terminal nunca chega à fase de renderização ao inspecionar um grafo, pelo que também não gera tal aviso, e uma inspeção no editor que também não gera nenhum mostra a mesma coisa que o terminal. Ativar a definição é a forma de pedir ao editor a camada adicional, e nada é escrito em disco quando isso se faz — a fase é executada e os seus artefactos são descartados. Acrescenta os avisos que uma compilação gera ao renderizar, e nenhuma das verificações em que uma compilação se interrompe. Cada problema publicado nomeia a camada que o gerou, para que um editor possa manter este aviso separado dos que as fases de resolução e de análise comunicam.

O aviso da compilação para um valor que um mapeamento renderiza sem marcação

Uma compilação imprime um aviso por cada folha values declarada sensível cuja marcação uma renderização não consegue transportar enquanto o autor ainda tem a alavanca sobre ela. Dispara numa 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 anexada a um componente, sobre uma folha que essa Feature declara. As chaves de saída do mapeamento são invenção sua, pelo que 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 um anexo começa pelo nome sob o qual está anexado, para que dois anexos de uma mesma Feature num mesmo componente se distingam. Remover o mapeamento é a alavanca: sem ele, os valores que uma renderização a partir de uma origem recebe são indexados pelos caminhos das folhas declaradas, e a marcação viaja com eles. Uma renderização só de artefactos 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 acontece com uma Feature anexada a uma fronteira, que renderiza contra um pilar values vazio — o teto descrito acima é aí permanente, e uma advertência não nomearia nada a fazer. Tal como o aviso para um valor que viaja como literal, é uma advertência e nunca uma interrupção, não muda nenhum byte renderizado, é uma classe própria com o seu próprio código, sensitivity-not-conveyed, e --no-unsupported-field-warnings não o silencia. Avisos e saída do linter descreve a sua forma completa.

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

A palavra-chave é lida no nó onde está, e a leitura segue depois 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 compõem-se ambos sobre a propriedade que os contém, pelo que uma declaração encontrada através de qualquer um deles é recolhida para essa propriedade; só uma descida por properties estende o caminho.

Um marcador é lido quer esteja ao lado de uma dessas palavras-chave quer dentro daquilo que a palavra-chave alcança, pelo que 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 esquema referenciado é também recolhido para a folha que faz a referência, no caminho dessa folha mais a cadeia abaixo dela — nunca num caminho dentro da definição, onde não vive nenhum valor escrito.
  • Ao lado de uma palavra-chave de composição (allOf / anyOf / oneOf), ou dentro das properties próprias de um ramo. Um ramo compõe-se sobre o objeto que o contém, pelo que se desce por cada ramo — incluindo os ramos condicionais de um nó escrito como JSON Schema — e uma declaração dentro de um deles é recolhida no caminho próprio da propriedade que compõe mais a sua cadeia.

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

  • Na própria folha array, não no seu tipo de elemento items. Um array cujos elementos transportam 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 declare numa entrada de parâmetro é recusado quando o Aggregate é carregado, com um diagnóstico do envelope do documento que comunica unexpected property: "sensitive" posicionado na própria chave infratora — o mesmo tratamento que qualquer chave fora desse vocabulário recebe, uma vez que o contrato de parâmetros é um objeto fechado.

A assimetria é deliberada: o eixo de sensibilidade abrange os três pilares de dados que uma entidade de catálogo declara, e um parâmetro é uma entrada do contrato de ambiente e não uma folha de pilar. Elevar material de credenciais através de um parâmetro está documentado em architecture/08-credential-model.md «Legacy charts that demand a formatted string (Charts legados que exigem uma cadeia formatada)», que enuncia o compromisso que esse caminho assume.

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 para além do vocabulário da forma compacta ($dynamicRef, unevaluatedProperties, composição not: profunda, tipos recursivos), qualquer nó pode recorrer ao 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 trata-o 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: que indica por que razão a forma que exclui é recusada. Um valor que corresponda a esse ramo é então recusado com a descrição como motivo, impressa numa única linha, em vez da formulação genérica «not allowed here (não permitido aqui)» — pelo que deve ser escrita como a frase que o autor do valor recusado deve ler. Só é usada uma descrição escrita no próprio ramo not:; uma numa entrada de $defs que o ramo apenas referencia não o é.

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

Aplica-se um limite a unevaluatedProperties e unevaluatedItems. Escrita num nó que contém também uma referência, uma palavra-chave de composição (allOf, anyOf, oneOf), uma condicional ou um esquema 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 está ao lado de allOf, pelo que { name: n, extra: 1 } é aceite embora nem Foo nem patternProperties declarem extra.

A via de escape $jsonschema: é por nó, não por documento. Um esquema 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 partilhadas — tudo num único documento.

Misturar forma compacta e JSON Schema num único documento

A forma compacta e o JSON Schema podem ser misturados livremente em qualquer fronteira entre nós. A regra de despacho é determinada 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 ao estilo do 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 → esquema filho (sem palavras-chave reservadas do JSON Schema) é tratado como forma compacta (forma inferida).
  • Um nó apenas com $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 modelo habitual é 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 suas chaves.

Para o raro caso ambíguo (por exemplo, um esquema 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 — ver «Reserved keywords at every inferred-form scope (Palavras-chave reservadas em cada âmbito em forma inferida)» acima.

Importar um contrato a partir de um ficheiro — $import:

Um contrato não tem de estar dentro da entidade que o declara. $import: nomeia um ficheiro a partir do qual o ler:

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

Todo o spec.schema provém então desse ficheiro, que se escreve exatamente como o bloco que substitui — pilares no topo, forma compacta ou YAML de JSON Schema por baixo:

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 isoladamente, com os 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 onde 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 ficheiro da entidade que o declarou, nunca em relação ao diretório a partir do qual uma compilação é executada — a mesma base que valuesMapping:, workload: e artifacts: usam. Tem de permanecer dentro desse diretório, porque cada ficheiro que uma publicação da entidade transporta é retirado daí: um caminho que sai dele, ou um caminho absoluto, nomeia um ficheiro que não viajaria com a entidade e é recusado — ver A path names content outside the entity’s own directory (Um caminho designa conteúdo fora do diretório da própria entidade). Um esquema que várias entidades partilham pertence a uma SchemaLibrary, referenciada com $ref:.
  • O ficheiro importado viaja com a entidade. Uma entidade publicada transporta cada ficheiro que o seu esquema importa, incluindo cada ficheiro de uma cadeia, pelo que uma cópia obtida de um registo lê o mesmo contrato e valida os valores escritos contra ele — ver aggrega push.
  • O ficheiro importado contém conteúdo de esquema, não um documento de entidade. Um ficheiro cujo conteúdo não seja um mapa YAML é recusado, com o nome do ficheiro.
  • Um ficheiro importado pode ser ele próprio um único $import:, que se resolve recursivamente; uma cadeia que regresse a um ficheiro que já está a ser lido é recusada, com o nome da cadeia.

A importação é lida quando a entidade é carregada, pelo que cada superfície que lê essa entidade vê o mesmo contrato: aggrega validate, uma compilação, aggrega push, aggrega inspect e o editor. Um ficheiro que não pode ser lido, ou um conteúdo que não é um esquema, é recusado nesse ponto em vez de deixar o contrato por aplicar — e um push recusa-o antes de qualquer coisa ser publicada.

$import: e $ref: não são intermutáveis. $import: nomeia um ficheiro e substitui um conteúdo inteiro; $ref: nomeia uma entrada de SchemaLibrary pela sua identidade e compõe-se em qualquer nó. Um valor $import: que contenha uma identidade de biblioteca ou um anfitrião de registo é recusado com uma indicação para $ref:. Ver cross-document-ref.md.

Espaço de nomes 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 espaço de nomes é aberto: novas anotações entram no catálogo sem edições ao vocabulário palavra-chave a palavra-chave. Os autores que escrevem x-aggrega-selector, x-aggrega-narrowed-from ou anotações futuras fazem chegar o seu conteúdo ao âmbito certo no JSON Schema resolvido sem recusa no momento da compilação.

O prefixo do espaço de nomes importa: uma gralha como x-agrega-source (falta um g) NÃO é reconhecida como palavra-chave de extensão e seria recusada pela semântica de objeto fechado nos âmbitos em forma inferida. O âmbito do prefixo funciona como uma rede de deteção de gralhas 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 transportar a cadeia do seletor que visa os Components fornecedores compatíveis.
  • x-aggrega-sensitive: — emitida por uma folha que declara sensitive: true. Ver Declarar uma folha sensível acima.

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

Exemplo completo — esquema de Component do MariaDB

Um esquema de Component representativo em forma compacta para um armazenamento de dados MariaDB, que mostra a forma inferida do princípio 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 enumera novamente cada campo obrigatório no required: do seu pai, pelo que fica consideravelmente mais longo. O ganho em compacidade acumula-se em contratos de Component maiores e é significativo o suficiente para tornar a forma compacta a superfície de escrita predefinida para schema:, parameters: e as 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 exprimir): templates/assertions-block.md.
  • Para o conjunto de pilares de dados que acolhem os esquemas 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 predefinido, segmento de registo, recurso de versão, expansão do editor): uri-grammar.md.
  • Para a escrita da entidade SchemaLibrary (onde vivem no catálogo os esquemas referenciáveis com $ref:): ../entities/schemalibrary.md.