SchemaLibrary
Una SchemaLibrary è un’entità di catalogo che contiene definizioni JSON Schema 2020-12 riutilizzabili più helper parametrizzati facoltativi. I Components e le Features che condividono forme di schema — URL, durate, strutture di probe comuni, limiti di risorse ricorrenti — dichiarano tali forme una sola volta in una libreria e vi fanno riferimento tramite URI $ref canonici. L’entità libreria è di Livello 3: facoltativa, per i cataloghi che necessitano del riutilizzo di schemi tra un Component e l’altro. I cataloghi senza contenuti di schema ripetuti vengono pubblicati senza alcuna SchemaLibrary.
Il ruolo della SchemaLibrary
Gli architetti di piattaforma scrivono SchemaLibraries per centralizzare le forme di schema che ricorrono nel catalogo. Una libreria non è un blocco costitutivo distribuibile; è uno spazio dei nomi di definizioni. Gli autori di Component / Feature fanno riferimento alle voci della libreria tramite il loro URI $ref canonico, tipizzato una volta e validato ovunque il riferimento si risolva.
La separazione tra «libreria» e «consumatore» è intenzionale. I Components dichiarano il contratto che un’istanza riempie (i suoi values, infra e provides, i suoi socket, i suoi slot di credenziali). Le Features codificano associazioni comportamentali. Le SchemaLibraries codificano solo contenuto di schema — le regole strutturali che un valore deve soddisfare. Mantenere distinti i tre ruoli consente a ciascun tipo di entità di evolvere con il proprio ritmo; gli autori che non hanno bisogno di definizioni di schema condivise non incontrano mai l’entità libreria.
Envelope dell’entità
Un’entità SchemaLibrary porta l’involucro standard del catalogo. apiVersion: aggrega.ai/v1beta1 e kind: SchemaLibrary contrassegnano il tipo di entità; metadata.name è un identificatore PascalCase; metadata.version segue rigorosamente il versionamento semantico. Il contenuto della libreria si trova sotto spec: spec.schemas è obbligatorio (la libreria deve dichiarare almeno una voce), e spec.templates è facoltativo (presente solo quando la libreria usa helper parametrizzati).
apiVersion: aggrega.ai/v1beta1kind: SchemaLibrarymetadata: name: WebPrimitives version: 1.0.0spec: schemas: URL: type: string pattern: "^https?://" HTTPMethod: type: string enum: [GET, POST, PUT, PATCH, DELETE]Scrivere le voci di schema
Le voci di schema si scrivono in una di tre forme. La forma compatta è la superficie predefinita per forme brevi e comuni — type, pattern, enum, min, max e vincoli simili su una riga. Lo YAML JSON Schema 2020-12 è l’opzione di authoring di pari rango per le voci che richiedono l’intera superficie di JSON Schema (parole chiave di composizione, forma condizionale, $defs complessi). Mescolare le due all’interno di una singola voce è supportato tramite il dispatch per nodo in base alla forma del contenuto del compilatore della forma compatta; la via d’uscita $jsonschema: incorpora contenuto JSON Schema completo in qualsiasi nodo quando la forma compatta non può esprimere l’intento.
Un format in una voce verifica ciò che verifica in qualsiasi schema: nomina uno tra email, uri, hostname, ipv4, ipv6, uuid, date-time e date, e un valore che un consumatore fornisce per il campo viene rifiutato a meno che non abbia quel formato — vedi vocabulary/compact-form-authoring.md. Una voce che nomina qualsiasi altro formato — password compreso — viene rifiutata al caricamento della libreria, quindi un aggrega validate dell’intero catalogo la rifiuta indipendentemente dal fatto che qualcosa vi faccia già riferimento, nominando la libreria, la voce e il nome ed elencando quelli supportati, e una build o un pull la cui Release raggiunge la libreria si interrompe su di essa. Una voce che fa riferimento a un’altra libreria viene valutata dove la consuma un pilastro di un Component o di una Feature. Un campo che contiene materiale segreto dichiara sensitive: true anziché un formato.
Template e $instantiate:
Le librerie con una struttura ripetuta consistente dichiarano helper parametrizzati sotto spec.templates. Un template porta una mappa $params: (dichiarazioni di parametri tipizzati con nome) più un corpo (forma compatta o contenuto JSON Schema che fa riferimento ai parametri come token scalari $<paramName>). Le voci di schema istanziano i template tramite i binding $instantiate: + $args:; il motore di sostituzione rimpiazza i segnaposto dei parametri con valori scalari letterali e produce il corpo della voce risolta.
spec: schemas: LivenessProbe: $instantiate: ProbeTemplate $args: port: 8080 path: /healthz ReadinessProbe: $instantiate: ProbeTemplate $args: port: 8081 path: /ready templates: ProbeTemplate: $params: port: type: integer path: type: string type: object properties: port: type: integer const: $port path: type: string const: $pathLa sostituzione riguarda solo scalari letterali. Il motore di sostituzione non interpreta la sintassi dei template Go, non valuta condizionali né esegue cicli. Gli autori che necessitano di helper più espressivi compongono Components o Features che consumano le voci della libreria con le proprie variazioni.
Convenzioni di denominazione
I nomi delle librerie, le chiavi delle voci di schema e i nomi dei template seguono il PascalCase. Il JSON Schema dell’involucro dell’entità applica la convenzione in tre posizioni tramite vincoli di pattern:
metadata.namecorrisponde a^[A-Z][A-Za-z0-9]*$.- Le chiavi della mappa
spec.schemascorrispondono allo stesso pattern tramitepropertyNames. - Le chiavi della mappa
spec.templatescorrispondono allo stesso pattern tramitepropertyNames.
Una SchemaLibrary con una chiave non PascalCase in spec.schemas o spec.templates non supera la validazione dell’involucro al caricamento del workspace. L’applicazione a livello di involucro è essenziale: le chiavi delle voci di schema compaiono negli URI $id canonici (#/schemas/<name>); i nomi dei template fanno riferimento a URI canonici al momento dell’istanziazione. Intercettare le chiavi non PascalCase al caricamento impedisce che si propaghino nell’ecosistema del catalogo.
I nomi dei parametri all’interno della mappa $params: di un template sono locali al template — non compaiono negli URI $id canonici e non sono vincolati da pattern a livello di involucro. Gli autori seguono qualunque convenzione di denominazione si adatti ai parametri del template; port, path, intervalSec e nomi di parametri minuscoli simili sono tipici.
L’uniformità dei nomi a livello di libreria, schema e template rende gli identificatori di riferimento facili da leggere: WebPrimitives#/schemas/URL si legge a colpo d’occhio.
Per la semantica di risoluzione di $ref: tra documenti — come $ref: si risolve oltre i confini delle SchemaLibrary, la distinzione sintattica di required: per i consumatori che portano $ref:, l’espansione delle catene da libreria a libreria e il comportamento in cui il consumatore restringe la libreria — vedi vocabulary/cross-document-ref.md.
Riferirsi alle voci della libreria
Gli autori di Component / Feature fanno riferimento a una voce di libreria tramite la sua identità — la forma a nome semplice <Library>#/schemas/<name>:
# Inside a Component schema:spec: schema: values: healthCheck: $ref: "WebPrimitives#/schemas/URL"Il nome della libreria si risolve rispetto al catalogo risolto; il frammento #/schemas/<name> seleziona la voce. Un riferimento non porta alcun host di registry; un autore può dichiarare un limite minimo di versione facoltativo come <Library>:<version>#/schemas/<name> (il separatore di versione è :, in linea con le mappature recipe/feature e il pin del lockfile), ma la versione risolta è fornita dal lockfile di ciascuna Release, che fissa ogni libreria consumata per nome + versione + digest del contenuto. Un riferimento che porta un host di registry — una forma oci://<host>/… — viene rifiutato in compilazione con una diagnostica che indirizza l’autore verso la forma a identità, così che una posizione fisica di registry non entri mai nel sorgente scritto. Da dove vengono serviti i byte della libreria (una directory di catalogo locale, la cache dei contenuti o un registry remoto) è compito del resolver, vincolato al momento della risoluzione; spostare un registry è una modifica della configurazione del resolver, non del sorgente.
Parole chiave JSON Schema vietate
Le parole chiave $dynamicAnchor e $dynamicRef di JSON Schema 2020-12 sono vietate nelle voci di SchemaLibrary. Il parser di SchemaLibrary analizza sia le voci di schema sia i corpi dei template al caricamento del workspace; il linter di pubblicazione applica una protezione ridondante al momento della pubblicazione; il motore di istanziazione rianalizza il corpo risolto dopo la sostituzione dei parametri, così un template che introduce di nascosto parole chiave vietate tramite valori di parametri fallisce comunque. Le tre analisi insieme chiudono la via di introduzione statica ($dynamicAnchor letterale in una voce di schema o nel corpo di un template), la via di introduzione parametrica (un valore $args: contenente $dynamicRef) e la via di aggiramento tramite strumenti esterni (la protezione al momento della pubblicazione intercetta tutto ciò che ha saltato il parser).
Quando il rifiuto scatta, l’errore cita la parola chiave incriminata e il percorso del file. Gli autori vedono l’errore al momento della scrittura anziché alla prima istanziazione; i corpi dei template non sono esentati dall’analisi al caricamento.
La semantica dei riferimenti dinamici si lega alla valutazione a runtime in modi che violano il contratto di determinismo in fase di compilazione del compilatore. Gli autori che necessitano di un comportamento a riferimenti dinamici ristrutturano lo schema per usare la risoluzione statica di $ref; il controllo non prevede eccezioni.
Collocazione nei tier
SchemaLibrary è di Livello 3 nel modello di documentazione a livelli delle entità — facoltativa per i cataloghi che necessitano del riutilizzo di schemi tra un Component e l’altro. I cataloghi senza contenuti di schema ripetuti vengono pubblicati senza alcuna entità SchemaLibrary; la marcatura di livello segnala «avanzato; salta se non serve» per la navigazione della documentazione, non una capacità. Il compilatore tratta SchemaLibrary in modo uniforme rispetto agli altri tipi di entità di catalogo: stessa validazione dell’involucro al caricamento del workspace, stessa pipeline JSON Schema 2020-12 per il contenuto di ciascuna voce, stessa pipeline di pubblicazione OCI al momento del rilascio.
All’interno del Livello 3, il meccanismo degli helper parametrici spec.templates è a sua volta facoltativo. Le librerie con una struttura ripetuta consistente (un template Probe parametrizzato su porta + percorso; un template CORS parametrizzato sulle origini consentite; un template TLS parametrizzato sui percorsi di certificato + chiave) traggono vantaggio dal riutilizzo di templates; le librerie con voci eterogenee e isolate saltano del tutto il blocco dei template e scrivono ogni voce inline sotto spec.schemas.