Passa al contenuto principale

RFC 7159 - The JavaScript Object Notation (JSON) Data Interchange Format

  • Stato: Proposed Standard
  • Pubblicato: March 2014
  • Stream: IETF
  • Sostituisce: RFC4627, RFC7158
  • Sostituito da: RFC8259
  • Errata: Nessun errata

Sommario (Abstract)​

JavaScript Object Notation (JSON) è un formato di scambio dati leggero, basato su testo e indipendente dal linguaggio. Deriva dallo standard del linguaggio di programmazione ECMAScript. JSON definisce un piccolo insieme di regole di formattazione per la rappresentazione portabile di dati strutturati.

Questo documento elimina le incoerenze con altre specifiche JSON, corregge gli errori di specifica e fornisce linee guida di interoperabilità basate sull'esperienza.

Concetti fondamentali di JSON​

Tipi di dati​

JSON supporta i seguenti tipi di dati:

Tipi primitivi (Primitive Types):

  • string - Stringa
  • number - Numero
  • boolean - Booleano (true/false)
  • null - Valore nullo

Tipi strutturati (Structured Types):

  • object - Oggetto (collezione non ordinata di coppie chiave-valore)
  • array - Array (sequenza ordinata di valori)

Esempi di sintassi​

Oggetto (Object):

{
  "name": "张三",
  "age": 30,
  "city": "北京"
}

Array:

[1, 2, 3, 4, 5]

Struttura nidificata:

{
  "users": [
    {"name": "Alice", "age": 25},
    {"name": "Bob", "age": 30}
  ],
  "total": 2
}

Cambiamenti principali rispetto a RFC 4627​

  1. Definizione di testo JSON più flessibile: Consente al testo JSON di essere qualsiasi valore JSON, non solo oggetti o array
  2. Correzioni di errori: Corregge gli errori segnalati in RFC 4627
  3. Linee guida di interoperabilità: Fornisce più consigli sull'interoperabilità dell'implementazione
  4. Chiarezza della codifica: Enfatizza l'uso della codifica UTF-8
  • Testo originale ufficiale: RFC 7159 (TXT)
  • Pagina ufficiale: RFC 7159 DataTracker
  • Rende obsoleti: RFC 4627 (vecchia specifica JSON)
  • Reso obsoleto da: È stato sostituito da RFC 8259
  • Tipo di media: application/json
  • Estensione file: .json

Riferimento rapido​

Tipo MIME​

Content-Type: application/json; charset=UTF-8

Strumenti comunemente usati​

Validazione online:

Supporto dei linguaggi di programmazione:

JavaScript:

const obj = JSON.parse('{"name":"Alice"}');
const str = JSON.stringify({name: "Bob"});

Python:

import json
obj = json.loads('{"name":"Alice"}')
str = json.dumps({"name": "Bob"})

Java:

// Con la libreria Jackson o Gson
ObjectMapper mapper = new ObjectMapper();
MyObject obj = mapper.readValue(jsonString, MyObject.class);

Nota importante: RFC 7159 è stato sostituito da RFC 8259, ma rimane un documento importante per comprendere la storia dell'evoluzione di JSON. Le applicazioni moderne dovrebbero fare riferimento a RFC 8259 come standard attuale.

1. Introduction (Introduzione)​

JavaScript Object Notation (JSON) è un formato testuale per la serializzazione di dati strutturati. Deriva dai letterali di oggetti JavaScript, come definiti nello standard del linguaggio di programmazione ECMAScript, terza edizione [ECMA-262].

JSON può rappresentare quattro tipi primitivi (stringhe, numeri, booleani e null) e due tipi strutturati (oggetti e array).

Una stringa è una sequenza di zero o più caratteri Unicode [UNICODE]. Si noti che questo riferimento punta all'ultima versione di Unicode, non a una versione specifica. Si prevede che i futuri cambiamenti alla specifica Unicode non influenzeranno la sintassi di JSON.

Un oggetto è una collezione non ordinata di zero o più coppie nome/valore, dove un nome è una stringa e un valore può essere una stringa, un numero, un booleano, null, un oggetto o un array.

Un array è una sequenza ordinata di zero o più valori.

I termini "oggetto" e "array" derivano dalle convenzioni di JavaScript.

Gli obiettivi di progettazione di JSON erano di essere minimale, portabile, testuale e un sottoinsieme di JavaScript.

1.1. Conventions Used in This Document (Convenzioni utilizzate in questo documento)​

Le parole chiave "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" e "OPTIONAL" in questo documento devono essere interpretate come descritto in [RFC2119].

Le regole grammaticali in questo documento devono essere interpretate come descritto in [RFC5234].

1.2. Specifications of JSON (Specifiche di JSON)​

Questo documento aggiorna [RFC4627], che descriveva JSON e registrava il tipo di media "application/json".

Una descrizione di JSON in termini ECMAScript appare nella versione 5.1 della specifica ECMAScript [ECMA-262], sezione 15.12. JSON è anche descritto in [ECMA-404].

Tutte le specifiche grammaticali JSON concordano sugli elementi sintattici del linguaggio.

1.3. Introduction to This Revision (Introduzione a questa revisione)​

Negli anni trascorsi dalla pubblicazione di RFC 4627, JSON ha avuto un uso molto ampio. Questa esperienza ha rivelato certi modelli che, sebbene consentiti dalle specifiche, hanno portato a problemi di interoperabilità.

Inoltre, è stato segnalato un piccolo numero di errata (vedere gli ID erratum RFC 607 [Err607] e 3607 [Err3607]).

L'obiettivo di questo documento è applicare questi errata, eliminare le incoerenze con altre specifiche JSON e evidenziare le pratiche che possono portare a problemi di interoperabilità.

2. JSON Grammar (Grammatica JSON)​

Un testo JSON è una sequenza di token. L'insieme di token include sei caratteri strutturali, stringhe, numeri e tre nomi letterali.

Un testo JSON è un valore serializzato. Si noti che alcune specifiche JSON precedenti limitavano un testo JSON a un oggetto o un array. Le implementazioni che generano solo oggetti o array dove è richiesto un testo JSON saranno interoperabili, poiché tutte le implementazioni accetteranno questi come testi JSON conformi.

JSON-text = ws value ws

Questi sono i sei caratteri strutturali:

begin-array     = ws %x5B ws  ; [ parentesi quadra sinistra
begin-object    = ws %x7B ws  ; { parentesi graffa sinistra
end-array       = ws %x5D ws  ; ] parentesi quadra destra
end-object      = ws %x7D ws  ; } parentesi graffa destra
name-separator  = ws %x3A ws  ; : due punti
value-separator = ws %x2C ws  ; , virgola

Lo spazio bianco insignificante è consentito prima o dopo uno qualsiasi dei sei caratteri strutturali.

ws = *(
        %x20 /              ; Spazio (Space)
        %x09 /              ; Tabulazione orizzontale (Horizontal tab)
        %x0A /              ; Avanzamento riga (Line feed or New line)
        %x0D )              ; Ritorno carrello (Carriage return)

7. Strings (Stringhe)​

La rappresentazione delle stringhe è simile alle convenzioni utilizzate nella famiglia di linguaggi di programmazione C. Una stringa inizia e termina con virgolette. Tutti i caratteri Unicode possono essere inseriti tra virgolette, ad eccezione dei caratteri che devono essere escapati: virgolette, barra rovesciata e caratteri di controllo (U+0000 a U+001F).

Qualsiasi carattere può essere escapato. Se il carattere si trova nel piano multilingue di base (BMP) (U+0000 a U+FFFF), può essere rappresentato come una sequenza di sei caratteri: una barra rovesciata, seguita dalla lettera minuscola u, seguita da quattro cifre esadecimali che codificano il punto di codice del carattere. Le lettere esadecimali da A a F possono essere maiuscole o minuscole. Così, per esempio, una stringa contenente solo un singolo carattere barra rovesciata può essere rappresentata come "\u005C".

In alternativa, esistono rappresentazioni di escape a sequenza di due caratteri per alcuni caratteri comunemente usati. Così, per esempio, una stringa contenente solo un singolo carattere barra rovesciata può essere rappresentata in modo più compatto come "\\".

Per escapare un carattere esteso che non si trova nel piano multilingue di base, il carattere è rappresentato come una sequenza di 12 caratteri, che codifica una coppia surrogata UTF-16. Così, per esempio, una stringa contenente solo il carattere chiave di violino (U+1D11E) può essere rappresentata come "\uD834\uDD1E".

string = quotation-mark *char quotation-mark

char = unescaped /
    escape (
        %x22 /          ; "    Virgolette         U+0022
        %x5C /          ; \    Barra rovesciata   U+005C
        %x2F /          ; /    Barra              U+002F
        %x62 /          ; b    Backspace          U+0008
        %x66 /          ; f    Form Feed          U+000C
        %x6E /          ; n    Nuova riga         U+000A
        %x72 /          ; r    Ritorno carrello   U+000D
        %x74 /          ; t    Tabulazione        U+0009
        %x75 4HEXDIG )  ; uXXXX                   U+XXXX

escape = %x5C              ; \

quotation-mark = %x22      ; "

unescaped = %x20-21 / %x23-5B / %x5D-10FFFF

8. String and Character Issues (Problemi di stringhe e caratteri)​

8.1. Character Encoding (Codifica dei caratteri)​

Il testo JSON DEVE essere codificato in UTF-8, UTF-16 o UTF-32. La codifica predefinita è UTF-8, e il testo JSON codificato in UTF-8 è interoperabile poiché sarà letto con successo dal maggior numero di implementazioni; ci sono molte implementazioni che non possono leggere con successo testi in altre codifiche (come UTF-16 e UTF-32).

Le implementazioni NON DEVONO aggiungere un Byte Order Mark (BOM) all'inizio di un testo JSON. Per l'interoperabilità, le implementazioni che analizzano testo JSON POSSONO ignorare la presenza di un Byte Order Mark piuttosto che trattarlo come un errore.

8.2. Unicode Characters (Caratteri Unicode)​

Quando tutte le stringhe rappresentate nel testo JSON sono interamente composte da caratteri Unicode [UNICODE] (indipendentemente da come sono escapati), quel testo JSON è interoperabile poiché tutte le implementazioni software che lo analizzano concorderanno sul contenuto dei nomi e dei valori di stringa negli oggetti e negli array.

Tuttavia, l'ABNF in questa specifica consente ai nomi dei membri e ai valori di stringa di contenere sequenze di bit che non possono codificare caratteri Unicode; ad esempio, "\uDEAD" (un singolo surrogato UTF-16 non accoppiato). Sono state osservate istanze di questa situazione, ad esempio, quando le librerie troncano stringhe UTF-16 senza verificare se la troncatura divide una coppia surrogata. Il comportamento del software che riceve testo JSON contenente tali valori è imprevedibile; ad esempio, le implementazioni possono restituire valori diversi per la lunghezza dei valori di stringa, o addirittura subire eccezioni di runtime fatali.

8.3. String Comparison (Confronto di stringhe)​

Le implementazioni software spesso devono testare l'uguaglianza dei nomi dei membri degli oggetti. Le implementazioni che convertono la rappresentazione testuale in una sequenza di unità di codice Unicode, quindi eseguono un confronto numerico unità di codice per unità di codice, sono interoperabili poiché le implementazioni concorderanno in tutti i casi sull'uguaglianza o disuguaglianza di due stringhe. Ad esempio, le implementazioni che confrontano incondizionatamente stringhe escapate potrebbero scoprire erroneamente che "a\\b" e "a\u005Cb" non sono uguali.

9. Parsers (Parser)​

Un parser JSON converte il testo JSON in un'altra rappresentazione. Un parser JSON DEVE accettare tutti i testi conformi alla grammatica JSON. Un parser JSON PUÒ accettare forme non-JSON o estensioni.

Un'implementazione può impostare limiti sulla dimensione dei testi accettati. Un'implementazione può impostare limiti sulla profondità massima di annidamento. Un'implementazione può impostare limiti sull'intervallo e sulla precisione dei numeri. Un'implementazione può impostare limiti sulla lunghezza e sul contenuto dei caratteri delle stringhe.

10. Generators (Generatori)​

Un generatore JSON produce testo JSON. Il testo prodotto DEVE conformarsi rigorosamente alla grammatica JSON.

12. Security Considerations (Considerazioni sulla sicurezza)​

In generale, ci sono problemi di sicurezza con i linguaggi di scripting. JSON è un sottoinsieme di JavaScript, ma esclude assegnazioni e chiamate.

Poiché la sintassi di JSON è presa in prestito da JavaScript, è possibile utilizzare la funzione "eval()" di quel linguaggio per analizzare il testo JSON. Questo costituisce generalmente un rischio di sicurezza inaccettabile, poiché il testo può contenere codice eseguibile oltre alle dichiarazioni di dati. Le stesse considerazioni si applicano all'uso di funzioni simili a eval() in qualsiasi altro linguaggio di programmazione in cui il testo JSON è conforme alla sintassi di quel linguaggio.

14. Contributors (Contributori)​

RFC 4627 è stato scritto da Douglas Crockford. Questo documento è stato costruito apportando relativamente poche modifiche a quel documento; pertanto, la stragrande maggioranza del testo qui contenuto è suo.

Appendix A. Changes from RFC 4627 (Modifiche rispetto a RFC 4627)​

Questa sezione elenca le modifiche tra questo documento e il testo di RFC 4627.

  • Modificato il titolo e il sommario del documento

  • Cambiato il riferimento a [UNICODE] per renderlo non specifico della versione

  • Aggiunta la sezione "Specifiche JSON"

  • Aggiunta la sezione "Introduzione a questa revisione"

  • Cambiata la definizione di "testo JSON" per consentire che sia qualsiasi valore JSON, rimuovendo il vincolo che dovesse essere un oggetto o un array

  • Aggiunto linguaggio sui nomi di membri di oggetti duplicati, ordine dei membri e interoperabilità

  • Chiarito che i valori in un array non devono essere dello stesso tipo JSON

  • Applicato l'erratum #607 di RFC 4627 per correggere l'allineamento del diagramma della definizione "object"

  • Cambiato "as sequences of digits" in "in the grammar below" nella sezione "Numeri" e chiarita la base decimale

  • Aggiunto linguaggio sull'interoperabilità dei numeri come funzione IEEE754 e aggiunto riferimento IEEE754

  • Aggiunto linguaggio sull'interoperabilità e i caratteri Unicode e sul confronto di stringhe. Per questo, trasformata la vecchia sezione "Codifica" in sezione "Problemi di stringhe e caratteri" con tre sottosezioni: "Codifica dei caratteri", "Caratteri Unicode" e "Confronto di stringhe"

  • Cambiata la guida nella sezione "Parser" per indicare che le implementazioni possono impostare limiti sull'intervallo "e sulla precisione" dei numeri

  • Aggiornata e riorganizzata la sezione "Considerazioni IANA"

  • Creata una vera sezione "Considerazioni sulla sicurezza" ed estratto testo dalla sezione precedente "Considerazioni IANA"

  • Applicato l'erratum #3607 di RFC 4627 rimuovendo la considerazione sulla sicurezza che inizia con "A JSON text can be safely passed" e il codice JavaScript associato a tale considerazione

  • Aggiunta una nota nella sezione "Considerazioni sulla sicurezza" che evidenzia il rischio di utilizzare la funzione "eval()" in JavaScript o in qualsiasi altro linguaggio in cui il testo JSON è conforme alla sintassi di quel linguaggio

  • Aggiunta una nota in "Considerazioni IANA" che chiarisce che il tipo di media application/json manca di un parametro "charset"

  • Cambiato "100" in 100 nel primo esempio e aggiunto un campo booleano

  • Aggiunti esempi di testi JSON con valori semplici (né oggetto né array)

  • Aggiunta sezione "Contributori" per ringraziare Douglas Crockford

  • Aggiunto riferimento a RFC 4627

  • Spostato il riferimento ECMAScript da normativo a informativo e aggiornato per riferirsi a ECMAScript 5.1, e aggiunto riferimento a ECMA 404