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

Schema del catalogo di Aggrega (Feature)

Riferimento generato. Non modificarlo a mano — rigeneralo a partire dal JSON Schema pubblicato.

Id dello schema: https://aggrega.ai/schemas/feature-v1beta1.schema.json

Una funzionalità operativa modulare che si lega dinamicamente ai componenti.

Consulta il riferimento per l’authoring della Feature per una guida in prosa sulla scrittura delle entità Feature; questa pagina documenta lo schema strutturale descritto da quel riferimento.

Tipo di primo livello: object

Proprietà

ProprietàTipoObbligatoriaDescrizione
apiVersionconst “aggrega.ai/v1beta1”sìCostante: "aggrega.ai/v1beta1"
kindconst “Feature”sìCostante: "Feature"
metadataobjectsì
specobjectsìIl contratto di validazione, selezione dei destinatari e interoperabilità di una Feature del catalogo: i pilastri a forma libera (values, infra, provides) scritti tramite schema, i pilastri a forma fissa (socket di dipendenza usesSchema, slot di associazione featuresSchema), la selezione dei componenti di destinazione (appliesTo e appliesToAnyOf) e i controlli di interoperabilità.

Non sono consentite proprietà aggiuntive.

feature.metadata

ProprietàTipoObbligatoriaDescrizione
namestringsìLungo almeno 1 carattere.
versionstringsìVersionamento semantico rigoroso della funzionalità (ad es. 1.0.0). Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$.
descriptionstringnoChe cos’è questa entità e a che cosa serve, scritto per chi sta decidendo se usarla. Apri con una frase che nomina la cosa, poi aggiungi ciò di cui un lettore ha bisogno per sceglierla e usarla correttamente — che cosa si aspetta dalla Release che la distribuisce, e qualsiasi aspetto sorprendente del suo comportamento. Un breve paragrafo è la lunghezza abituale.
maintainersobject[]noElenco dei manutentori responsabili di questa entità.
licensestringnoIdentificatore SPDX della licenza del software descritto da questa entità, come MIT o AGPL-3.0. Registra le condizioni di quel software, non le condizioni di questo file.
repositorystringnoL’URL del repository Git in cui risiedono i file sorgente.
homestringnoL’URL della home page, del wiki o della documentazione di questa entità.
keywordsstring[]noUn elenco di parole chiave descrittive per la reperibilità nell’interfaccia utente.
labelsobjectnoEtichette di duck typing per la Feature. L’etichetta riservata ‘feature.aggrega.ai/kind’ con valore ‘secret’ contrassegna questa come una Feature di credenziali per l’autore e per gli strumenti che la mettono in evidenza. Una Feature di credenziali e una Feature ordinaria vengono associate allo stesso modo, sotto la stessa superficie di associazione; ciò che un’associazione produce è deciso dalla FeatureRecipe a cui il Manifest mappa il suo tipo, non dall’etichetta.
annotationsmappa di stringnoCaratteristiche intrinseche e immutabili della funzionalità, scritte dall’architetto di piattaforma nel Dominio 2. Scendono in cascata fino al contenitore .context.annotations.catalog.

Non sono consentite proprietà aggiuntive.

feature.metadata.maintainers[]
ProprietàTipoObbligatoriaDescrizione
namestringsì
emailstringno
urlstringno

Non sono consentite proprietà aggiuntive.

feature.metadata.labels

Etichette di duck typing per la Feature. L’etichetta riservata ‘feature.aggrega.ai/kind’ con valore ‘secret’ contrassegna questa come una Feature di credenziali per l’autore e per gli strumenti che la mettono in evidenza. Una Feature di credenziali e una Feature ordinaria vengono associate allo stesso modo, sotto la stessa superficie di associazione; ciò che un’associazione produce è deciso dalla FeatureRecipe a cui il Manifest mappa il suo tipo, non dall’etichetta.

ProprietàTipoObbligatoriaDescrizione
feature.aggrega.ai/kindstring (enum)noEtichetta del tipo di Feature. Il valore ‘secret’ contrassegna questa come una Feature di credenziali. Valori consentiti: "secret"

feature.spec

Il contratto di validazione, selezione dei destinatari e interoperabilità di una Feature del catalogo: i pilastri a forma libera (values, infra, provides) scritti tramite schema, i pilastri a forma fissa (socket di dipendenza usesSchema, slot di associazione featuresSchema), la selezione dei componenti di destinazione (appliesTo e appliesToAnyOf) e i controlli di interoperabilità.

ProprietàTipoObbligatoriaDescrizione
extendsstringnoRiferimento a una Feature di base da cui questa Feature eredita. Nomina la base tramite il suo metadata.name anziché tramite la coordinata di registry con cui la Feature viene pubblicata, e accetta le stesse tre forme di versione di ogni riferimento del catalogo: semplice (core/queue) per la versione più alta disponibile, esatta (core/queue:1.0.0) o un intervallo con accento circonflesso (core/queue:^1.0.0). Ciò che viene ereditato va oltre i metadati: metadata.labels e metadata.annotations della base, i suoi selettori appliesTo e appliesToAnyOf, il suo blocco interoperability, il suo usesSchema e il suo featuresSchema vengono tutti uniti verso il basso, e le sue dichiarazioni JSON Schema 2020-12 su schema vengono unite automaticamente. Il valore proprio del figlio prevale su una chiave condivisa, e i campi di identità non vengono mai ereditati.
featuresSchemamappa di objectnoDefinizioni dichiarative degli slot di associazione: i punti di legame con nome in cui questa Feature si aspetta che venga associata un’ulteriore Feature. Uno slot vincola quale riempimento può legarsi a esso (selector) e come può essere consegnato il materiale del riempimento (inject); la Feature propria del riempimento possiede il proprio contratto di values e infra. Dichiarare uno slot non chiude mai il blocco delle associazioni — un autore può associare una Feature con un nome che nessuno slot dichiara. Uno slot è un punto di legame, non un socket di dipendenza: usesSchema dichiara la superficie di topologia separata.
appliesTostringnoStringa di selettore di etichette in stile Kubernetes che seleziona i Components. I requisiti separati da virgole devono valere tutti (AND). Forme supportate: key=value, key!=value, key in (v1, v2), key notin (v1, v2), chiave semplice (etichetta presente), !key (etichetta assente). Esempio: “tier in (critical, production), !legacy”. Un selettore vuoto o assente non dichiara alcun vincolo. Il selettore viene letto rispetto a queste forme ogni volta che viene valutata un’associazione di questa Feature, e un requisito al di fuori di esse arresta la build, nominandolo: un requisito vuoto (una virgola iniziale, finale o doppia), oppure una chiave che contiene spazi bianchi o uno qualsiasi tra = ! ( ) e la virgola — quindi “!tier=frontend” viene rifiutato, e tier!=frontend è il modo in cui si esclude un valore. Un valore è il testo che segue il suo operatore, qualunque carattere contenga. Il pattern su questo campo rifiuta solo alcune forme malformate, prima che venga valutata qualsiasi associazione. Pattern: ^(?:[^()]*[()][\s\S]*|[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?(?:,[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?)*)$.
appliesToAnyOfstring o mappa di string[]noUn elenco di selettori; la Feature si applica se UN QUALSIASI elemento corrisponde (logica OR). Ogni elemento è una stringa di selettore di etichette (stessa grammatica di appliesTo; i requisiti all’interno della stringa si combinano in AND) oppure una mappa chiave-valore piatta in cui ogni coppia deve corrispondere (solo uguaglianza).
interoperabilityobjectnoControlli avanzati di sicurezza operativa e di interoperabilità.
usesSchemamappa di objectnoI socket di dipendenza che questa entità dichiara, indicizzati per nome del socket; ogni connessione tracciata attraverso un socket viene verificata rispetto alla dichiarazione di quel socket — il suo selettore e i meccanismi di iniezione che consente. Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$.
schemaobjectnoContenuto JSON Schema 2020-12 che copre i pilastri a forma libera: values (il dominio dello Sviluppatore — parametri con la forma dell’applicazione che lo Sviluppatore configura per ogni associazione di Feature nell’Aggregate); infra (il dominio dell’Operatore — manopole di dimensionamento fisico fornite dalla Release); e provides (chiavi di contesto a valle che questa Feature espone ai consumatori tramite il pipe della topologia). Accetta tre modalità di authoring tramite smistamento in base alla forma del contenuto: (1) contenuto inline (una mappa YAML che porta la forma compatta, JSON Schema YAML o una combinazione dei due); (2) sostituzione con un file tramite {$import: }, scritta in spec.schema per fornire l’intero contratto da un solo file oppure su un singolo pilastro per fornire solo quel pilastro, con un percorso relativo letto rispetto alla directory che contiene l’entità che lo ha dichiarato; (3) riferimento tra documenti tramite {$ref: #/schemas/} a una voce di una SchemaLibrary per identità di nome semplice (la versione è fornita dal file di lock per Release; nessun host di registry compare nel riferimento). I campi complementari usesSchema e featuresSchema coprono i pilastri a forma fissa (socket di dipendenza, slot di associazione); il compilatore compone i tre nell’unico schema rispetto a cui viene validata un’istanza.
assertionsmappa di stringnoValidazione tra campi in fase di build. Ogni voce è un’asserzione con nome: la chiave è un identificatore di regola stabile che compare nei messaggi di errore; il valore è una stringa di template Go con semantica di arresto {{ fail "message" }}. Più asserzioni con nome per entità vengono valutate per istanza nell’ordine dichiarato dall’autore; la prima asserzione che fallisce arresta la build. Le asserzioni della Feature vengono valutate dopo la risoluzione e l’analisi statica, prima del rendering, ed esprimono invarianti architetturali del contratto. Contesto del template: .values / .infra / .uses / .features / .metadata. Il valutatore usa missingkey=error: i riferimenti a chiavi non definite provocano un arresto con una diagnostica no-such-key. Poiché il semplice riferimento provoca l’arresto prima che possa essere eseguito qualsiasi fallback, un semplice default non fornisce un fallback per un campo opzionale su questa superficie — proteggi il riferimento con hasKey, oppure usa l’helper optional, che esegue direttamente il controllo di presenza. Nemmeno la lettura della chiave tramite index ne fornisce uno: index provoca un arresto su una chiave di mappa che la mappa non contiene, nominando la chiave.

Non sono consentite proprietà aggiuntive.

feature.spec.interoperability

Controlli avanzati di sicurezza operativa e di interoperabilità.

ProprietàTipoObbligatoriaDescrizione
conflictsWithstring[]noNomi delle Features insieme alle quali questa Feature non può raggiungere un componente, ciascuno scritto nel modo in cui il tipo di un’associazione nomina una Feature. La build si arresta prima del rendering quando un componente finisce per portare questa Feature e una Feature nominata qui — che ciascuna sia stata associata sul componente, su un sottosistema o un confine che lo contiene, su una voce di componente della Release o tramite espansione guidata da annotazioni. Basta una sola dichiarazione: l’arresto non richiede che l’altra Feature elenchi questa. I nomi vengono confrontati dopo aver rimosso qualsiasi versione, quindi una voce corrisponde a ogni versione della Feature che nomina. Due Features associate a confini fratelli che non condividono alcun componente non si incontrano mai e non provocano un arresto.

Non sono consentite proprietà aggiuntive.