Cosa ci si aspetta da un producer OSIRIS JSON
I producer OSIRIS JSON sono il punto in cui lo standard diventa reale.
Le linee guida per i producer e la documentazione dell’SDK per i producer lo rendono esplicito. Un producer non è soltanto un parser che capita di emettere JSON. È il confine in cui inventari proprietari vengono tradotti in uno snapshot OSIRIS deterministico, portabile e sicuro, di cui altri strumenti possano fidarsi.
Un producer è un traduttore in sola lettura
Il primo punto importante nelle linee guida sui producer è ciò che un producer non è.
Non effettua provisioning dell’infrastruttura. Non modifica i dispositivi. Non inventa dati mancanti. Non reinterpreta la specifica. Il compito di un producer è più ristretto e più rigoroso: scoprire ciò che esiste, normalizzarlo in OSIRIS, rimuovere dati non sicuri o irrilevanti ed emettere uno snapshot che possa essere convalidato dalla toolchain canonica di OSIRIS.
Può sembrare ovvio, ma è il confine giusto da tracciare. Nel momento in cui i producer iniziano a comportarsi come control plane, o iniziano a incorporare idee personalizzate di ciò che significhi OSIRIS, l’interoperabilità si spezza.
Il flusso di lavoro del producer è deliberato
La documentazione descrive il ciclo di vita del producer in quattro passaggi: discovery, normalization, redaction ed emission.
Questa sequenza è importante perché ogni fase ha una responsabilità diversa:
- discovery raccoglie dati dal vendor o dalla piattaforma
- normalization li mappa nelle strutture standard di OSIRIS
- redaction rimuove segreti, PII e rumore inutile
- emission serializza il documento e lo convalida prima della pubblicazione
Le linee guida lasciano spazio anche alla realtà. Inventari parziali sono accettabili. I singoli errori di discovery dovrebbero di norma essere registrati e saltati invece di mandare in crash l’intero export. Ma questa flessibilità si ferma al confine della sicurezza: se vengono rilevati segreti, ci si aspetta che il producer fallisca in modo sicuro.
Il determinismo è una funzionalità, non rifinitura
Uno dei temi più forti in entrambi i documenti è il determinismo.
Ci si aspetta che gli ID delle risorse, delle connessioni e dei gruppi siano stabili tra un’esecuzione e l’altra. La documentazione sui producer insiste molto contro casualità, ordinamenti instabili e naming ad hoc. La ragione è semplice: se lo stesso ambiente produce output diversi ogni volta, diff, correlazione e automazione a valle diventano tutti inaffidabili.
L’SDK rafforza questo punto con helper concreti:
- generazione deterministica degli ID a partire da chiavi canoniche
- gestione delle collisioni in due fasi tramite un
IDRegistry - un
DocumentBuilderche gestisce$schema,version, i metadati del generator e un output topologico ordinato - helper di test che verificano il determinismo byte per byte e la coerenza dei golden file
Questo è uno dei segnali più chiari che OSIRIS è in fase di progettazione per tooling di lunga durata, non per export una tantum.
La sicurezza è una responsabilità del producer
Le linee guida per i producer sono altrettanto nette sulla redazione.
I documenti OSIRIS non devono contenere credenziali, token, chiavi private o stringhe di connessione con segreti incorporati. Ci si aspetta che i producer analizzino pattern comuni prima dell’emissione, scompongano i valori non sicuri invece di copiarli integralmente e scelgano una modalità di errore esplicita.
L’impostazione predefinita raccomandata è fail-closed. Esiste una modalità log-and-redact attivabile esplicitamente, ma anche in quel caso le regole restano severe: non registrare mai il valore segreto stesso, contrassegnare sempre il documento come redatto e non lasciare mai che la redazione avvenga in silenzio.
È l’impostazione corretta. I producer sono il punto più vicino ai sistemi sorgente grezzi, e questo li rende anche il luogo più pericoloso in cui essere superficiali.
L’SDK serve a rimuovere la deriva
L’SDK Go per i producer non viene presentato come infrastruttura magica. Viene presentato come un modo per fermare la deriva dei producer.
Standardizza il contratto Collect(ctx), fornisce contesto runtime condiviso, factory per risorse e relazioni, helper di normalizzazione, builder deterministici e un harness di test. Altrettanto importante, rifiuta di diventare un secondo validatore. L’SDK non possiede le diagnostiche V-* e non importa @osirisjson/core come libreria. I producer convalidano l’output chiamando la CLI canonica come passaggio esterno.
Questa separazione è architettonicamente solida. Mantiene la logica di mapping nei producer e la logica di convalida nel motore condiviso di OSIRIS.
La fiducia nasce dai test
Il messaggio finale nella documentazione sui producer è che l’output di un producer deve essere riproducibile e verificabile.
I golden file sono trattati come la difesa principale contro le regressioni. Il flusso di lavoro atteso è semplice: simulare l’input del vendor, generare il documento OSIRIS, confrontarlo con il golden file, quindi convalidare quell’artefatto con la CLI canonica sotto il profilo strict. L’harness di test dell’SDK aggiunge helper per quel flusso e per riesecuzioni deterministiche con clock e fixture fissi.
Questo conta perché la qualità di un producer non riguarda soltanto il fatto che l’export “funzioni una volta”. Riguarda il fatto che lo stesso input continui a produrre output affidabile mentre l’ecosistema evolve.
Leggi la documentazione sui producer
Le linee guida sui producer sono disponibili nella sezione architettura della documentazione: