Specifiche
I contratti sono JSON Schema (draft 2020-12) e documenti normativi. Sono la fonte di verità: il codice di Yggdrasil stesso è generato a partire da essi e testato su fixture condivise in TypeScript e Python. La versione 1 è stata congelata il 4 ottobre 2026 (tag specs-v1.0.0); il rilascio 1.1.0 (tag specs-v1.1.0, 7 ottobre 2026) aggiunge YGG1 1.1, che lega i dati cifrati al loro contesto e le chiavi e gli output dei processori al progetto reale. Le modifiche incompatibili richiedono una nuova versione major; le aggiunte sono rilasci minor.
Inizia dalla panoramica dei contratti: identificatori, versionamento, convenzioni, condizioni show-if, testo cifrato del manifest e le regole che ogni validatore deve verificare oltre a JSON Schema.
Documenti
Sezione intitolata “Documenti”| Documento | Che cosa definisce |
|---|---|
| Formato di cifratura YGG1 | Chiavi degli oggetti, il contenitore a blocchi per gli asset, gli oggetti piccoli, la sigillatura delle chiavi con HPKE, le chiavi di identità, i pacchetti di chiavi, le epoche del progetto, il registro firmato del progetto e i codici di sicurezza. Con vettori di test. |
| API HTTP dei processori v1 | Come un processore si registra, prende in carico i job, mantiene i lease, legge i suoi input, carica gli output e pubblica i risultati. |
| Geometria dei volumi v1 | Un’unica geometria canonica per ogni serie volumetrica da DICOM, NIfTI e NRRD, gli spazi di coordinate dei selettori e la struttura delle mappe di etichette. |
| Contratto | Schema |
|---|---|
| Manifest del progetto | manifest/v1 |
| Envelope dell’annotazione (visibile al server) | annotation/envelope-v1 |
| Payload dell’annotazione (corpo cifrato e selettore) | annotation/payload-v1 |
| Selettori | annotation/selectors-v1 |
| Tipi di annotazione: corpo e configurazione dell’attività | types/ |
| Descrittore di modalità | modality/descriptor-v1 |
| Descrittore del processore | processor/descriptor-v1 |
| Pacchetto di plugin (il catalogo dei plugin) | plugin/package-v1 |
| Payload dell’API dei processori | processor/api/ |
| Geometria dei volumi e mappe di etichette | geometry/volume-v1 |
| Ricevuta di de-identificazione | deid/receipt-v1 |
| Metadati delle entità (i metadati cifrati di pazienti, studi, serie e asset) | data/entity-meta-v1 |
| Tour delle guide nella pagina | guides/tour-v1 |
| Definizioni condivise | common/v1 |
I metadati di una serie contengono anche le calibrazioni e le trasformazioni di visualizzazione delle sue immagini (ritaglio, specchiatura e rotazione): i visualizzatori applicano una trasformazione alla camera, mentre l’immagine conservata e ogni forma restano nei pixel originali.
I manifest di progetto iniziali si trovano in templates/.
Le modalità e i tipi di annotazione sono plugin; un’installazione ne aggiunge altri dal suo catalogo dei plugin. Un plugin di modalità acquisisce, de-identifica, normalizza e visualizza un tipo di dati, e si dichiara con un descrittore di modalità. Un tipo di annotazione definisce uno schema del corpo e uno schema di configurazione dell’attività. I tipi di annotazione integrati della versione 1:
| Tipo | Corpo |
|---|---|
ygg.classification.single@1, ygg.classification.multi@1 |
Una o più opzioni |
ygg.classification.boolean@1 |
Sì o no |
ygg.classification.ordinal@1 |
Un livello di una scala ordinata |
ygg.value.text@1, ygg.value.number@1 |
Testo libero, o un numero con un’unità facoltativa |
ygg.geometry.point@1, ygg.geometry.box@1, ygg.geometry.polygon@1 |
Una forma con etichetta, con la sua geometria nel selettore |
ygg.segmentation.labelmap@1 |
Un asset mappa di etichette e i suoi segmenti |
I tipi di misura contengono una forma con etichetta e i valori misurati su di essa dal client del lettore, con le loro unità: ygg.geometry.line@1, ygg.geometry.polyline@1, ygg.geometry.angle@1, ygg.geometry.cobb@1, ygg.geometry.bidirectional@1, ygg.geometry.ellipse@1, ygg.geometry.freehand@1, ygg.geometry.probe@1 e ygg.geometry.oriented-box@1.
I tipi temporali marcano i frame di un video (frame contati da 0 nell’ordine di presentazione, con i loro tempi): ygg.temporal.interval@1 contiene le sequenze di frame con etichetta di un lettore (fasi, eventi) e ygg.temporal.frame-tag@1 i suoi singoli frame contrassegnati. ygg.temporal.phases@1 (dalla 1.40.0) divide un video o una registrazione di segnali in fasi consecutive: ogni marcatore (un’etichetta, un tempo in secondi e, su un video, un frame) inizia una fase che dura fino al successivo. Le forme su un video indicano il loro frame nel selettore pixel, e dalla 1.41.0 possono indicare una track, l’oggetto che seguono (i fotogrammi chiave di una traccia sono interpolati tra loro, e mantenuti dopo l’ultimo fino a uno marcato outside), e il frameRate di un’attività stabilisce quali frame annotano i lettori, per esempio uno al secondo.
I tipi di segnale marcano una registrazione (ECG, EEG) in secondi dal primo campione: ygg.signal.interval@1 contiene gli intervalli di tempo con etichetta di un lettore (onde, battiti, crisi) e ygg.signal.event@1 i suoi istanti con etichetta (picchi R, spike), ciascuno eventualmente solo su alcuni canali.
I tipi di riferimento puntano fuori dalla risposta: ygg.ontology.term@1 sceglie termini dall’elenco di codici del progetto (SNOMED CT, RadLex o codici propri) e ygg.attachment.file@1 allega file come i referti PDF, ciascuno conservato come asset cifrato che non viene mai analizzato.
Validare i documenti
Sezione intitolata “Validare i documenti”- TypeScript: il pacchetto
@yggdrasil/specsesportavalidate(id, data)e i tipi generati. - Python: carica ogni schema in un
referencing.Registryindicizzato per$ide valida conjsonschema.Draft202012Validator. - Qualsiasi altro linguaggio: qualsiasi validatore draft 2020-12 con espressioni regolari ECMA-262.