JSON

JSON, abbreviazione di JavaScript Object Notation, è un formato leggero basato su testo per archiviare e scambiare dati strutturati. Douglas Crockford lo ha definito nei primi anni 2000, basandosi sulla sintassi dei letterali oggetto di JavaScript, e oggi è standardizzato come RFC 8259 dell'IETF e ECMA-404. JSON è indipendente dal linguaggio, leggibile dalle persone e analizzabile con la libreria standard di quasi tutti i linguaggi di programmazione, il che lo rende il formato predefinito per le API web. Nell'apprendimento automatico (ML), trasporta le predizioni fuori dai motori di inferenza, archivia le annotazioni dei dataset, registra i metadati degli esperimenti e definisce gli output strutturati dei modelli linguistici di grandi dimensioni (LLM).

Sintassi JSON#

Un documento JSON è composto da due contenitori e quattro tipi di valori:

• Oggetti: insiemi non ordinati di coppie chiave-valore racchiusi tra parentesi graffe, come {"name": "bus", "confidence": 0.94}. Le chiavi devono essere stringhe racchiuse tra virgolette doppie.
• Array: elenchi ordinati racchiusi tra parentesi quadre, come [48.5, 398.0, 245.3, 902.1].
• Valori: stringhe, numeri, i valori letterali true, false e null, oppure oggetti e array annidati.

Il formato è rigoroso. Commenti, virgole finali, stringhe tra apici singoli e i valori NaN e Infinity non sono consentiti, anche se il modulo json di Python scrive NaN per impostazione predefinita, a meno che non venga impostato allow_nan=False, producendo file che i parser rigorosi rifiutano. Anche RFC 8259 avverte che i numeri vengono scambiati in modo affidabile solo entro la precisione double di IEEE 754, quindi gli interi superiori a 2⁵³ − 1, come alcuni ID di database, vengono spesso inviati come stringhe.

JSON nei flussi di lavoro di apprendimento automatico#

Quando una telecamera di un sistema di sicurezza invia un frame a un servizio di rilevamento degli oggetti, il livello di distribuzione del modello risponde in genere con JSON: un record per ogni oggetto rilevato, con la relativa classe, il punteggio di confidenza e le coordinate del riquadro di delimitazione, pronto per dashboard, app mobili e database documentali come MongoDB.

Anche i formati di annotazione si basano su JSON. Il dataset COCO memorizza tutte le etichette di una partizione in un unico file JSON con tre elenchi principali: images con nomi e dimensioni dei file, categories con ID e nomi delle classi e annotations, in cui ogni voce rimanda a un'immagine e a una categoria tramite ID e memorizza un riquadro come [x, y, width, height] in pixel a partire dall'angolo superiore sinistro. Il formato YOLO usa invece un file di testo per immagine con coordinate normalizzate del centro, e la conversione tra i due formati è un passaggio standard nelle pipeline di annotazione dei dati, anche se una classe dataset personalizzata può anche addestrare YOLO direttamente su JSON COCO.

JSON Lines, chiamato anche NDJSON, inserisce un oggetto JSON completo su ogni riga. I file possono così essere ampliati, trasmessi in streaming e suddivisi senza analizzare l'intero documento, una caratteristica utile per i log di addestramento, i flussi di predizioni e i dataset di istruzioni usati per il fine-tuning degli LLM. Per gli LLM, JSON Schema descrive esattamente i campi attesi da un'applicazione, mentre gli output strutturati e la chiamata di funzioni vincolano un modello a produrre JSON conforme allo schema. GeoJSON, standardizzato come RFC 7946, applica il formato agli elementi geografici e consente così all'analisi di immagini satellitari di collocare i rilevamenti su una mappa.

Convertire le predizioni in JSON#

Gli oggetti Results di Ultralytics YOLO serializzano le loro predizioni con to_json(), scrivendo un record per ogni rilevamento con il nome della classe, l'ID della classe, la confidenza e gli angoli del riquadro x1, y1, x2, y2, oltre alle coordinate della maschera o dei keypoint per i modelli di segmentazione delle istanze e di stima della posa. L'esempio seguente esegue YOLO26 su un'immagine di esempio e rilegge il JSON con la libreria standard di Python:

import json

from ultralytics import YOLO

# Carica un modello di rilevamento YOLO26 preaddestrato ed esegui l'inferenza
model = YOLO("yolo26n.pt")
results = model("https://ultralytics.com/images/bus.jpg")
result = results[0]

# Serializza ogni rilevamento in una stringa JSON (normalize=True normalizzerebbe i riquadri nell'intervallo 0-1)
json_string = result.to_json()

# Qualsiasi parser JSON può rileggerlo, in questo caso in un elenco di dizionari Python
detections = json.loads(json_string)
print(json.dumps(detections[0], indent=2))

Il record stampato è un oggetto JSON con le chiavi name, class e confidence e un oggetto annidato box che contiene le coordinate degli angoli in pixel.

JSON e formati correlati a confronto#

• YAML: un formato più leggibile che consente commenti e annidamento tramite indentazione, comune nelle configurazioni di addestramento e nelle definizioni dei dataset. YAML 1.2 è progettato come sovrainsieme di JSON, quindi la maggior parte dei documenti JSON è valida anche come YAML.
• XML: un formato basato su tag, usato per le annotazioni Pascal VOC, più verboso di JSON e in grado di supportare attributi, namespace e schemi.
• CSV: un formato tabellare semplice, compatto per i dati in tabella, ma incapace di annidare oggetti o elenchi.
• Formati binari: Protocol Buffers e MessagePack sono più compatti e veloci da analizzare rispetto a JSON, ma non sono leggibili dalle persone. I file di modello ONNX sono archiviati come messaggi Protocol Buffers.