Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Scrittura in forma compatta

La forma compatta è una notazione abbreviata dichiarativa in stile YAML per JSON Schema 2020-12. Gli autori scrivono i vincoli per campo come mappe YAML in stile inline-flow (port: { type: integer, min: 1, max: 65535, default: 8080 }); i nodi oggetto intermedi sono il normale annidamento YAML; i riferimenti usano il $ref: standard di JSON Schema. Il compilatore trasforma la forma compatta in JSON Schema 2020-12 prima che venga eseguita qualsiasi validazione, quindi la validazione, la segnalazione degli errori e ogni strumento che legge uno schema lavorano sul JSON Schema risolto, in qualunque forma sia stato scritto.

Questa pagina documenta il vocabolario della forma compatta, le convenzioni strutturali, lo smistamento tra oggetti in forma inferita ed esplicita, la semantica di chiusura, l’eterogeneità di type: che consente array di tipi ammessi, le parole chiave riservate in ogni ambito in forma inferita e lo spazio dei nomi di estensione x-aggrega-*. Per la semantica di risoluzione di $ref: tra documenti, vedi cross-document-ref.md. Per la grammatica di scrittura del blocco di asserzioni, vedi templates/assertions-block.md. Per l’insieme dei pilastri di dati (values:, infra:, provides:, uses:, features:, locals:, parameters:), vedi data-pillars.md.

La forma compatta è la superficie di scrittura predefinita per schema:, parameters: e le voci di SchemaLibrary. JSON Schema in YAML è un’opzione di scrittura di pari livello; entrambe le forme sono di prima classe e possono essere combinate in un unico schema. Le due forme si compilano nello stesso documento JSON Schema risolto; gli strumenti a valle e la validazione sono indifferenti al percorso di scrittura.

Vocabolario

Le parole chiave della forma compatta sono quelle delle tabelle seguenti. Gli autori le imparano una volta e le applicano in schema:, parameters: e nelle voci di SchemaLibrary.

Parole chiave di tipo e identità

Parola chiaveSignificatoSi compila in JSON Schema
typeTipo del campo (string, integer, number, boolean, object, array o un array di tipi ammessi)type:
descriptionDocumentazione leggibiledescription:
defaultValore predefinito quando il campo mancadefault:
requiredMarcatore per foglia (required: true) per i campi che devono essere presentiAggiunge il nome del campo all’array required: del genitore

Parole chiave di vincolo

Parola chiaveSignificatoSi compila in JSON Schema
enumValori ammessi (elenco)enum:
constL’unico valore ammesso — uno scalare, una mappa o un elencoconst:
minValore minimo (numerico) o lunghezza minima (stringa/array)minimum: (numerico); minLength: (stringa); minItems: (array) — scelto in base a type:
maxValore o lunghezza massimi, in parallelo a minmaximum: / maxLength: / maxItems:
minLength / maxLengthVincoli espliciti sulla lunghezza delle stringheCorrispondenza diretta con minLength: / maxLength: (da usare quando min/max sarebbero ambigui)
patternPattern regex per le stringhepattern:
formatFormato con nome che una stringa deve avere — uno tra email, uri, hostname, ipv4, ipv6, uuid, date-time, date (vedi Formati con nome)format:

Nel blocco parameters: di un Aggregate, alcuni di questi vengono controllati anche sulla dichiarazione stessa, prima che venga letto qualsiasi valore della Release. I minLength e maxLength di un parametro sono zero o più — uno negativo viene rifiutato quando l’Aggregate viene caricato — e ogni pattern, compreso uno all’interno di un contratto items, properties o valuesType annidato, deve essere un’espressione regolare che si compila, poiché il pattern viene compilato quando si legge il contratto del parametro. Ogni format, a qualsiasi profondità, deve essere uno dei formati con nome riportati sotto. Anche un min o un max su un parametro booleano o oggetto viene rifiutato, poiché la coppia non limita nulla su quei tipi. Ogni errore arresta la build nominando il parametro, che una Release lo fornisca o no. Un limite di lunghezza all’interno di un contratto annidato non è soggetto a quel minimo; vedi entities/aggregate.md per sapere dove viene eseguito ogni controllo.

Formati con nome

format nomina la forma che un valore stringa deve avere. I nomi sono quelli definiti dalla specifica JSON Schema, scritti come li scrive la specifica, e ognuno controlla ciò che la specifica gli attribuisce come significato:

NomeUn valore conforme èDefinito da
emailuna casella di posta: una parte locale (atomi separati da punti, o una stringa tra virgolette), @, poi un dominio o un letterale di indirizzo tra parentesi quadre — ops@example.com. Un nome visualizzato come Joe <joe@example.com> non è una casella di postaRFC 5321, sezione 4.1.2 (Mailbox)
uriun URI assoluto: uno schema, :, poi il resto, con ogni carattere al di fuori dell’alfabeto URI codificato in percentuale — https://example.com/a%20b, s3://bucket/key. Un riferimento relativo come /path non lo èRFC 3986 (URI)
hostnameun nome host: etichette separate da punti composte da lettere, cifre e trattini, ciascuna di 1–63 caratteri che non inizia né termina con un trattino, 253 caratteri al massimo in tutto — db-primary.data.svc.cluster.local. Un’etichetta Punycode (xn--…) è accettata così come è scritta; un carattere jolly *, un trattino basso o un punto finale noRFC 1123, sezione 2.1
ipv4quattro numeri decimali da 0 a 255, separati da punti — 192.0.2.1RFC 2673, sezione 3.2 (dotted-quad)
ipv6un indirizzo IPv6 in una qualsiasi delle sue forme testuali — completa, compressa con :: o terminante con un indirizzo IPv4 — 2001:db8::1. Una zona (%eth0) o una lunghezza di prefisso (/64) non fa parte di un indirizzoRFC 4291, sezione 2.2
uuid32 cifre esadecimali in gruppi di 8-4-4-4-12 separati da trattini, in maiuscolo o minuscolo — 2eb8aa08-aa98-11ea-b4aa-73b441d16380RFC 4122, sezione 3
date-timeun timestamp con uno scostamento — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00, un giorno che esiste nel suo mese, e un secondo intercalare solo alle 23:59 UTCRFC 3339, sezione 5.6 (date-time)
dateuna data di calendario — 2026-09-28 — il cui giorno esiste nel suo mese e annoRFC 3339, sezione 5.6 (full-date)

Un formato giudica una stringa e nient’altro: un valore di un altro tipo è il suo type a giudicarlo. E giudica solo la sintassi del valore — un nome host non viene mai risolto, un URI mai recuperato, una casella di posta mai contattata — quindi il controllo dà la stessa risposta a ogni build e non richiede rete.

Il controllo viene eseguito ovunque un valore sia validato rispetto al suo schema: il parameters: di un Aggregate, i values e gli infra che i pilastri schema: di un Component o di una Feature vincolano, i values e gli infra per arco che vincolano gli schemi di payload di un socket usesSchema:, e ogni voce di SchemaLibrary raggiunta da quegli schemi. I nomi di formato di un pilastro provides vengono giudicati al caricamento del catalogo come quelli di qualsiasi altro schema; i valori che una Recipe pubblica non vengono validati rispetto al pilastro, quindi su di essi non viene controllato alcun formato. All’interno di allOf, anyOf, oneOf e not, un valore che non rispetta il suo formato è un valore che non rispetta quel ramo, esattamente come un valore che non rispetta qualsiasi altro vincolo. Un valore non conforme viene rifiutato nominando il campo, il valore e il formato.

Un nome fuori dalla tabella viene rifiutato quando lo schema viene caricato, che un valore lo raggiunga o no, e il rifiuto elenca i nomi supportati — così un errore di battitura come emial è una diagnostica anziché un vincolo che non controlla nulla. Per una voce di SchemaLibrary, esegui aggrega validate sull’intero catalogo per vedere il nome in errore: anche una Release i cui schemi raggiungono la voce viene rifiutata, ma segnala la libreria come non trovata. password non è un formato: un campo che contiene materiale segreto dichiara invece sensitive: true.

Un limite si applica alle forme raggiunte indirettamente. Quando la forma di un campo arriva attraverso un $ref: che porta accanto a sé altre parole chiave (una mappa properties:, per esempio), attraverso il then: o l’else: di un when:, o attraverso un puntatore in una proprietà dichiarata, il suo format viene controllato sui campi che la forma dichiara direttamente e attraverso allOf — ma non all’interno di un ramo anyOf, oneOf, not o condizionale in quella forma.

Parole chiave di composizione e riferimento

Parola chiaveSignificatoSi compila in JSON Schema
$refRiferimento a un frammento JSON Pointer o a una voce esterna di SchemaLibrary$ref:
allOf / anyOf / oneOfComposizione JSON SchemaStesse parole chiave
patternPropertiesMappa con chiavi regexStessa parola chiave
valuesTypeAbbreviazione per mappe a valori tipizzati (per es. «oggetto i cui valori sono tutti stringhe»)additionalProperties: { type: <X> }

Parole chiave contenitore

Parola chiaveSignificatoSi compila in JSON Schema
itemsForma degli elementi dell’arrayitems: (forma compatta ricorsiva o JSON Schema)
propertiesDichiarazione esplicita dei figli (raramente necessaria; di solito implicita tramite la struttura YAML)properties:
additionalPropertiesSe le proprietà non dichiarate sono consentite (false su un oggetto in forma inferita, dove lo aggiunge il compilatore; su un type: object esplicito spetta a te scriverlo, e dove non lo fai si applica il valore predefinito di JSON Schema, true)additionalProperties:

Parole chiave specifiche di Aggrega

Parola chiaveSignificato
validatePredicato template Go per campo che restituisce un booleano; false arresta la validazione con validateMessage:
validateMessageMessaggio di errore che accompagna un fallimento di validate:
whenApplicazione condizionale di un sottoalbero; predicato template Go che determina se i vincoli del nodo si applicano
sensitiveDichiara che questa foglia contiene materiale segreto. Si compila in x-aggrega-sensitive: true. Vedi «Declaring a leaf sensitive (Dichiarare sensibile una foglia)» più avanti
$jsonschemaVia d’uscita — sottodocumento JSON Schema completo incorporato in questo nodo
$modeAnnotazione di smistamento facoltativa per i casi ambigui (raramente necessaria; vedi «Inferred vs explicit object form (Forma inferita e forma esplicita degli oggetti)» più avanti)

Le parole chiave prese in prestito da JSON Schema ($ref, allOf, format ecc.) riutilizzano una sintassi identica a quella di JSON Schema, quindi gli autori che conoscono già JSON Schema le riconoscono subito.

Una parola chiave il cui valore è un dato porta quel valore così come è scritto. Una mappa o un elenco dato a default, enum o const è il valore stesso, mai uno schema annidato: endpoint: { type: object, default: { host: db, port: 5432 } } imposta quell’oggetto come valore predefinito di endpoint, e mode: { type: object, const: { kind: fast } } ammette esattamente quell’oggetto — come fa mode: { const: { kind: fast } }, poiché const, come enum, rende da solo il nodo una foglia. Lo stesso vale all’interno di una via d’uscita $jsonschema:.

Come è strutturata una foglia in forma compatta

L’unità di scrittura è un nodo foglia — un campo con un dict di vincoli:

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

Pattern comuni:

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 }

Ogni foglia occupa una riga. Il dict di vincoli cattura tutto della forma del campo; la struttura del nodo genitore cattura la posizione del campo.

Oggetti annidati

La struttura degli oggetti rispecchia l’annidamento YAML. L’annidamento profondo funziona direttamente, con ogni foglia sempre su una riga:

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 }

Il compilatore inferisce la struttura degli oggetti dalla gerarchia YAML. I nodi intermedi (qui: primary, resources, requests, limits, auth) sono tipi oggetto che contengono i figli annidati. Il compilatore emette blocchi type: object e properties: espliciti nel JSON Schema risolto; l’autore non li scrive.

Forma inferita e forma esplicita degli oggetti

Un ambito oggetto in forma compatta può essere scritto in due modi:

Forma inferita — i figli direttamente sotto la chiave genitore, nessuna dichiarazione type: object:

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

Il compilatore riconosce l’ambito come oggetto perché i suoi figli sono dichiarazioni di proprietà. Emette type: object, properties: { ... } e inietta automaticamente additionalProperties: false in fase di compilazione. La semantica di chiusura fa parte del contratto della forma inferita: gli errori di battitura nei campi scritti dagli sviluppatori falliscono in modo evidente.

Forma esplicita — type: object dichiarato, properties: enumerate:

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

Il compilatore NON inietta additionalProperties: false nella forma esplicita. Gli autori che dichiarano type: object si assumono la piena responsabilità della decisione di chiusura; la forma esplicita è la superficie per le mappe realmente aperte (additionalProperties: true) e per gli oggetti che richiedono altre parole chiave JSON Schema (patternProperties, propertyNames, unevaluatedProperties).

Criterio di scrittura: usa la forma inferita per i normali oggetti chiusi (il caso comune negli schemi del catalogo). Usa la forma esplicita quando l’oggetto deve essere realmente aperto, o quando lo schema richiede parole chiave JSON Schema che la forma compatta non supporta direttamente.

Semantica di chiusura

Per convenzione, gli oggetti in forma inferita della forma compatta sono chiusi: le proprietà non dichiarate producono un errore di validazione. Il compilatore emette automaticamente additionalProperties: false su ogni ambito oggetto in forma inferita. Ciò corrisponde alla disciplina del catalogo per cui gli errori di battitura falliscono in modo evidente.

Per aprire un oggetto (consentendo proprietà aggiuntive arbitrarie), usa la forma esplicita con additionalProperties: true:

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

Per il pattern comune «oggetto i cui valori condividono tutti un tipo» (per es. una mappa da stringa a stringa per le etichette), usa valuesType::

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

valuesType: <type> si compila in additionalProperties: { type: <type> }. È un pattern abbastanza frequente da meritare un’abbreviazione con un’unica parola chiave.

Il nome di tipo semplice qui sopra è la grafia di schema: e di SchemaLibrary. In uno slot parameters: di un Aggregate, scrivi invece il valore come contratto — valuesType: { type: string }. Lo stesso vale per le altre due parole chiave il cui valore è a sua volta un contratto, items: e ogni voce sotto properties:, perché una dichiarazione di parametro e ogni contratto annidato al suo interno hanno un’unica forma. Un nome di tipo semplice in una qualsiasi di queste tre posizioni su uno slot di parametro viene rifiutato, e la diagnostica nomina quale contratto annidato lo conteneva. Vedi entities/aggregate.md per il vocabolario completo degli slot dei parametri.

Campi obbligatori

I campi obbligatori usano required: true per foglia:

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 }

Il compilatore raccoglie tutti i marcatori required: true all’interno di un ambito oggetto e li emette come array required: [field1, field2] di JSON Schema. Il marcatore conta ovunque la proprietà sia dichiarata: in un ambito in forma inferita e su una proprietà all’interno di un blocco properties: esplicito.

Un consumatore che include una voce di SchemaLibrary nel proprio schema tramite $ref: può indicarne i requisiti in entrambi i modi — un array required: [name1, name2] a livello del genitore accanto al riferimento, o un marcatore required: true su una proprietà che dichiara lì sotto properties:. Vedi cross-document-ref.md §«required: syntax under cross-document $ref: (sintassi dei campi obbligatori sotto un riferimento tra documenti)» per la regola completa.

Array

Gli array usano type: array con items: che descrive la forma degli elementi:

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 }

Per il caso comune «array di scalari tipizzati», la forma inline occupa una riga. Per gli array di oggetti, items: introduce uno schema annidato in forma compatta.

La parola chiave type: — scalare o array di tipi

type: accetta un singolo valore (type: string) o un array di tipi ammessi (type: [string, integer, boolean]). La forma array è l’espressione standard di JSON Schema 2020-12 per «questo campo accetta uno tra più tipi»:

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

Quando type: contiene un array, lo spazio dei valori è l’unione degli spazi dei valori dei tipi nominati. Gli autori che scrivono schemi che consumano la forma array devono gestire entrambe le forme a valle — il campo type del JSON Schema risolto contiene una stringa o un array, e i consumatori che percorrono lo schema risolto controllano entrambe le forme.

Parole chiave riservate in ogni ambito in forma inferita

Lo smistamento della forma inferita riconosce un piccolo insieme di parole chiave che hanno un significato a livello del vocabolario della forma compatta: description, type, default, required, le parole chiave di vincolo (enum, const, min, max, pattern, format ecc.) e le parole chiave specifiche di Aggrega (validate, validateMessage, when, sensitive). Quando una qualsiasi di queste parole chiave compare come nome di campo in un ambito oggetto in forma inferita, il compilatore legge l’ambito che la racchiude come foglia di vincolo anziché come oggetto: la parola chiave viene presa come vincolo, non come proprietà figlia, e ogni altra chiave in quell’ambito deve allora essere anch’essa una parola chiave, per cui la prima che non lo è viene rifiutata come parola chiave sconosciuta.

sensitive merita una menzione specifica qui, perché è un nome molto più plausibile per un campo reale scritto da uno sviluppatore rispetto alle altre parole chiave specifiche di Aggrega. Uno schema che ha davvero bisogno di una proprietà chiamata sensitive — un componente i cui values espongono un proprio flag sensitive, per esempio — deve dichiarare esplicitamente l’ambito che la racchiude, esattamente come farebbe per una proprietà chiamata type o default. Ci riesce la forma esplicita qui sotto oppure $mode: jsonschema sull’ambito che la racchiude: con $mode: jsonschema l’intero nodo viene letto come JSON Schema scritto dall’autore, dove sensitive è contenuto ordinario anziché la parola chiave della forma compatta.

Per gli schemi che hanno bisogno di una proprietà chiamata come una parola chiave riservata (per es. un contratto di Component con un campo description: scritto dallo sviluppatore, o un campo type:, o un campo default:), usa la forma esplicita per l’ambito in questione:

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

La forma esplicita aggira lo smistamento — properties: enumera esplicitamente i figli, quindi la collisione di parole chiave non si verifica.

Questo vincolo si applica in ogni ambito in forma inferita, ricorsivamente. Un oggetto annidato in forma inferita che contiene una proprietà chiamata come una parola chiave riservata viene letto come foglia di vincolo in quell’ambito. La soluzione è la stessa: passare l’ambito in questione alla forma esplicita.

Riferimenti

I riferimenti riprendono il $ref: di JSON Schema sia nella sintassi sia nella semantica:

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

I blocchi $defs: all’interno di uno schema in forma compatta dichiarano definizioni riutilizzabili. Ogni voce è a sua volta uno schema in forma compatta (o JSON Schema, o misto). Il riferimento avviene tramite il frammento JSON Pointer #/$defs/<Name>:

Dichiara il blocco all’interno del pilastro i cui campi vi fanno riferimento, accanto a quei campi — non accanto al pilastro. Un blocco schema: accetta al proprio livello superiore solo i nomi dei tre pilastri di dati, quindi un $defs: scritto come fratello di values: viene rifiutato quando l’entità viene caricata, con un errore che nomina la chiave in questione e l’insieme di pilastri che il blocco può contenere. Il puntatore si scrive #/$defs/<Name> in entrambi i casi.

$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" }

Per i riferimenti tra documenti che puntano a voci di SchemaLibrary, vedi cross-document-ref.md. Per l’espansione della forma abbreviata degli URI OCI, vedi uri-grammar.md.

Puntare un riferimento a una definizione, non a una proprietà

Un puntatore che nomina una voce $defs: — #/$defs/PodResources — è la forma da preferire. Un puntatore è lecito ovunque JSON Schema ne consenta uno, quindi anche un puntatore in una proprietà dichiarata viene accettato e applicato, ma viene segnalato con meno precisione, e vale la pena conoscere la differenza prima di scriverne uno.

Un campo la cui forma proviene da una voce $defs: viene controllato campo per campo: un errore viene segnalato al percorso del valore effettivamente errato, e ogni errore sotto quel campo viene segnalato, non solo il primo.

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

Un cpu errato qui viene segnalato in primary.resources.requests.cpu.

Un campo la cui forma proviene da un puntatore in una proprietà dichiarata viene controllato come parte del documento nel suo insieme. I vincoli si applicano comunque e un documento che li viola si arresta comunque — ma l’errore viene segnalato al campo che porta il puntatore anziché al valore al suo interno, e quando più campi di questo tipo sono errati contemporaneamente ne viene nominato uno solo.

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

Un cpu errato sotto secondary viene segnalato in secondary.resources.

Le due scritture accettano e rifiutano gli stessi documenti, salvo un limite su format indicato in Formati con nome: attraverso il puntatore, un format all’interno di un ramo anyOf, oneOf o not della forma non viene controllato. Per il resto, ciò che cambia è quanto ti dice il messaggio, cosa che conta soprattutto in un editor, dove il marcatore viene posizionato a partire da quel percorso. Lo stesso vale per una voce $defs: il cui puntatore rimanda a sua volta alle proprietà: raggiungere una definizione attraverso di essa eredita la segnalazione meno precisa.

Forma condizionale tramite when:

JSON Schema 2020-12 esprime la forma condizionale tramite if/then/else. La forma compatta fornisce when: come abbreviazione più diretta: un predicato template Go che, se vero, applica il resto dei vincoli del nodo; se falso, il nodo viene trattato come se i suoi vincoli non esistessero.

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

Il predicato viene valutato sui valori dell’istanza del genitore. $ si riferisce all’ambito oggetto circostante. Quando architecture è replication, i vincoli (required: true, il replicaCount: min: 2 aggiuntivo) si applicano in aggiunta al NodePool referenziato. Quando architecture è standalone, quei vincoli sono inattivi.

Il predicato ha accesso alle funzioni template Go standard (Sprig). Il compilatore compila when: nell’if/then/else di JSON Schema più un wrapper che valuta il predicato template Go prima che venga eseguita la validazione. Il determinismo è preservato perché il predicato è puro rispetto all’istanza.

Validazione personalizzata per campo tramite validate: e validateMessage:

Alcuni vincoli non si possono esprimere con min / max / pattern / enum. Per questi, la forma compatta fornisce validate: — un predicato template Go che, se falso, arresta la validazione con un errore personalizzato.

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"

Il predicato viene eseguito sul valore del campo (accessibile come .); l’ambito oggetto circostante è $. Se il predicato restituisce false, la validazione produce un errore usando validateMessage: (o un messaggio predefinito se non è fornito).

validate: gestisce i casi che vanno oltre il vocabolario standard di JSON Schema: la validazione semantica personalizzata (controllo del formato semver, contenuto JSON di una stringa), le regole tra campi ma di ambito ristretto in cui il vincolo di un campo dipende da un fratello, e i vincoli che non meritano un blocco assertions: completo.

validate: differisce da when: nel ruolo: when: attiva o disattiva l’applicazione dei vincoli; validate: è esso stesso un vincolo.

Per le regole realmente tra campi con ambito ampio, in cui nessun singolo campo è «quello che viene validato», usa il blocco dedicato assertions:. Vedi templates/assertions-block.md.

Dichiarare sensibile una foglia — sensitive:

Una foglia values, infra o provides può dichiarare che il dato che descrive contiene materiale segreto:

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 si compila nella parola chiave di estensione x-aggrega-sensitive: true su quel nodo nel JSON Schema risolto, accanto alle altre annotazioni x-aggrega-*. Il compilatore la legge per derivare quali associazioni in una distribuzione gestiscono materiale dichiarato sensibile, e porta quel fatto derivato sul grafo compilato.

Dichiaralo sul dato, non sul suo localizzatore. La distinzione è il senso stesso della parola chiave ed è facile invertirla. Il materiale di una credenziale è sensibile; il nome della risorsa che lo contiene e la chiave dati all’interno di quella risorsa non lo sono — entrambi sono pubblici, ed entrambi vengono renderizzati in chiaro in ogni consumatore che fa riferimento alla risorsa. Marcare un localizzatore afferma su di esso qualcosa di falso e propaga quell’errore a tutto ciò che, a valle, legge la dichiarazione. Nell’esempio qui sopra, origin è marcato e key deliberatamente no.

L’affermazione complementare — qualunque cosa si leghi a questo punto gestisce materiale segreto, indipendentemente da ciò che il riempimento dichiara sulle proprie foglie — non è affatto una dichiarazione di foglia. È sensitive su uno slot di associazione; vedi entities/component.md «Attachment Slots (Slot di associazione)».

Dichiarare sensibile un intero oggetto

La parola chiave può stare su un oggetto anziché su uno scalare, e allora copre tutto ciò che sta sotto quell’oggetto — i figli dell’oggetto stesso e qualsiasi cosa annidata più in profondità. È la dichiarazione da preferire quando un intero blocco è materiale e marcare ogni foglia separatamente lascerebbe non marcata la prossima foglia che qualcuno aggiunge.

I figli dell’oggetto devono stare in un blocco properties: esplicito. Questo è l’unico punto in cui la forma inferita degli oggetti non serve, e vale la pena conoscerne il motivo anziché aggirarlo:

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

Scrivere i figli direttamente accanto al marcatore, come la forma inferita degli oggetti consente ovunque altrove, viene rifiutato in fase di compilazione — il primo figlio viene segnalato come parola chiave sconosciuta, posizionata sulla chiave del figlio stesso:

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

Il rifiuto è corretto, non un limite da aggirare. Un nodo viene letto come foglia di vincolo non appena porta una parola chiave della forma compatta, e sensitive: lo è — quindi da quel punto ogni chiave sorella deve essere anch’essa una parola chiave, e password non lo è. Il blocco properties: è ciò che dice «le chiavi sotto sono nomi di proprietà, non altre parole chiave», ed è la stessa disambiguazione descritta in Forma inferita e forma esplicita degli oggetti. Leggere la diagnostica come «il marcatore non può stare su un oggetto» è l’errore di lettura da evitare: può starci, e il blocco è il modo per dirlo.

Una foglia all’interno di un oggetto dichiarato non ha bisogno di un proprio marcatore. Aggiungerne uno è innocuo e non dice nulla di nuovo, poiché la dichiarazione dell’oggetto la copre già.

Cosa non fa la parola chiave

Il nome suggerisce supposizioni che la parola chiave non giustifica, quindi se ne dichiara chiaramente il tetto:

  • Non cifra nulla. È un’annotazione su una dichiarazione, non un meccanismo di riservatezza.
  • Non valida né rifiuta, tranne dove vengono valorizzati i parametri di un template CloudFormation. Nessun valore viene accettato o rifiutato perché una foglia è dichiarata sensibile, e nessun esito della build cambia — tranne che, dove il valuesMapping di una Recipe o di una FeatureRecipe CloudFormation legge una foglia dichiarata sensibile per valorizzare i parametri di un template di origine esterna, ogni letterale che quel mapping lega arresta la build, quindi due build che differiscono solo per la dichiarazione possono terminare in modo diverso. Vedi A secret bound to a CloudFormation parameter would be written into the template (Un segreto legato a un parametro CloudFormation verrebbe scritto nel template).
  • Non garantisce che l’output renderizzato sia privo di materiale. Che un artefatto contenga materiale dipende da quale riempimento un autore ha associato e da ciò che l’autore ha scritto nei suoi values — vedi architecture/08-credential-model.md «What the compiler does and does not guarantee (Cosa il compilatore garantisce e cosa no)». Un valore dichiarato sensibile che un autore ha fornito inline viene renderizzato esattamente come uno non dichiarato, ovunque la build lo renderizzi.
  • Non impone un meccanismo di consegna. Non può trasformare un valore inline in un riferimento a uno store, e non restringe ciò che consente l’allowlist inject di uno slot.
  • Non arresta una build, se non attraverso quel rifiuto di CloudFormation. Le segnalazioni in fase di build che solleva, descritte più avanti, sono avvisi: la build viene eseguita fino in fondo e scrive i suoi artefatti. Rendere fatale una segnalazione è una scelta dell’organizzazione, espressa come policy di governance associata alla build, non qualcosa che la parola chiave fa da sola. Il rifiuto del provider CloudFormation descritto sopra è l’eccezione: arresta la build, perché un letterale scritto in un template è leggibile da chiunque possa leggere lo stack.
  • Non cambia alcun byte renderizzato sulla maggior parte dei target, e su quelli non lo farà mai. Una piattaforma di destinazione che ha una propria nozione di sensibilità è il luogo in cui una dichiarazione ha dove approdare; un target che non ne ha non offre nulla che essa possa cambiare, in modo permanente. Terraform è l’unico target della libreria standard che ha una primitiva di questo tipo: dove l’input di un modulo vendorizzato riceve materiale che un autore ha dichiarato sensibile, l’output renderizzato acquisisce un file di override generato che indica l’attributo di sensibilità proprio di Terraform per quell’input — vedi providers/terraform.md «Declared-sensitive module inputs (Input di modulo dichiarati sensibili)». Ovunque altrove, dichiarare sensibile una foglia in un catalogo esistente lascia identico ogni artefatto renderizzato.

Cosa cambia in ciò che lo strumento stampa

L’unica cosa che una dichiarazione cambia è ciò che lo strumento stampa perché una persona lo legga: il suo output di debug e il testo di un rifiuto, descritto più avanti. Sulle superfici di debug un valore dichiarato sensibile viene sostituito dal testo fisso <redacted>:

  • la traccia per passata che aggrega build --trace scrive in .trace/;
  • il blocco Values: per nodo che aggrega inspect stampa per un Aggregate;
  • il blocco delle associazioni per foglia che aggrega inspect stampa per una Release risolta.

La chiave viene sempre mantenuta e solo il suo valore viene sostituito, così chi legge vede comunque che la foglia è scritta e che qualcosa è stato oscurato. Una foglia che l’autore non ha dichiarato stampa il proprio valore alla lettera accanto a una sorella oscurata — la sostituzione segue la dichiarazione e nient’altro, quindi un campo chiamato password che non porta alcuna dichiarazione viene stampato, e un campo dichiarato chiamato key no.

Una dichiarazione raggiunge ogni foglia sotto di essa, e raggiunge le tre superfici allo stesso modo. Dove la dichiarazione sta su un oggetto, anche ogni valore annidato in quell’oggetto viene oscurato, a qualsiasi profondità — la dichiarazione dell’oggetto li nomina, quindi oscurarli non afferma nulla che l’autore non abbia scritto. La corrispondenza avviene su segmenti di percorso interi anziché sul testo, quindi una sorella il cui nome inizia semplicemente con un nome dichiarato non viene toccata: dichiarare dbPassword non oscura dbPasswordHint.

L’oscuramento della traccia può essere disattivato per una singola build, quando il valore oscurato è proprio quello di cui si sta facendo il debug: aggrega build --trace --trace-unredacted scrive i valori nei file di traccia e marca ciascuno di quei file con un’intestazione che lo dichiara. È una scelta al momento dell’invocazione senza alcuna impostazione di configurazione, raggiunge solo la traccia ed è documentata con cli/aggrega-build.md «Showing the withheld values (Mostrare i valori oscurati)». I layout di aggrega inspect hanno la propria, --unredacted, documentata con cli/aggrega-inspect.md «Showing the withheld values (Mostrare i valori oscurati)».

I limiti di quel comportamento contano più del comportamento stesso.

Gli artefatti renderizzati non vengono mai oscurati. Tutto ciò che si trova sotto dist/ viene emesso esattamente come il rendering lo ha prodotto, perché è ciò che si distribuisce: un segnaposto scritto in un manifesto sarebbe una distribuzione rotta anziché una protetta. L’oscuramento riguarda ciò che lo strumento stampa, mai ciò che scrive. Leggere una dichiarazione come la promessa che dist/ sia sicuro da pubblicare è l’unico fraintendimento da evitare — il tetto descritto sopra resta invariato, e dist/ resta sensibile quanto la sua associazione che porta più materiale.

Una cosa che una dichiarazione può aggiungere a un artefatto renderizzato, e non è un oscuramento: dove un target ha una propria primitiva di sensibilità, la dichiarazione viene renderizzata in essa. Il valore viene comunque scritto per intero — nulla viene oscurato o sostituito — e ciò che l’artefatto guadagna è la marcatura propria del target accanto al valore, così che gli strumenti del target possano trattare il valore come l’autore l’ha dichiarato. Terraform è il target che ne offre una oggi, e ciò che il suo attributo garantisce e non garantisce si trova in providers/terraform.md «Declared-sensitive module inputs (Input di modulo dichiarati sensibili)». Una tale marcatura viaggia solo dove l’identità del nome renderizzato viene ricavata dalla dichiarazione stessa; dove un template ha inventato il nome, la marcatura è assente anziché approssimata, perché marcare un valore che l’autore non ha dichiarato affermerebbe qualcosa di falso su di esso. Dove quel template è un valuesMapping — quello di una Recipe, o quello della FeatureRecipe di una Feature associata a un componente — la build lo segnala, come descritto più avanti.

L’oscuramento raggiunge ciò che una dichiarazione nomina, più ciò che si vede leggere da un template. Una foglia dichiarata in un pilastro values o infra, e una chiave di consegna che porta materiale da una chiave provides dichiarata sensibile, sono entrambe identificate per nome e oscurate. Un valore calcolato da un template finisce sotto una chiave che nessuno ha dichiarato, quindi ciò che lo identifica è invece il riferimento scritto dall’autore: nella traccia, una voce locals: o un campo source: il cui template legge una foglia dichiarata sensibile viene oscurato, e lo stesso vale per una voce locals: che legge una sorella già oscurata. La lettura è deliberatamente prudente — raggiungere un intero oggetto raggiunge ogni foglia dichiarata al suo interno, e un template che inoltra la totalità dei propri dati le raggiunge tutte — quindi un riferimento non risolvibile oscura anziché stampare.

Un documento renderizzato viene mostrato come un nuovo rendering, e lo indica. Il Workload analizzato della traccia è un documento prodotto dal template della Recipe: nulla in esso registra da quale dichiarazione provenga ciascun carattere, quindi al suo interno non c’è alcuna chiave in cui sostituire, e ricostruire il legame campo per campo significherebbe ispezionare il contenuto di un valore — cosa che il compilatore non fa. Ciò che la traccia mostra invece è lo stesso template workload: valutato di nuovo rispetto a un contesto i cui dati dichiarati sensibili si leggono già come il testo sostitutivo, annunciato in una voce workload_note accanto al documento. Poiché il template vede una stringa dove c’era una stringa, il nuovo rendering mantiene la forma del documento emesso e il testo sostitutivo occupa la posizione propria del dato oscurato. Restano due differenze e la nota le indica entrambe: un template che si ramifica sul contenuto di un valore produce un rendering diverso rispetto al testo sostitutivo, e un dato che l’asse non nomina viene portato avanti invariato. È una vista di debug di ciò che è stato renderizzato, mai una sua copia.

I valori di un nodo consumato vengono oscurati in base alle dichiarazioni di quel nodo, su entrambe le superfici a cui l’arco li porta. Una vista di un arco uses riproduce ciò che un componente target ha pubblicato, quindi è lo schema proprio del target a governarla: una chiave provides che il target ha dichiarato sensibile viene oscurata nella traccia del consumatore anche quando il consumatore non dichiara nulla. Dove il blocco inject dell’arco stesso instrada quella chiave su una chiave di consegna del componente consumatore, anche quella chiave di consegna viene oscurata — la stessa regola che segue la mappatura inject di un’associazione, leggendo la stessa dichiarazione, così che i due cablaggi non possano essere in disaccordo. I layout di aggrega inspect mostrano i pilastri propri di un nodo e le sue associazioni, non i valori pubblicati di un nodo consumato, quindi lì nulla porta una vista tra nodi da oscurare.

Un’associazione scritta su una connessione viene oscurata in base alle dichiarazioni della propria Feature, su ogni superficie che la mostra. La traccia la mostra sotto la vista dell’arco uses di quella connessione, in .context.uses.<alias>.features.<slot>, e aggrega inspect la stampa sotto la riga della connessione in una Release risolta. In entrambe, una foglia values o infra che la sua Feature dichiara sensibile viene oscurata esattamente come lo è sulla stessa Feature associata direttamente al componente, e nella traccia viene oscurata anche una chiave del provides risolto dell’associazione che la Feature dichiara sensibile. Il suo tipo, la versione, le etichette e ogni foglia e chiave provides non dichiarata vengono stampati alla lettera, così che un localizzatore pubblicato resti leggibile accanto al materiale che localizza. Uno slot che dichiara sensitive: true, sul componente o su un socket, marca l’associazione come gestore di materiale segreto e non oscura alcuna foglia di propria iniziativa — quali foglie vengano oscurate spetta alla Feature dichiararlo.

Le proiezioni leggibili da una macchina sono alla lettera per contratto, e richiedono lo stesso trattamento dei file da cui provengono. aggrega inspect --raw emette un’entità esattamente come è stata scritta, e aggrega inspect --output yaml riproduce l’entità scritta per ogni tipo, Release inclusa. Nessuno dei due sostituisce nulla, ed è voluto: sono gli output che uno script analizza e che un diff confronta, quindi un output che oscurasse in silenzio una parte di sé travisarebbe l’input che afferma di riprodurre e romperebbe il viaggio di andata e ritorno da cui dipendono i suoi consumatori. Dichiarare sensibile una foglia non basta a tenerla fuori da quegli output: inoltrali, conservali e condividili come faresti con l’Aggregate e la Release stessi.

Il grafo compilato è l’unica proiezione leggibile da una macchina che oscura, ovunque venga consegnato. --ir-graph, su aggrega inspect, aggrega validate e aggrega build, scrive il grafo risolto dall’esecuzione come JSON accanto a qualunque cosa il comando già produca, e aggrega/irGraph del daemon risponde a un editor con lo stesso grafo; in ciascun caso, un valore che un autore ha dichiarato sensibile viene sostituito esattamente come nei layout leggibili. --unredacted accanto a --ir-graph stampa invece quei valori, e lo stesso fa il campo unredacted nella richiesta al daemon. Quindi il grafo letto da un comando e il grafo letto tramite il protocollo del daemon sono lo stesso documento sotto la stessa regola di trattamento, e una pipeline o un client che ha bisogno dei valori scritti dall’autore deve chiederli.

Che cosa dice un rifiuto su un valore dichiarato

Un rifiuto sollevato da un template che legge un valore che un autore ha dichiarato sensibile non porta quel valore. Quando un template ferma la build — un’asserzione che chiama fail, un’espressione che non può essere valutata, un output che non si legge come il documento che il template deve produrre — e uno dei suoi riferimenti raggiunge un dato dichiarato sensibile, ciò che viene riportato deriva dal valutare lo stesso template una seconda volta, rispetto a un contesto in cui ogni dato dichiarato sensibile si legge già <redacted> — a meno che il template non si sia fermato su una frase che scrive esso stesso per esteso, il primo caso qui sotto:

assertion failed: the admin password <redacted> must be supplied as a reference
  • Un fail la cui frase è scritta per esteso nel template viene riportato così come è scritto. Dove la chiamata che ha fermato la build è fail con una sola stringa tra virgolette — fail "…", senza nulla passato in pipe e nulla composto nella sua frase — il rifiuto porta quella frase qualunque cosa contenga il valore e qualunque ramo abbia portato alla chiamata, perché la frase non cita nulla di ciò che il template ha letto: un’asserzione che rifiuta un’origine nella forma sbagliata mostra la propria spiegazione della forma. Una frase costruita in qualsiasi altro modo — printf, un campo, una variabile, un valore passato in pipe a fail — viene riportata secondo i casi che seguono.
  • Dove la seconda valutazione fallisce alla stessa espressione per lo stesso motivo, è il suo fallimento a essere riportato. La frase dell’autore sopravvive con <redacted> al posto del valore, e anche un valore che il template ha codificato, messo tra virgolette o trasformato in altro modo viene oscurato, perché la sostituzione avviene prima della trasformazione.
  • Dove non lo fa, il rifiuto nomina l’espressione che fallisce e dice che il suo testo è oscurato. Si tratta di un template il cui comportamento dipendeva da ciò che il valore contiene — ha preso un altro ramo, o è fallito altrove, rispetto al testo sostitutivo — quindi nulla di ciò che ha composto può essere mostrato. Perché un rifiuto del genere si spieghi da sé, scrivi la sua frase per esteso nella chiamata fail, come descrive il primo caso. Il rifiuto ferma comunque la build, e mantiene il suo codice.
  • Un Workload renderizzato che lo schema del Workload rifiuta viene formulato a partire dallo schema. I campi del documento non portano alcun collegamento ai dati letti dal suo template, quindi dove quel template ha letto un dato dichiarato sensibile, ogni rilievo che potrebbe citare un valore enuncia invece il vincolo, con <redacted> al posto del valore e un avviso che spiega perché. Non viene dato alcun consiglio derivato dal valore, e un rilievo che non cita alcun valore — una chiave mancante, una chiave che il Workload non ammette — si legge come 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)
  • Un input with di un passo della pipeline rifiutato dal contratto di input dichiarato del passo viene formulato a partire dal contratto dove il template with legge un dato dichiarato sensibile: ogni posizione che fallisce nell’input e la parola chiave dello schema che l’ha rifiutata, seguite da un avviso che spiega perché, e nulla di ciò che l’input portava.
  • Un rifiuto che nomina una coordinata source: viene formulato a partire da ciò che nulla di dichiarato ha prodotto dove un template source: ha prodotto quella coordinata leggendo un dato dichiarato sensibile — la sorgente non è nel lockfile o nella cache, il suo archivio in cache non corrisponde a ciò che il lockfile registra, oppure il pin registrato accanto all’entità non concorda con il lockfile. Ogni riga che un tale rifiuto stampa nomina le coordinate usate dalla ricerca, quindi nomina la sorgente tramite il suo url e la versione o il riferimento a cui è stata richiesta — dove li aveva letti — con <redacted> al posto di ciascuna che un tale template ha prodotto, e dice che il suo motivo è oscurato. Mantiene il suo codice e il rimedio che la build fornisce per quel codice:
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

Ciò che conta come dichiarato è ciò che le dichiarazioni nominano, in ogni parte del contesto che un template può leggere: i values e gli infra propri del componente, le Features associate a esso e a ciascuna delle sue connessioni, una chiave di consegna che porta materiale dichiarato, una chiave provides che il suo Component dichiara sensibile, ogni voce di una lista che il contesto porta, descritta più avanti, e una voce locals: calcolata da uno qualsiasi di essi. Un template che non ne legge nessuno riporta esattamente come farebbe senza alcuna dichiarazione da nessuna parte, byte per byte, quindi solo un rifiuto sollevato da un template che ha letto un valore dichiarato viene riportato in modo diverso. La lettura è quella che usa la traccia, ricavata dai riferimenti che un template scrive: raggiungere un intero oggetto raggiunge ogni foglia dichiarata al suo interno, quindi può oscurare un testo che non conteneva alcun valore. Un template che inoltra tutti i propri dati in una volta — il punto o $ senza nulla dopo, passato a una funzione come toJson, stampato, o passato a un template che invoca per nome — legge ogni valore dichiarato in essi, quindi il suo rifiuto viene riportato allo stesso modo; all’interno di un corpo range o with il punto è il valore che quel corpo itera o nomina, e inoltrarlo legge solo ciò che quel valore contiene. Nulla qui dipende da --trace-unredacted: quel flag raggiunge solo i file di traccia, e un rifiuto si legge allo stesso modo con e senza di esso.

Un valore dichiarato viene oscurato ovunque si trovi, anche all’interno di una lista. Le voci di una stessa lista sono governate da entità diverse, e ciascuna voce viene oscurata in base alle proprie. Sulla vista .boundary letta da una FeatureRecipe con ambito di confine, ogni connessione elencata in internal_uses_edges, outgoing_cross_boundary_uses_edges, incoming_cross_boundary_uses_edges e cross_boundary_uses_edges porta i provides che il suo target pubblica, oscurati dove il Component del target dichiara sensibile la chiave, e ogni voce di feature_attachments porta gli infra di quell’associazione, oscurati dove la sua Feature dichiara la foglia. Nel contesto di una Feature associata a un componente, ogni voce di .context.used_by porta ciò che pubblica il componente che si connette, oscurato dove il Component del componente che si connette dichiara la chiave. La stessa chiave su una voce la cui entità non dichiara nulla viene citata così com’è, e una voce locals: calcolata da una voce oscurata viene oscurata con essa. Iterare su una lista, o raggiungere una delle sue voci tramite index, legge l’intera lista, quindi conta come leggere ciò che ogni voce porta:

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

Questo raggiunge il testo di un rifiuto che la build solleva. Ciò che viene detto a un provider su quale parte del suo input provenga da un valore dichiarato — i valori prodotti da un valuesMapping, un documento workload: renderizzato, ogni voce artifacts:, ogni campo di una voce omits: — non tiene conto di un valore letto dall’interno di una lista, quindi la gestione propria di un provider di un valore dichiarato, compreso il rifiuto CloudFormation di un letterale legato descritto sopra, non lo raggiunge.

Alcuni rifiuti stanno al di fuori di questo. Il testo che scrive un plugin — il rifiuto proprio di un provider o di un passo della pipeline — è la frase del plugin, riportata come il plugin l’ha scritta. Un template valutato al di fuori delle asserzioni della build e del suo rendering — l’interpolazione dei parametri e i controlli dei parametri in un Aggregate, i template when: e validate: di uno schema, e la risoluzione di una coordinata source: che registra il suo pin — riporta il suo fallimento così come è fallito.

La segnalazione della build per un valore che viaggia come letterale

Una build stampa una segnalazione per ogni chiave di consegna che porta materiale dichiarato sensibile come valore letterale. Scatta quando il blocco inject di un’associazione instrada una chiave provides che la Feature dell’associazione ha dichiarato sensibile su una chiave di consegna del componente consumatore, e il valore viene effettivamente consegnato:

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

Tre aspetti sono deliberati.

Riporta come viaggia un valore, non che qualcosa sia sbagliato. Consegnare un letterale è spesso l’unica cosa che un target accetta, e un’intera famiglia di associazioni esiste proprio per fare questo. La segnalazione dice a un autore quale valore prende quella strada e dove, così che la scelta sia visibile anziché implicita; non afferma che la scelta sia un errore.

È un avviso e mai un arresto. La build riesce e scrive i suoi artefatti invariati. Un’organizzazione che vuole che una credenziale consegnata come letterale faccia fallire la build lo esprime come policy di governance sulla build, che è il luogo a cui appartiene un rifiuto — una regola che alcune distribuzioni devono infrangere non è un comportamento predefinito del compilatore.

Viene deciso dal cablaggio, mai dal valore. La segnalazione legge la sensibilità che uno schema ha dichiarato più la consegna che l’autore ha scritto. Nessun valore viene ispezionato, quindi non si presume mai che un campo sia una credenziale in base al suo nome o al suo contenuto, e un valore non dichiarato che per caso contiene una password non solleva nulla.

Due casi restano deliberatamente silenziosi. Una chiave di consegna la cui chiave provides referenziata non pubblica nulla non consegna alcun letterale e non riporta nulla — la segnalazione segue una consegna che è avvenuta. E uno slot la cui allowlist inject è vuota lascia la consegna alla Recipe, quindi l’autore non ha scritto alcuna chiave di consegna da riportare e non ha nulla su cui agire.

La segnalazione è una classe a sé, identificata dal proprio codice, e --no-unsupported-field-warnings non la silenzia: quel flag copre le notifiche di fedeltà di un target, che sono un giudizio diverso, silenziato per ragioni diverse. Raggiunge anche l’editor, dove appare come un problema sull’Aggregate, ogni volta che il server di linguaggio è in esecuzione con --build-on-inspect (o la chiave di configurazione serve.build_on_inspect) attivato. Quell’impostazione è disattivata per impostazione predefinita per coerenza con aggrega inspect: il comando da terminale non raggiunge mai la fase di rendering mentre ispeziona un grafo, quindi non solleva nemmeno lui una tale segnalazione, e un’ispezione nell’editor che non ne solleva nessuna ti mostra la stessa cosa che mostra il terminale. Attivare l’impostazione è il modo in cui chiedi all’editor lo strato aggiuntivo, e quando lo fai non viene scritto nulla su disco — la fase viene eseguita e i suoi artefatti vengono scartati. Aggiunge le segnalazioni che una build solleva durante il rendering, e nessuno dei controlli su cui una build si arresta. Ogni problema pubblicato nomina lo strato che lo ha sollevato, così che un editor possa tenere questa segnalazione separata da quelle che riportano le fasi di risoluzione e di analisi.

La segnalazione della build per un valore che una mappatura renderizza senza marcatura

Una build stampa una segnalazione per ogni foglia values dichiarata sensibile la cui marcatura un rendering non può portare mentre l’autore ha ancora in mano la leva su di essa. Scatta su un rendering da un source: i cui valori sono l’output di un valuesMapping — quello di una Recipe, su una foglia che il suo Component dichiara, o quello della FeatureRecipe di una Feature associata a un componente, su una foglia che quella Feature dichiara. Le chiavi di output della mappatura sono una sua invenzione, quindi nessuna dichiarazione ne nomina alcuna e il target non riceve alcuna marcatura per chiave per la foglia:

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

La riga nomina la foglia alla sua coordinata scritta dall’autore e la Recipe o la FeatureRecipe la cui mappatura condiziona il collegamento, perché la dichiarazione e la mappatura sono scritte in due entità diverse; la riga di un’associazione inizia con il nome sotto cui è associata, così che due associazioni di una stessa Feature su uno stesso componente vengano distinte. Rimuovere la mappatura è la leva: senza di essa, i valori che un rendering da sorgente riceve sono indicizzati dai percorsi delle foglie dichiarate, e la marcatura viaggia con essi. Un rendering di soli artefatti e un rendering di solo workload restano silenziosi, perché non consegnano al loro target alcuna mappa di valori, e lo stesso vale per una Feature associata a un confine, che renderizza rispetto a un pilastro values vuoto — lì il tetto descritto sopra è permanente, e un avviso non nominerebbe nulla da fare. Come la segnalazione per un valore che viaggia come letterale, è un avviso e mai un arresto, non cambia alcun byte renderizzato, è una classe a sé con il proprio codice, sensitivity-not-conveyed, e --no-unsupported-field-warnings non la silenzia. Avvertimenti e output del linter ne riporta la forma completa.

Dove la dichiarazione viene letta, e dove no

La parola chiave viene letta sul nodo su cui si trova, e la lettura segue poi ogni via attraverso cui una dichiarazione può raggiungere quel dato: mappe di proprietà annidate, ogni ramo di composizione e il target di un $ref. Un ramo e un target di riferimento si compongono entrambi sulla proprietà che li porta, quindi una dichiarazione trovata attraverso l’uno o l’altro viene raccolta per quella proprietà; solo una discesa in properties estende il percorso.

Un marcatore viene letto sia che si trovi accanto a una di quelle parole chiave sia che si trovi all’interno di ciò che la parola chiave raggiunge, quindi due forme non richiedono un posizionamento deliberato:

  • Accanto a un $ref, o all’interno del target del riferimento. Un marcatore sulla foglia che fa riferimento dichiara quella foglia. Un marcatore nello schema referenziato viene raccolto anch’esso per la foglia che fa riferimento, al percorso di quella foglia più la catena sottostante — mai a un percorso all’interno della definizione, dove non vive alcun valore scritto dall’autore.
  • Accanto a una parola chiave di composizione (allOf / anyOf / oneOf), o all’interno delle properties proprie di un ramo. Un ramo si compone sull’oggetto che lo porta, quindi si discende in ogni ramo — compresi i rami condizionali di un nodo scritto come JSON Schema — e una dichiarazione all’interno di uno di essi viene raccolta al percorso proprio della proprietà che compone più la sua catena.

Una forma richiede invece che il marcatore sia posizionato deliberatamente:

  • Sulla foglia array stessa, non sul suo tipo di elemento items. Un array i cui elementi portano materiale viene dichiarato sensibile sull’array, perché un tipo di elemento non è una mappa di proprietà e non vi si discende.

parameters: è un vocabolario diverso

sensitive non fa parte del vocabolario del contratto tipizzato di parameters:. Un Aggregate che lo dichiara su una voce di parametro viene rifiutato quando l’Aggregate viene caricato, con una diagnostica dell’involucro del documento che riporta unexpected property: "sensitive" posizionata sulla chiave incriminata stessa — lo stesso trattamento che riceve qualsiasi chiave al di fuori di quel vocabolario, poiché il contratto dei parametri è un oggetto chiuso.

L’asimmetria è deliberata: l’asse di sensibilità copre i tre pilastri di dati che un’entità di catalogo dichiara, e un parametro è un input del contratto d’ambiente anziché una foglia di pilastro. Sollevare materiale di credenziali attraverso un parametro è documentato in architecture/08-credential-model.md «Legacy charts that demand a formatted string (Chart legacy che richiedono una stringa formattata)», che enuncia il compromesso che quel percorso comporta.

Composizione con allOf, anyOf, oneOf

Le parole chiave di composizione funzionano come in 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 }

Il compilatore emette le stesse parole chiave di composizione nel JSON Schema risolto. Le voci che compongono possono essere ciascuna in forma compatta, JSON Schema o riferimenti $ref:. La combinazione all’interno di una composizione è supportata.

La via d’uscita — $jsonschema:

Per i casi che vanno oltre il vocabolario della forma compatta ($dynamicRef, unevaluatedProperties, composizione not: profonda, tipi ricorsivi), qualsiasi nodo può passare al 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 }

Il blocco $jsonschema: contiene YAML JSON Schema; il compilatore lo tratta come un passaggio trasparente — il contenuto va direttamente nel documento JSON Schema risolto alla posizione di quel nodo. Validazione, comunicazione degli errori e strumenti lavorano tutti sul documento risolto; la via d’uscita è puramente una comodità di scrittura.

Un ramo not: può avere una description: che spiega perché la forma che esclude viene rifiutata. Un valore che corrisponde a quel ramo viene allora rifiutato con la descrizione come motivo, stampata su una sola riga, al posto della dicitura generica «not allowed here (non consentito qui)» — quindi scrivila come la frase che l’autore del valore rifiutato dovrebbe leggere. Viene usata solo una descrizione scritta sul ramo not: stesso; non una su una voce di $defs a cui il ramo fa solo riferimento.

Ogni nodo all’interno del blocco viene letto come JSON Schema, e una parola chiave della forma compatta scritta lì mantiene il suo significato compatto (min: 3 su una stringa è comunque una lunghezza minima). Un $ref nel blocco si risolve come uno al di fuori: #/$defs/Foo nomina una voce del $defs: del pilastro, quindi l’esempio dichiara Foo lì, e un riferimento che nomina una voce che nessuno ha dichiarato viene rifiutato quando l’entità viene caricata. $dynamicRef si risolve rispetto a un $dynamicAnchor, quindi si può scrivere una forma ricorsiva; un valore che fallisce in profondità nella ricorsione viene riportato al campo che lo contiene — tree.children, per un name errato due livelli più in basso in un albero i cui elementi children sono { $dynamicRef: "#node" }.

Un limite si applica a unevaluatedProperties e unevaluatedItems. Scritto in un nodo che porta anche un riferimento, una parola chiave di composizione (allOf, anyOf, oneOf), un condizionale o uno schema dipendente, ciascuno dei due viene caricato ma non applicato — e unevaluatedItems non viene applicato nemmeno accanto a contains. Nell’esempio qui sopra, unevaluatedProperties: false sta accanto ad allOf, quindi { name: n, extra: 1 } viene accettato sebbene né Foo né patternProperties dichiarino extra.

La via d’uscita $jsonschema: è per nodo, non per documento. Uno schema può usare la forma compatta per le parti semplici, la via d’uscita JSON Schema per l’unico campo complesso e $ref: per le forme condivise — tutto in un unico documento.

Combinare forma compatta e JSON Schema in un unico documento

La forma compatta e JSON Schema possono essere combinati liberamente a qualsiasi confine tra nodi. La regola di smistamento è guidata dalla forma del contenuto:

  • Un nodo che contiene $jsonschema: viene trattato come JSON Schema (la via d’uscita).
  • Un nodo che contiene parole chiave di primo livello in stile JSON Schema (type:, properties:, additionalProperties:, if:, ecc.) viene trattato come JSON Schema (la forma esplicita).
  • Un nodo che contiene solo voci nome di proprietà → schema figlio (nessuna parola chiave riservata di JSON Schema) viene trattato come forma compatta (forma inferita).
  • Un nodo con solo $ref: è un passaggio di riferimento.
  • Un nodo con allOf: / anyOf: / oneOf: è una composizione; ogni voce viene smistata in modo indipendente.

Per le foglie in forma compatta, il modello standard è field_name: { type: ..., constraints... } — una mappa YAML che contiene un vocabolario noto della forma compatta. Lo smistamento riconosce i dizionari di vincoli dalle loro chiavi.

Per il raro caso ambiguo (ad esempio uno schema in forma compatta con un campo chiamato letteralmente type che lo smistamento in forma inferita interpreterebbe come la parola chiave di JSON Schema), la forma esplicita è la correzione canonica — vedi «Reserved keywords at every inferred-form scope (Parole chiave riservate in ogni ambito in forma inferita)» sopra.

Importare un contratto da un file — $import:

Un contratto non deve per forza stare all’interno dell’entità che lo dichiara. $import: nomina un file da cui leggerlo:

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

L’intero spec.schema proviene allora da quel file, che si scrive esattamente come il blocco che sostituisce — i pilastri in cima, forma compatta o YAML JSON Schema sotto:

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

Un singolo pilastro può essere importato da solo, con i suoi fratelli scritti inline accanto a esso:

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

La stessa forma funziona sul valueSchema: e sull’infraSchema: di un socket usesSchema:.

Le regole che lo governano:

  • $import: è l’unica chiave nella posizione in cui compare. Un fratello scritto accanto a esso viene rifiutato, anziché scartare uno dei due.
  • Un percorso relativo viene letto rispetto alla directory che contiene il file dell’entità che lo ha dichiarato, mai rispetto alla directory da cui viene eseguita una build — la stessa base che usano valuesMapping:, workload: e artifacts:. Deve restare all’interno di quella directory, perché ogni file che una pubblicazione dell’entità porta viene preso da lì: un percorso che ne esce, o un percorso assoluto, nomina un file che non viaggerebbe con l’entità e viene rifiutato — vedi A path names content outside the entity’s own directory (Un percorso indica contenuti esterni alla directory dell’entità). Uno schema condiviso da più entità appartiene a una SchemaLibrary, referenziata con $ref:.
  • Il file importato viaggia con l’entità. Un’entità pubblicata porta ogni file che il suo schema importa, compreso ogni file di una catena, così che una copia scaricata da un registro legga lo stesso contratto e validi i valori scritti in base a esso — vedi aggrega push.
  • Il file importato porta contenuto di schema, non un documento di entità. Un file il cui contenuto non è una mappa YAML viene rifiutato, nominando il file.
  • Un file importato può essere esso stesso un singolo $import:, che si risolve ricorsivamente; una catena che ritorna a un file già in lettura viene rifiutata, nominando la catena.

L’importazione viene letta quando l’entità viene caricata, quindi ogni superficie che legge quell’entità vede lo stesso contratto: aggrega validate, una build, aggrega push, aggrega inspect e l’editor. Un file che non può essere letto, o un contenuto che non è uno schema, viene rifiutato in quel momento anziché lasciare il contratto non applicato — e un push lo rifiuta prima che qualcosa venga pubblicato.

$import: e $ref: non sono intercambiabili. $import: nomina un file e sostituisce un contenuto intero; $ref: nomina una voce di SchemaLibrary per identità e si compone in qualsiasi nodo. Un valore $import: che porta un’identità di libreria o un host di registro viene rifiutato con un’indicazione verso $ref:. Vedi cross-document-ref.md.

Namespace di estensione Aggrega — x-aggrega-*

La forma compatta riconosce qualsiasi parola chiave con prefisso x-aggrega- come estensione specifica di Aggrega. Il namespace è aperto: nuove annotazioni entrano nel catalogo senza modifiche al vocabolario per ogni parola chiave. Gli autori che scrivono x-aggrega-selector, x-aggrega-narrowed-from o annotazioni future fanno arrivare il loro contenuto all’ambito giusto nel JSON Schema risolto senza rifiuto in fase di compilazione.

Il prefisso del namespace conta: un refuso come x-agrega-source (manca una g) NON viene riconosciuto come parola chiave di estensione e verrebbe rifiutato dalla semantica a oggetto chiuso negli ambiti in forma inferita. L’ambito del prefisso funge da rete di rilevamento dei refusi per la superficie di annotazione del catalogo.

Annotazioni x-aggrega-* specifiche vengono emesse dal compilatore in punti ben noti della pipeline:

  • x-aggrega-selector: — emessa dalla sintesi di usesSchema: e featuresSchema: per portare la stringa del selettore che seleziona i Components provider compatibili.
  • x-aggrega-sensitive: — emessa da una foglia che dichiara sensitive: true. Vedi Dichiarare sensibile una foglia sopra.

Gli autori di catalogo che scrivono le proprie parole chiave di estensione usano lo stesso namespace; gli strumenti a valle che consumano il JSON Schema compilato leggono le chiavi x-aggrega-* senza entrare in collisione con lo spazio delle parole chiave proprio di JSON Schema.

Esempio svolto — schema di Component MariaDB

Uno schema di Component rappresentativo in forma compatta per un datastore MariaDB, che mostra la forma inferita in tutto lo schema, vincoli di foglia misti, riferimenti, forma condizionale e un oneOf svolto per il blocco di autenticazione:

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 }

Scritto come YAML JSON Schema, lo stesso contratto esplicita per ogni oggetto type: object, properties: e additionalProperties: false, ed elenca di nuovo ogni campo obbligatorio nel required: del suo genitore, quindi risulta notevolmente più lungo. Il guadagno in compattezza si accumula nei contratti di Component più grandi ed è abbastanza significativo da rendere la forma compatta la superficie di scrittura predefinita per schema:, parameters: e le voci di SchemaLibrary.

Riferimenti incrociati

  • Per la semantica di risoluzione dei $ref: tra documenti (la sintassi di required: accanto a un riferimento tra documenti; l’espansione delle catene da libreria a libreria; il consumatore che restringe la libreria): cross-document-ref.md.
  • Per la grammatica di scrittura del blocco assertions: (regole tra campi che validate: in forma compatta non può esprimere): templates/assertions-block.md.
  • Per l’insieme dei pilastri di dati che ospitano gli schemi in forma compatta (values:, infra:, provides:, uses:, features:, locals:, parameters:): data-pillars.md.
  • Per le regole di espansione della forma abbreviata degli URI OCI (dominio predefinito, segmento del registro, fallback della versione, espansione dell’editore): uri-grammar.md.
  • Per la scrittura dell’entità SchemaLibrary (dove vivono nel catalogo gli schemi referenziabili con $ref:): ../entities/schemalibrary.md.