JSON: conceptos y sintaxis

JSON, JavaScript Object Notation, es un formato textual para representar e intercambiar datos estructurados.

Aunque su sintaxis está inspirada en JavaScript, JSON es un formato independiente del lenguaje y puede utilizarse desde numerosos lenguajes y plataformas.

{
  "nombre": "Ana",
  "activo": true
}

Un documento JSON representa un valor. Ese valor puede ser un objeto, un array, una cadena, un número, un booleano o null.

Un objeto JSON está delimitado por llaves y contiene miembros formados por un nombre y un valor.

{
  "nombre": "Ana",
  "activo": true
}

Los nombres deben ser cadenas entre comillas dobles. Los dos puntos separan cada nombre de su valor y las comas separan los diferentes miembros.

JSON admite cadenas, números, booleanos, null, objetos y arrays.

{
  "texto": "dato",
  "numero": 42,
  "decimal": 3.14,
  "valido": true,
  "desactivado": false,
  "valor": null
}

JSON no incorpora tipos específicos para fechas, archivos binarios o clases propias de un lenguaje de programación.

Los números se escriben sin comillas.

42
-17
3.14
6.02e23

Un número entre comillas pasa a ser una cadena.

{
  "cantidad": 42,
  "codigo": "42"
}

Aunque ambos valores contienen los caracteres 42, no representan el mismo tipo de dato.

Dentro de un objeto, cada miembro relaciona un nombre con un valor.

{
  "nombre": "Ana",
  "edad": 32,
  "activo": true
}

La estructura básica de cada miembro es:

"nombre": valor

Las comas separan los diferentes miembros del objeto.

Una estructura habitual consiste en utilizar un array para representar una colección de objetos.

[
  {
    "id": 1,
    "nombre": "Linux"
  },
  {
    "id": 2,
    "nombre": "HTTP"
  },
  {
    "id": 3,
    "nombre": "JSON"
  }
]

Cada elemento del array es un valor JSON completo y, en este caso, cada valor es un objeto.

Un documento JSON válido debe respetar la gramática definida para el formato.

• Las cadenas utilizan comillas dobles.
• Los nombres de los miembros de un objeto son cadenas.
• Los miembros y elementos se separan mediante comas.
• No se permite una coma después del último elemento.
• JSON no incorpora comentarios.
• Los booleanos se escriben como true y false.
• El valor nulo se escribe null.

Los comentarios habituales de los lenguajes de programación no forman parte de la sintaxis JSON.

{
  // Esto no es JSON válido
  "activo": true
}

Algunas herramientas admiten extensiones que permiten comentarios, pero ese contenido no se ajusta estrictamente al formato JSON.

Muchas APIs utilizan JSON como representación de los datos enviados y recibidos mediante HTTP.

Content-Type: application/json

Una respuesta podría contener:

{
  "id": 42,
  "nombre": "Servidor",
  "activo": true
}

El código de estado HTTP describe el resultado de la petición, mientras que JSON puede utilizarse para representar los datos del cuerpo de la respuesta.

Puedes consultar también la ficha de códigos de estado HTTP .

Una respuesta HTTP puede indicar que su cuerpo contiene JSON mediante el tipo de contenido correspondiente.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "nombre": "Ana"
}

El cliente puede interpretar el documento y convertir sus valores a estructuras adecuadas para el lenguaje de programación utilizado.

Conviene distinguir el documento JSON de la estructura que una aplicación obtiene después de interpretarlo.

Texto JSON
↓
Parser
↓
Estructura del lenguaje

Por ejemplo, un objeto JSON puede convertirse en un diccionario, un mapa o una estructura equivalente dependiendo del lenguaje.

Un miembro cuyo valor es null no representa exactamente lo mismo que un miembro ausente.

Con valor nulo:

{
  "telefono": null
}

Sin ese miembro:

{}

La interpretación de esta diferencia depende del contrato de datos definido por cada aplicación o API.

Los espacios y saltos de línea permitidos pueden utilizarse para presentar un documento de forma más legible.

Forma compacta:

{"id":17,"nombre":"Recurso","activo":true}

Forma indentada:

{
  "id": 17,
  "nombre": "Recurso",
  "activo": true
}

Ambas formas representan la misma estructura de datos.

La validez sintáctica indica que el documento cumple las reglas de JSON, pero no garantiza que los valores sean correctos para una aplicación.

{
  "edad": -500
}

Este fragmento puede ser JSON sintácticamente válido aunque el valor resulte incorrecto para el dominio de una aplicación.

JSON válido
≠
Datos necesariamente válidos

• Confundir JSON con un lenguaje de programación.
• Confundir un objeto JSON con un objeto nativo de JavaScript.
• Utilizar comillas simples para cadenas o nombres.
• Añadir comentarios dentro de un documento JSON.
• Dejar una coma después del último elemento.
• Escribir True, False o None como si fueran valores JSON.
• Suponer que JSON dispone de un tipo nativo de fecha.
• Confundir null con la ausencia de un miembro.
• Asumir que un documento sintácticamente válido contiene necesariamente datos válidos para la aplicación.

• JSON es un formato textual de intercambio de datos.
• Puede representar objetos, arrays, cadenas, números, booleanos y null.
• Los nombres de los miembros de un objeto se escriben entre comillas dobles.
• JSON no admite comentarios ni comas finales.
• Los objetos y arrays pueden anidarse.
• JSON no dispone de un tipo específico para fechas.
• El formato es independiente del lenguaje de programación que lo procesa.
• La validez sintáctica no sustituye a la validación de los datos de una aplicación.

Documentación primaria y referencias reconocidas para ampliar esta ficha.

• RFC 8259 · JSON Data Interchange Format
• ECMA-404 · JSON Data Interchange Syntax