Schema del catalogo di Aggrega (Component)
Riferimento generato. Non modificarlo a mano — rigeneralo a partire dal JSON Schema pubblicato.
Id dello schema: https://aggrega.ai/schemas/component-v1beta1.schema.json
La definizione astratta di un elemento costitutivo atomico.
Consulta il riferimento per l’authoring del Component per una guida in prosa sulla scrittura delle entità Component; 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 “Component” | sì | Costante: "Component" |
metadata | object | sì | |
spec | object | sì | Definizioni di validazione e di schema che regolano il payload opaco dei valori dello sviluppatore. |
Non sono consentite proprietà aggiuntive.
component.metadata
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
name | string | sì | Lungo almeno 1 carattere. |
version | string | sì | Versionamento semantico rigoroso dell’interfaccia (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-]+)*))?$. |
description | string | no | Che 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. |
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 | object | sì | Etichette di duck typing per dichiarare caratteristiche. Devono includere la chiave riservata ‘component.aggrega.ai/type’. |
annotations | mappa di string | no | Caratteristiche intrinseche e immutabili del componente, scritte dall’architetto di piattaforma nel Dominio 2. Scendono in cascata fino al contenitore .context.annotations.catalog. |
Non sono consentite proprietà aggiuntive.
component.metadata.maintainers[]
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
name | string | sì | |
email | string | no | |
url | string | no |
Non sono consentite proprietà aggiuntive.
component.metadata.labels
Etichette di duck typing per dichiarare caratteristiche. Devono includere la chiave riservata ‘component.aggrega.ai/type’.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
component.aggrega.ai/type | string (enum) | sì | L’asse riservato che indica che tipo di cosa è questo componente. Aggrega definisce questa chiave e i valori che accetta, quindi l’insieme è chiuso; per classificare i componenti su un asse tuo, aggiungi una tua chiave di etichetta accanto a questa. Valori consentiti: "server", "worker", "task", "function", "stateful-server", "resource" |
component.spec
Definizioni di validazione e di schema che regolano il payload opaco dei valori dello sviluppatore.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
extends | string | no | URI di un Component di base che questo Component estende. L’estensione compone la struttura: le etichette e le annotazioni dei metadati della base, i suoi slot di associazione (featuresSchema), la sua allowlist di auto-iniezione (inject) e i suoi socket di topologia (usesSchema) vengono ereditati, e questo Component può aggiungervi voci o sostituire una voce ereditata chiave per chiave. I pilastri di dati della base NON vengono composti — il blocco schema della base viene ereditato esattamente come la base lo ha scritto, quindi un Component che estende scrive schema: inherited e non scrive alcun contenuto di pilastro proprio. |
featuresSchema | mappa di object | no | Definizioni dichiarative degli slot di associazione: i punti di legame con nome in cui questa entità si aspetta che venga associata una 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, così una stessa entità serve sia un’associazione che riempie uno slot sia una credenziale condivisa in un ambito più ampio. Uno slot è un punto di legame, non un socket di dipendenza: usesSchema dichiara la superficie di topologia separata. |
inject | string[] | no | Meccanismi di consegna dell’auto-iniezione ammessi dall’allowlist (ad es. [‘env’, ‘file’, ‘arg’]). Quando è presente, gli sviluppatori possono usare il blocco inject: a livello di componente nell’Aggregate per iniettare i propri values o le proprie chiavi provides direttamente nel pipe di consegna. Se omesso, l’auto-iniezione a livello di componente è vietata (pattern Black-Box — la Recipe gestisce tutto il cablaggio interno). Stessa semantica di usesSchema[].inject, ma governa i values propri del componente anziché la topologia tra componenti. Si può elencare qualsiasi nome di meccanismo tranne all, che nessun blocco inject può nominare. |
usesSchema | mappa di object | no | I 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, i meccanismi di iniezione che consente e i suoi contratti per connessione. Chiavi: una o più lettere, cifre, trattini bassi o trattini. Il punto non è consentito. Pattern: ^[a-zA-Z0-9_-]+$. |
schema | any | no | Contenuto 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 istanza di Component nell’Aggregate); infra (il dominio dell’Operatore — manopole di dimensionamento fisico fornite dalla Release); e provides (chiavi di contesto a valle che questo Component espone ai consumatori tramite il pipe della topologia). Accetta quattro 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: |
assertions | mappa di string | no | Validazione 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 del Component vengono valutate dopo la risoluzione e l’analisi statica, prima del rendering, ed esprimono invarianti architetturali del contratto che valgono qualunque Recipe si leghi. 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. L’ereditarietà è additiva: un Component che dichiara extends viene valutato rispetto alle asserzioni che eredita oltre che alle proprie, prima le regole ereditate, e una catena di qualsiasi profondità si accumula dalla radice della catena verso il basso — quindi, quando più di una regola fallirebbe, quella riportata è quella dichiarata più in alto nella catena. Riutilizzare un nome ereditato per dichiarare una regola diversa viene rifiutato quando la catena di extends viene risolta rispetto al catalogo, nominando entrambi i Components e il nome condiviso — quindi emerge una volta che il Component di base è presente, non dal solo documento che estende; un Component che estende aggiunge regole e non ne sostituisce mai una. Ridichiarare una regola ereditata byte per byte con il suo stesso nome è accettato come l’operazione nulla che è. Nulla verifica se due regole possono valere entrambe: una coppia reciprocamente insoddisfacibile è un errore di authoring che emerge come un normale fallimento di asserzione quando un’istanza fa scattare quella che scatta per prima, mai come avviso anticipato. |
Non sono consentite proprietà aggiuntive.
Definizioni
extending-component-must-declare-schema-inherited
Si applica quando spec.extends è presente. Un Component che estende riceve i values / infra / provides della sua base esattamente come la base li ha scritti, quindi dichiara spec.schema: inherited e non scrive alcun contenuto di pilastro. Entrambi gli altri esiti sono errori, e sono sbagli diversi: omettere del tutto spec.schema, il che lascerebbe un lettore incapace di distinguere un blocco di pilastri ereditato da uno dimenticato; e scrivere contenuto di pilastro sotto spec.schema, il che chiederebbe un secondo contratto, divergente, su un Component il cui contratto è quello della sua base.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
schema | const “inherited” | sì | Il marcatore di ereditarietà, e l’unico valore che spec.schema assume su un Component che dichiara extends. Indica da dove provengono i pilastri; il contenuto dei pilastri è quello del Component di base. Costante: "inherited" |
non-extending-component-authors-its-own-schema
Si applica quando spec.extends è assente. Un Component che non estende alcuna base scrive il proprio contenuto values / infra / provides sotto spec.schema, quindi il campo porta contenuto scritto dall’autore anziché il marcatore inherited: il marcatore afferma che i pilastri provengono da una base, e questo Component non ne ha.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
schema | object | no | Contenuto di pilastro scritto dall’autore — una mappa, in una qualsiasi delle tre modalità di authoring del contenuto che spec.schema documenta. |