Cómo escribir JSON: guía completa de sintaxis

Q: ¿Puedo escribir comentarios en JSON?

No. //, /* */ y # son todos inválidos en JSON estándar. Si necesitas comentarios en un archivo de configuración, usa un superconjunto como JSONC o JSON5, o adopta una convención como claves "_comment": "...". Consulta Cómo añadir comentarios a JSON para conocer las cuatro soluciones comunes.

La sintaxis de JSON cabe en una ficha. Hay seis tipos de datos, dos estructuras contenedoras y un puñado de reglas. Eso es realmente todo. Pero la simplicidad es engañosa: la gente sigue cometiendo errores al escribir JSON a mano, sobre todo quienes están acostumbrados a las reglas más relajadas de JavaScript o Python.

Esta guía es una referencia completa de la sintaxis de JSON. Cada tipo de dato, cada regla y muchos ejemplos. Guárdala en marcadores para la próxima vez que necesites escribir o depurar JSON manualmente.

La gramática de JSON está definida oficialmente en RFC 8259 y ECMA-404. Ambas especificaciones coinciden en la sintaxis; esta guía cubre las mismas reglas con ejemplos prácticos y los errores que más comete la gente al escribir JSON a mano.

Si JSON es algo completamente nuevo para ti, empieza por ¿Qué es JSON? Una guía para principiantes y vuelve aquí para la referencia detallada de sintaxis.

El elemento raíz

Un documento JSON es un único valor. Ese valor suele ser un objeto o un arreglo, pero la especificación permite cualquiera de los seis tipos en el nivel superior.

Documentos JSON válidos:

{"name": "Alice"}

[1, 2, 3]

"just a string"

true

null

En la práctica, casi siempre verás un objeto o un arreglo como raíz. Las APIs devuelven objetos, los feeds de datos devuelven arreglos de objetos y los archivos de configuración son objetos.

Cadenas

Las cadenas son el tipo de valor JSON más común, y son las que tienen más reglas.

Las comillas dobles son obligatorias

Las cadenas JSON deben ir entre comillas dobles. No comillas simples. No comillas invertidas.

{ "correct": "hello" }

Todos estos son inválidos:

{ 'wrong': 'hello' }
{ `wrong`: `hello` }
{ wrong: "hello" }

El último ejemplo, una clave sin comillas, es JavaScript válido pero no JSON válido. Este es probablemente el error más común que comete la gente al escribir JSON a mano.

Secuencias de escape

Ciertos caracteres deben escaparse con una barra invertida dentro de las cadenas:

Sequence	Meaning
`\"`	Double quote
`\\`	Backslash
`\/`	Forward slash
`\b`	Backspace
`\f`	Form feed
`\n`	Newline
`\r`	Carriage return
`\t`	Tab
`\uXXXX`	Unicode character

Ejemplo:

{
  "path": "C:\\Users\\alice\\documents",
  "message": "She said \"hi\"",
  "newline": "Line one\nLine two"
}

Unicode

JSON se codifica en UTF-8 (o UTF-16 o UTF-32, aunque UTF-8 es el dominante). Puedes incluir caracteres Unicode directamente o usar secuencias de escape \u:

{
  "direct": "café",
  "emoji": "❤",
  "japanese": "東京"
}

La mayoría de las veces basta con escribir los caracteres directamente. El escape \u es útil sobre todo cuando necesitas incluir caracteres difíciles de teclear o que podrían corromperse por problemas de codificación de texto.

Lo que las cadenas no pueden contener

Los caracteres de control sin procesar (de U+0000 a U+001F) deben escaparse. No puedes poner un carácter de tabulación o un salto de línea literal dentro de una cadena JSON: usa \t y \n en su lugar.

Números

Los números en JSON son sencillos, pero hay algunas restricciones en comparación con lo que permite JavaScript.

Enteros

{
  "positive": 42,
  "negative": -17,
  "zero": 0
}

Punto flotante

{
  "pi": 3.14159,
  "small": 0.001
}

Ten en cuenta que .5 no es JSON válido. Debes escribir 0.5. El cero inicial es obligatorio.

Notación científica

{
  "avogadro": 6.022e23,
  "planck": 6.626e-34,
  "explicit": 1.0E+10
}

La e puede ir en mayúscula o minúscula. El exponente puede llevar un signo + o -.

Lo que los números no pueden ser

Sin ceros a la izquierda: 007 es inválido. Usa 7.
Sin hexadecimal: 0xFF es inválido. Usa 255.
Sin octal: 0o17 es inválido. Usa 15.
Sin NaN ni Infinity: no son valores JSON válidos. Si necesitas representarlos, usa null o una cadena como "NaN".
Sin decimal final: 42. es inválido. Usa 42 o 42.0.

Consideraciones de precisión

La especificación de JSON no define límites de precisión para los números, pero en la práctica la mayoría de los analizadores usan punto flotante de doble precisión IEEE 754. Esto significa que los enteros mayores que 2^53 (9.007.199.254.740.992) pueden perder precisión. Si trabajas con enteros muy grandes, como los IDs snowflake de Twitter, es práctica común transmitirlos como cadenas.

{
  "safe": 9007199254740991,
  "asString": "9007199254740993"
}

Booleanos

Dos valores, en minúscula:

{
  "active": true,
  "deleted": false
}

No True, no TRUE, no 1, no "true". Solo true y false.

Esto parece obvio, pero provoca errores cuando se copian valores desde Python (que usa True y False con mayúsculas) o desde YAML (que acepta yes, no, on, off).

Null

Un valor, en minúscula:

{
  "middleName": null
}

No None (eso es Python), no nil (eso es Ruby), no undefined (eso es JavaScript). JSON no tiene el concepto de undefined: si una clave no tiene valor, o la fijas en null o la omites por completo.

Objetos

Los objetos son la estructura central de JSON. Son colecciones no ordenadas de pares clave-valor.

Sintaxis básica

{
  "key": "value",
  "anotherKey": 42
}

Reglas:

Las llaves {} envuelven el objeto
Las claves deben ser cadenas (entre comillas dobles)
Un signo de dos puntos separa la clave del valor
Las comas separan los pares
Sin coma final después del último par

Objetos vacíos

{}

Perfectamente válido. Representa un objeto sin propiedades.

Objetos anidados

Los objetos pueden contener otros objetos:

{
  "user": {
    "name": "Alice",
    "address": {
      "street": "123 Main St",
      "city": "Tokyo",
      "country": "Japan"
    }
  }
}

La especificación no impone un límite a la profundidad del anidamiento, aunque las estructuras muy anidadas se vuelven difíciles de leer y algunos analizadores imponen límites prácticos.

Orden de las claves

La especificación de JSON dice que los objetos no están ordenados. Esto significa que {"a": 1, "b": 2} y {"b": 2, "a": 1} son semánticamente equivalentes. En la práctica, la mayoría de los analizadores conservan el orden de inserción, pero no deberías depender del orden de las claves.

Claves duplicadas

La especificación desaconseja las claves duplicadas, pero no las prohíbe de forma explícita. El comportamiento varía según el analizador: algunos toman el último valor, otros el primero, otros lanzan un error y unos pocos conservan ambos. La regla de que "gana el último valor" es la más común, pero no está garantizada.

{
  "name": "Alice",
  "name": "Bob"
}

El resultado de analizar este documento depende de la biblioteca: podrías obtener "Alice", "Bob" o un error de análisis. Si no puedes garantizar la unicidad en el productor, valida la salida con JSON Formatter: las claves duplicadas se hacen visibles cuando ordenas o aplicas formato legible a los datos.

Arreglos

Los arreglos son listas ordenadas de valores.

Sintaxis básica

[1, 2, 3, 4, 5]

Reglas:

Los corchetes [] envuelven el arreglo
Las comas separan los valores
Sin coma final después del último valor
Los valores pueden ser de cualquier tipo JSON

Arreglos vacíos

[]

Arreglos de tipos mixtos

JSON permite arreglos con tipos mixtos:

[42, "hello", true, null, {"key": "value"}, [1, 2]]

Esto es válido, pero en la práctica los arreglos suelen contener valores del mismo tipo. Un arreglo de objetos es el patrón más común.

Arreglos de objetos

Esta es la estructura que encontrarás con más frecuencia al trabajar con APIs y feeds de datos:

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com"
  }
]

Cada objeto del arreglo suele tener el mismo conjunto de claves, formando algo parecido a una tabla en la que cada objeto es una fila.

Patrones de anidamiento

El JSON del mundo real combina objetos y arreglos de varias maneras. Estos son los patrones comunes.

Objeto que contiene arreglos

{
  "name": "Project Alpha",
  "tags": ["web", "api", "typescript"],
  "contributors": [
    { "name": "Alice", "role": "lead" },
    { "name": "Bob", "role": "developer" }
  ]
}

Arreglo que contiene objetos anidados

[
  {
    "department": "Engineering",
    "teams": [
      {
        "name": "Frontend",
        "members": ["Alice", "Bob"]
      },
      {
        "name": "Backend",
        "members": ["Charlie", "Diana"]
      }
    ]
  }
]

Estructuras muy anidadas

{
  "company": {
    "departments": [
      {
        "name": "Engineering",
        "teams": [
          {
            "name": "Frontend",
            "projects": [
              {
                "name": "Dashboard",
                "status": "active",
                "milestones": [
                  { "name": "v1.0", "date": "2026-06-01" }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Esto es válido, pero se vuelve difícil de leer. Cuando te encuentres con JSON muy anidado, un JSON Formatter ayuda al aplicar una sangría coherente.

Espacios en blanco

JSON ignora los espacios en blanco entre tokens. Todos estos son equivalentes:

Compacto:

{"name":"Alice","age":30}

Legible:

{
  "name": "Alice",
  "age": 30
}

Con espacios de más:

{
    "name"  :  "Alice"  ,
    "age"   :  30
}

Para la transmisión y el almacenamiento, el JSON compacto ahorra ancho de banda. Para leer y editar, el JSON con sangría es mucho más fácil de manejar. La mayoría de las herramientas y bibliotecas te dejan elegir el formato.

Errores comunes

Estos son los errores que surgen con más frecuencia al escribir JSON a mano.

Comas finales

{
  "a": 1,
  "b": 2,
}

Esa coma final después de "b": 2 es inválida. JavaScript y muchos otros lenguajes la permiten, pero JSON no. Este es probablemente el error de sintaxis de JSON más común de todos.

Comillas simples

{'name': 'Alice'}

Inválido. JSON requiere comillas dobles tanto para las claves como para los valores de cadena.

Claves sin comillas

{name: "Alice"}

Inválido. Las claves deben ser cadenas entre comillas dobles.

Comentarios

{
  // this is not allowed
  "name": "Alice"
}

JSON no tiene sintaxis de comentarios. Ni //, ni /* */, ni #. Si necesitas JSON con comentarios, considera JSONC o JSON5, pero ten en cuenta que los analizadores de JSON estándar los rechazarán.

Undefined y NaN

{
  "value": undefined,
  "result": NaN
}

Ni undefined ni NaN son valores JSON válidos. Usa null para los valores faltantes y una cadena o null para los resultados no numéricos.

Un valor único sin comillas

hello

Una cadena sin comillas y sin envoltorio no es JSON válido. Tendría que ser "hello".

Para profundizar en el diagnóstico y la corrección de estos errores, consulta Soluciones a errores de análisis de JSON. Cuando reparas JSON a mano, pegarlo en JSON Formatter muestra la posición del error con un número de línea para que detectes el carácter dañado de un vistazo.

Validar tu JSON

Cuando escribes JSON a mano, ocurren errores. Una coma que falta, una comilla de más, una coma final: todos provocan errores de análisis que pueden ser frustrantes de rastrear en un documento grande.

El JSON Formatter validará tu JSON y señalará los errores de sintaxis. Pega tu JSON y, si hay un error, verás exactamente qué salió mal.

También puedes validar desde la línea de comandos:

# Using Python
python3 -m json.tool < file.json

# Using jq
jq . file.json

Ambos imprimirán JSON con formato si todo va bien, o un mensaje de error si falla. Para aplicar formato legible al JSON que devuelven las llamadas a API con curl, consulta Cómo aplicar formato legible al JSON de curl.

Convenciones de formato de JSON

Aunque la sintaxis de JSON es fija, existen convenciones que hacen que JSON sea más fácil de manejar:

Usa una sangría de 2 espacios (la convención más común)
Mantén las claves en un orden coherente entre objetos similares
Usa camelCase o snake_case para los nombres de las claves, pero sé coherente
Evita las estructuras muy anidadas cuando un diseño más plano funciona

Para profundizar en estas convenciones, consulta Consejos de formato de JSON.

Referencia rápida

Todo valor JSON válido pertenece a una de estas categorías:

Type	Example	Notes
String	`"hello"`	Double quotes required
Number	`42`, `3.14`, `1e10`	No hex, no leading zeros
Boolean	`true`, `false`	Lowercase only
Null	`null`	Lowercase only
Object	`{"key": "value"}`	Keys must be strings
Array	`[1, 2, 3]`	Ordered, mixed types allowed

Ese es todo el lenguaje. Todo lo que verás en un documento JSON es alguna combinación de estos seis tipos.

Preguntas frecuentes

¿Puedo escribir comentarios en JSON?

No. //, /* */ y # son todos inválidos en JSON estándar. Si necesitas comentarios en un archivo de configuración, usa un superconjunto como JSONC o JSON5, o adopta una convención como claves "_comment": "...". Consulta Cómo añadir comentarios a JSON para conocer las cuatro soluciones comunes.

¿Se permiten las comas finales en JSON?

No. Una coma después del último elemento de un arreglo u objeto es un error de sintaxis en casi todos los analizadores de JSON. Los literales de JavaScript y Python aceptan comas finales, así que es un desliz común al pegar desde código fuente.

¿Las claves de JSON realmente necesitan comillas dobles?

Sí. Las claves de JSON deben ser cadenas envueltas en comillas dobles. La forma de clave sin comillas {name: "Alice"} es JavaScript válido pero JSON inválido. Las comillas simples 'name' tampoco se permiten.

¿Cómo localizo rápidamente un error de análisis de JSON?

Pega el JSON en el JSON Formatter: resalta la línea que falla. Desde la línea de comandos, python3 -m json.tool < file.json o jq . file.json también informan el número de línea. Para conocer las causas y correcciones comunes, consulta Soluciones a errores de análisis de JSON.

Próximos pasos

Prueba el JSON Formatter para validar y dar formato a tu JSON
Lee sobre las Soluciones a errores de análisis de JSON cuando te encuentres con errores de sintaxis
Echa un vistazo a los Consejos de formato de JSON para conocer convenciones y buenas prácticas
Vuelve a ¿Qué es JSON? para una visión más amplia del formato y dónde se usa
Compara con la guía de sintaxis de YAML: el mismo modelo de datos, con sintaxis basada en sangría