Schema dell’intento dello sviluppatore di Aggrega (Aggregate)
Riferimento generato. Non modificarlo a mano — rigeneralo a partire dal JSON Schema pubblicato.
Id dello schema: https://aggrega.ai/schemas/aggregate-v1beta1.schema.json
L’architettura AI ricorsiva e parametrizzata. Funge sia da radice di una build sia da modulo riutilizzabile.
Consulta il riferimento per l’authoring dell’Aggregate per una guida in prosa sulla scrittura delle entità Aggregate; questa pagina documenta lo schema strutturale descritto da quel riferimento.
Tipo di primo livello: object
Proprietà
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | sì | Costante: "aggrega.ai/v1beta1" |
kind | const “Aggregate” | sì | Costante: "Aggregate" |
metadata | object | sì | |
defs | string[] | no | Blocco opzionale per le ancore YAML standard (& e *), che mantiene l’Aggregate DRY pur conservando per il compilatore un dizionario piatto O(1). Rispecchia il blocco equivalente sul Manifest. |
spec | object | sì | La superficie dell’intento dello sviluppatore: il contratto globale dei parametri, gli import di aggregati annidati, l’API pubblica dei componenti esportati, i raggruppamenti in sottosistemi e le istanze di componente che compongono il modulo. |
Non sono consentite proprietà aggiuntive.
aggregate.metadata
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
name | string | sì | Lungo almeno 1 carattere. |
version | string | sì | Versionamento semantico rigoroso del modulo aggregato. 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-]+)*))?$. |
description | string | no | |
maintainers | object[] | no | Elenco dei manutentori responsabili di questa entità. |
license | string | no | Identificatore 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. |
repository | string | no | L’URL del repository Git in cui risiedono i file sorgente. |
home | string | no | L’URL della home page, del wiki o della documentazione di questa entità. |
keywords | string[] | no | Un elenco di parole chiave descrittive per la reperibilità nell’interfaccia utente. |
labels | mappa di string | no | Etichette di duck typing a livello di modulo per la scoperta nel catalogo, la valutazione delle policy e il filtraggio in Studio/IDE. Queste etichette descrivono l’identità dell’Aggregate come modulo riutilizzabile (ad es. aggregate.aggrega.ai/tier: infrastructure, aggregate.aggrega.ai/compliance: pci-dss). NON si propagano in cascata ai nodi dei componenti figli — le etichette dei componenti provengono esclusivamente dall’entità di catalogo Component nel Dominio 2. |
Non sono consentite proprietà aggiuntive.
aggregate.metadata.maintainers[]
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
name | string | sì | |
email | string | no | |
url | string | no |
Non sono consentite proprietà aggiuntive.
aggregate.spec
La superficie dell’intento dello sviluppatore: il contratto globale dei parametri, gli import di aggregati annidati, l’API pubblica dei componenti esportati, i raggruppamenti in sottosistemi e le istanze di componente che compongono il modulo.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
parameters | mappa di object | no | Contratto globale dell’ambiente. Ogni voce è un oggetto di contratto tipizzato che usa il sottoinsieme del vocabolario in forma compatta (type, description, default, enum, min/max, minLength/maxLength, pattern, format, validate, validateMessage, required, items, valuesType, properties). La struttura annidata si esprime tramite il sottocampo properties: della forma tipizzata. La Release può adempierlo inline (parameters: {…}) oppure tramite l’import di un unico file sorgente (parameters: {$import: |
aggregates | mappa di object | no | Aggregati annidati che fungono da moduli importati. Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$. |
exportedComponents | mappa di string | no | L’interfaccia dell’API pubblica. Associa un nome pubblico esposto a un ID di componente interno. Gli Aggregates genitori che importano questo modulo fanno riferimento ai componenti tramite questi nomi pubblici. |
subsystems | mappa di subsystem | no | Raggruppamenti logici con nome dei componenti di un Aggregate in sottosistemi. Mutuamente esclusivi con i componenti di primo livello — la dichiarazione di entrambi viene rifiutata. Un sottosistema che l’autore chiama default è un normale sottosistema dichiarato, distinto dal default sintetizzato che il compilatore crea per un Aggregate con soli componenti. Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$. |
components | mappa di component_instance | no | La mappa dei componenti logici atomici che compongono questo Aggregate, scritti direttamente al primo livello. I componenti di primo livello e i sottosistemi sono mutuamente esclusivi — la dichiarazione di entrambi viene rifiutata. Quando i componenti sono scritti qui (senza sottosistemi), il compilatore li raccoglie al caricamento in un sottosistema default sintetizzato, e l’IR marca quel sottosistema come sintetizzato. Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$. |
Non sono consentite proprietà aggiuntive.
Definizioni
inject_delivery
Un singolo meccanismo di consegna, scritto come array di voci. Ogni voce porta un ‘in’ (identificatore locale — nome di variabile d’ambiente, percorso di file, flag di argomento o chiave personalizzata specifica del meccanismo) più esattamente uno tra ‘from’ (una chiave provides da risolvere) e ‘value’ (una stringa letterale, che può contenere espressioni di template Go valutate alla risoluzione dell’auto-iniezione). ‘from’ si risolve rispetto ai provides della destinazione nel contesto uses[].inject, rispetto ai provides che la FeatureRecipe dell’associazione pubblica nel contesto features.
Tipo: object[]
inject_block
Instradamento agnostico dell’iniezione. Associa variabili locali a chiavi provides della destinazione (uses[].inject), alle chiavi provides che la FeatureRecipe di un’associazione pubblica (features.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
env | inject_delivery | no | Un singolo meccanismo di consegna, scritto come array di voci. Ogni voce porta un ‘in’ (identificatore locale — nome di variabile d’ambiente, percorso di file, flag di argomento o chiave personalizzata specifica del meccanismo) più esattamente uno tra ‘from’ (una chiave provides da risolvere) e ‘value’ (una stringa letterale, che può contenere espressioni di template Go valutate alla risoluzione dell’auto-iniezione). ‘from’ si risolve rispetto ai provides della destinazione nel contesto uses[].inject, rispetto ai provides che la FeatureRecipe dell’associazione pubblica nel contesto features. |
file | inject_delivery | no | Un singolo meccanismo di consegna, scritto come array di voci. Ogni voce porta un ‘in’ (identificatore locale — nome di variabile d’ambiente, percorso di file, flag di argomento o chiave personalizzata specifica del meccanismo) più esattamente uno tra ‘from’ (una chiave provides da risolvere) e ‘value’ (una stringa letterale, che può contenere espressioni di template Go valutate alla risoluzione dell’auto-iniezione). ‘from’ si risolve rispetto ai provides della destinazione nel contesto uses[].inject, rispetto ai provides che la FeatureRecipe dell’associazione pubblica nel contesto features. |
arg | inject_delivery | no | Un singolo meccanismo di consegna, scritto come array di voci. Ogni voce porta un ‘in’ (identificatore locale — nome di variabile d’ambiente, percorso di file, flag di argomento o chiave personalizzata specifica del meccanismo) più esattamente uno tra ‘from’ (una chiave provides da risolvere) e ‘value’ (una stringa letterale, che può contenere espressioni di template Go valutate alla risoluzione dell’auto-iniezione). ‘from’ si risolve rispetto ai provides della destinazione nel contesto uses[].inject, rispetto ai provides che la FeatureRecipe dell’associazione pubblica nel contesto features. |
component_uses_block
Le connessioni che un componente traccia verso i componenti da cui dipende, indicizzate per socket. Ogni socket elenca le proprie destinazioni, oppure nomina ciascuna connessione con un alias. Una connessione nominata con un alias può portare i valori per connessione dello sviluppatore e le associazioni che riempiono gli slot dichiarati dal socket.
Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$.
I valori sono string[] or map of object.
Nessun’altra chiave è consentita.
feature_uses_block
Le connessioni che traccia una Feature associata, indicizzate per un socket che la Feature dichiara nel proprio usesSchema. Ogni socket elenca le proprie destinazioni, oppure nomina ciascuna connessione con un alias. Una connessione tracciata da una Feature non porta associazioni proprie: una credenziale di cui ha bisogno riempie uno slot che la Feature dichiara nel proprio featuresSchema e viene associata accanto alla Feature.
Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$.
I valori sono string[] or map of object.
Nessun’altra chiave è consentita.
connection_attachment
Un’associazione portata da una connessione: la Feature che riempie uno slot dichiarato dal socket della connessione, con la configurazione dello sviluppatore per essa.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
type | string | sì | L’URI dell’interfaccia della Feature richiesta da questa associazione (ad es. core/referenced-secret:1.0.0). |
description | string | no | Documentazione opzionale che spiega perché questa connessione porta l’associazione. |
values | object | no | Configurazione fornita dallo sviluppatore per la Feature, convalidata dalla dichiarazione del suo schema. |
Non sono consentite proprietà aggiuntive.
subsystem
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
description | string | no | Documentazione opzionale che descrive lo scopo di questo sottosistema e il raggruppamento logico che rappresenta. |
annotations | mappa di string o object o null | no | Annotazioni scritte dallo sviluppatore su questo sottosistema. I valori sono stringhe, oggetti strutturati (una mappa da sottochiave a valore, unita per sottochiave con un valore strutturato ereditato) oppure null; un null esplicito su una chiave ereditata da un sottosistema genitore rimuove il legame ereditato da questo sottosistema (rinuncia a una Feature guidata da annotazioni). Le annotazioni dichiarate qui vengono ereditate dai sottosistemi annidati e dai componenti contenuti; il livello più vicino prevale per chiave. Scendono in cascata fino al contenitore .context.annotations.aggregate su ogni nodo IR derivato. |
features | mappa di object | no | Funzionalità trasversali associate a tutti i componenti di questo sottosistema. Stesso schema delle funzionalità a livello di componente (type, values, uses, inject). Appiattite in ciascun componente alla finalizzazione del grafo, collocate dopo le funzionalità a livello di componente nell’ordine di esecuzione. Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$. |
subsystems | mappa di subsystem | no | Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$. |
components | mappa di component_instance | no | Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$. |
Non sono consentite proprietà aggiuntive.
component_instance
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
type | string | sì | Il Component astratto richiesto, come riferimento: il suo metadata.name più un :version opzionale (ad es. core/api-server:1.0.0), mai un percorso di file. Risolto tramite il modello di risoluzione delle entità a tre livelli (directory di catalogo del workspace → cache → registry): un Component scritto in locale si colloca sotto catalog/ nella radice del workspace o in una directory elencata sotto workspace.catalog_dirs, e un type scritto come percorso di file relativo arresta la build come entità che nessun catalogo contiene. |
active | boolean o string | no | Indica se questo componente è presente nella topologia compilata. Un boolean, oppure un template stringa su .parameters che deve risolversi in un boolean. Quando si risolve in false il componente viene eliminato dalla topologia, a cascata sui suoi archi uses e sulle sue associazioni. Ricavare il valore da un parametro consente a una Release di attivare o disattivare la presenza del componente adempiendo quel parametro. Vale true se omesso. Predefinito: true |
description | string | no | Documentazione opzionale che descrive il ruolo di questa istanza di componente nell’applicazione. Portata fino al grafo IR. |
annotations | mappa di string o object o null | no | Annotazioni scritte dallo sviluppatore su questo componente. I valori sono stringhe, oggetti strutturati (una mappa da sottochiave a valore, unita per sottochiave con un valore strutturato ereditato) oppure null; un null esplicito su una chiave ereditata da un sottosistema genitore rimuove il legame ereditato da questo componente (rinuncia a una Feature guidata da annotazioni). Le annotazioni a livello di Component sovrascrivono per chiave le annotazioni ereditate a livello di sottosistema; i componenti fratelli nello stesso sottosistema mantengono in modo indipendente le proprie mappe di annotazioni. |
values | object | no | Proprietà cognitive opache passate al Component, convalidate dal suo schema. |
uses | component_uses_block | no | Le connessioni che un componente traccia verso i componenti da cui dipende, indicizzate per socket. Ogni socket elenca le proprie destinazioni, oppure nomina ciascuna connessione con un alias. Una connessione nominata con un alias può portare i valori per connessione dello sviluppatore e le associazioni che riempiono gli slot dichiarati dal socket. |
inject | inject_block | no | Auto-iniezione a livello di Component. Inietta i valori propri del componente (tramite ‘value:’) o le sue chiavi provides (tramite ‘from:’) direttamente nel pipe di consegna (.context.inject). Consentito solo se l’entità di catalogo Component dichiara ‘spec.inject’ con i meccanismi corrispondenti. Una chiave inject che collide con una chiave dichiarata in uses[].inject arresta la build come chiave di consegna duplicata tra le sorgenti di inject. |
features | mappa di object | no | Le Features associate a questo componente, indicizzate per il nome di istanza che l’autore dà a ciascuna associazione. Questa è l’unica superficie di associazione: una Feature operativa, una Feature di credenziali (una con l’etichetta feature.aggrega.ai/kind: secret) e una Feature di identità vengono tutte associate qui, con la stessa parola chiave e la stessa forma. Ciò che le distingue è ciò che l’associazione produce, non il modo in cui viene dichiarata. Un’associazione il cui nome di istanza corrisponde a uno slot che il Component dichiara in featuresSchema riempie quello slot; qualsiasi altro nome di istanza è un’associazione libera. Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$. |
Non sono consentite proprietà aggiuntive.