Hoja de trucos de sintaxis JSON

Los seis caracteres estructurales

Seis caracteres de puntuación cargan con toda la estructura en JSON: las llaves { } que envuelven objetos, los corchetes [ ] que envuelven arrays, los dos puntos : que separan una clave de su valor, y la coma , que separa pares dentro de un objeto o valores dentro de un array. Nada más en la gramática hace trabajo estructural — cualquier otro carácter de un documento está dentro de una cadena o es uno de los cuatro caracteres de espacio en blanco. Una coma es estrictamente un separador: puede aparecer entre dos elementos, nunca delante de una llave o un corchete de cierre.

{"name":"Ada","tags":["math","pioneer"]}

{"name":"Ada","tags":["math","pioneer"],}

Espacio en blanco: exactamente cuatro caracteres

Fuera de las cadenas, JSON permite exactamente cuatro caracteres de espacio en blanco: el espacio (U+0020), el tabulador horizontal (U+0009), el salto de línea (U+000A) y el retorno de carro (U+000D). Cualquier otra cosa — tabulador vertical, alimentación de formulario, espacio duro, una marca de orden de bytes — es un error de sintaxis, aunque muchos editores muestren esos caracteres de forma invisible. Por eso el JSON pegado desde un procesador de textos falla tan a menudo la validación: el documento se ve limpio en pantalla y contiene caracteres que la gramática no conoce.

El espacio en blanco es también lo que hace posible dar formato. Como la gramática ignora estos cuatro caracteres entre tokens, el mismo documento puede ser una única línea larga en la transmisión y un árbol indentado en tu editor, y las dos formas son semánticamente idénticas — ningún analizador puede distinguirlas después de leer.

{"a":1,"b":[2,3]}

{
  "a": 1,
  "b": [
    2,
    3
  ]
}

Cadenas: comillas dobles y los nueve escapes

Una cadena JSON va envuelta en comillas dobles — nunca comillas simples. Dentro, la barra invertida \ introduce un escape, y RFC 8259 define exactamente nueve escapes de dos caracteres: dos son obligatorios, \\" para una comilla doble literal y \\\\ para una barra invertida literal, porque esos dos caracteres, de otro modo, terminarían o corromperían la cadena. Seis más son abreviaturas opcionales — \/ para la barra diagonal y \b \f \n \r \t para los cinco caracteres de control que aparecen con más frecuencia en el texto. La novena forma es \uXXXX, que escribe cualquier punto de código Unicode mediante su número hexadecimal de cuatro dígitos.

Todos los caracteres fuera del conjunto de escapes pueden aparecer literalmente como UTF-8, y las dos formas son equivalentes: un analizador entrega la cadena idéntica de cualquier manera. Escapar es grafía, no datos — un punto que la guía de escape desarrolla a fondo.

"quote": "she said \"hi\""
"path": "C:\\Users\\ada"
"e-acute": "\u00e9"

quote:   she said "hi"
path:    C:\Users\ada
e-acute: é

Números: ECMAScript, sin las extensiones

Un número es un entero o un decimal en notación llana, con un exponente opcional. RFC 8259 adopta la gramática de números de ECMAScript y elimina sus extensiones: nada de hexadecimal, nada de octal, nada de ceros a la izquierda, nada de signo más inicial, nada de punto final suelto. Un exponente usa e o E con un signo opcional, y el único signo con el que puede empezar un número es el guion simple. NaN, Infinity y -Infinity no son JSON — los lenguajes que tienen tales constantes escriben null en su lugar por convención.

La precisión se deja deliberadamente en manos de las implementaciones: la gramática no dice nada sobre cuántos dígitos debe honrar un analizador, así que números muy largos pueden llegar cambiados en silencio. Los generadores interoperables mantienen los enteros dentro del rango que la plataforma de destino representa exactamente — para los dobles IEEE 754 que hay detrás de JavaScript, hasta 2^53 − 1.

Los tres literales y los cinco rechazos clásicos

Tres tokens en crudo completan el conjunto de valores: true, false y null. Van en minúsculas y sin comillas — True, FALSE y None son errores de sintaxis, no mayúsculas creativas. Alrededor de ellos, la gramática traza cinco líneas que explican casi todos los documentos rechazados que existen:

• Sin comentarios. RFC 8259 no tiene sintaxis de comentarios; // o /* */ en cualquier lugar es un error de sintaxis. Anota con una clave hermana como "_comment" cuando el formato esté bajo tu control.
• Sin comas finales. [1, 2, 3,] y {"a":1,} son inválidos, por amigables que parezcan — la coma es un separador, y no puede separar un elemento de nada.
• Sin comillas simples ni claves sin comillas. {name:'ada'} es JSON inválido; {"name":"ada"} es la única grafía que permite la gramática.
• Sin claves duplicadas — oficialmente. La gramática permite que un nombre aparezca dos veces, pero RFC 8259 §4 deja en manos de las implementaciones qué valor gana, así que un documento que dependa de duplicados no tiene significado definido.
• Cualquier valor de nivel superior. Desde RFC 8259, un documento entero puede ser una cadena, un número, un booleano o un null en crudo — la regla de RFC 4627 de solo objetos y arrays desapareció, y "hello" o 42 son documentos JSON completos.

Codificación: UTF-8 y las reglas a nivel de bytes

RFC 8259 §8.1 fija la codificación de bytes: el texto JSON intercambiado entre sistemas que no forman parte de un ecosistema cerrado debe estar codificado en UTF-8. No existe JSON en UTF-16 o UTF-32 en la red abierta, y los generadores no deben anteponer una marca de orden de bytes — un analizador puede ignorar un BOM inicial en lugar de fallar, pero nada conforme emite uno. Fíjate en cómo se separan las capas: el escape \uXXXX es una elección de notación dentro de cadenas individuales, mientras que UTF-8 es una propiedad del documento completo, y las dos resuelven problemas distintos.

Con esto se cierra la gramática. La manera más rápida de fijar estas reglas es someter a ellas tus propios documentos — dale formato a una carga útil real, rompe una regla cada vez y lee cada error del validador. Diez minutos de fallo deliberado enseñan más que otra pasada por esta página.