Formato JSON: Guía Completa sobre JavaScript Object Notation

¿Qué es JSON?

JSON son las siglas de JavaScript Object Notation (Notación de Objetos de JavaScript), un formato de intercambio de datos ligero y basado en texto derivado de la sintaxis literal de objetos de JavaScript. A pesar de sus orígenes en JavaScript, JSON es independiente del lenguaje: todos los principales lenguajes de programación tienen soporte integrado o de biblioteca ampliamente utilizado para analizar y generar JSON.

JSON fue popularizado por Douglas Crockford a principios de los años 2000 como una alternativa más sencilla a XML para el intercambio de datos en APIs web. Ahora está formalizado en dos estándares complementarios: RFC 8259 (el estándar definitivo de IETF) y ECMA-404 (la especificación mínima y formal).

Seis Tipos de Datos

JSON define exactamente seis tipos de datos:

1. null — representa la ausencia de valor: null
2. boolean — true o false
3. number — punto flotante de doble precisión IEEE 754: 42, 3.14, -7, 1.5e10
4. string — texto UTF-8 entre comillas dobles: "hola", "café", "línea1\nlínea2"
5. array — secuencia ordenada de valores: [1, "dos", null, true]
6. object — colección desordenada de pares clave-valor: {"clave": "valor", "n": 42}

Todo en JSON se construye a partir de estos seis tipos. No existe concepto de fechas, datos binarios, undefined, funciones, expresiones regulares o comentarios.

Reglas de Sintaxis

{
  "nombre": "Alicia",
  "edad": 30,
  "activo": true,
  "puntuacion": 98.6,
  "etiquetas": ["admin", "editor"],
  "direccion": {
    "calle": "C/ Mayor 123",
    "ciudad": "Madrid",
    "cp": "28001"
  },
  "apodo": null
}

Requisitos estrictos de sintaxis:

• Las claves deben ser cadenas (entre comillas dobles)
• Las cadenas deben usar comillas dobles (las comillas simples no son válidas)
• Las comas finales son inválidas (sin coma después del último elemento)
• Los comentarios son inválidos (no forman parte de la especificación JSON)
• Los números no pueden tener ceros iniciales (01 es inválido)
• Los números no pueden ser NaN ni Infinity

Precisión de Números

Los números JSON se mapean a punto flotante de doble precisión IEEE 754, que tiene 53 bits de precisión de significando. Esto causa un problema conocido: los enteros mayores de 2^53 (9.007.199.254.740.992) no se pueden representar exactamente.

{"id": 9007199254740993}

JSON.parse() de JavaScript analizará 9007199254740993 como 9007199254740992 — con un error de uno, silenciosamente. Por eso Twitter, Facebook y muchas APIs devuelven los IDs de enteros grandes como número y como cadena: {"id": 1234567890123456789, "id_str": "1234567890123456789"}.

JSON Schema

JSON Schema es un vocabulario para validar y describir documentos JSON. Permite especificar restricciones como:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "nombre": {"type": "string", "minLength": 1},
    "edad": {"type": "integer", "minimum": 0, "maximum": 150},
    "email": {"type": "string", "format": "email"}
  },
  "required": ["nombre", "edad"]
}

JSON Schema permite la validación automatizada, el autocompletado en IDE, las pruebas de contrato de API y la generación de documentación.

Extensiones JSON5 y JSONC

Porque la sintaxis estricta de JSON frustra a los autores de archivos de configuración, han surgido varias extensiones:

JSON5: Un superconjunto de JSON que permite:

• Comentarios de una línea (// ...)
• Comentarios multilínea (/* ... */)
• Comas finales
• Cadenas entre comillas simples
• Claves de objeto sin comillas (si son identificadores válidos)
• Números hexadecimales (0xFF)

JSONC (JSON con Comentarios): Permite comentarios // y /* */ pero nada más. Usado por el settings.json de VS Code, el tsconfig.json de TypeScript, etc. No analizable por analizadores JSON estándar.

JSON frente a XML frente a YAML

Patrones JSON Comunes

Respuesta de API con envoltura:

{
  "estado": "exito",
  "datos": {
    "usuarios": [
      {"id": 1, "nombre": "Alicia"},
      {"id": 2, "nombre": "Roberto"}
    ]
  },
  "meta": {
    "total": 2,
    "pagina": 1,
    "por_pagina": 10
  }
}

JSON Lines (JSONL) — un objeto JSON por línea, para streaming y archivos de registro:

{"id": 1, "evento": "inicio_sesion", "ts": "2024-01-15T10:30:00Z"}
{"id": 2, "evento": "compra", "ts": "2024-01-15T10:31:00Z"}

Procesamiento de JSON

Línea de comandos (jq):

# Extraer todos los nombres de un array de objetos
cat datos.json | jq '.[].nombre'

# Filtrar objetos donde edad > 25
cat datos.json | jq '[.[] | select(.edad > 25)]'

# Convertir JSON a CSV
cat datos.json | jq -r '["nombre","edad"], (.[] | [.nombre, .edad]) | @csv'

Python:

import json

# Analizar cadena JSON
datos = json.loads('{"nombre": "Alicia", "edad": 30}')
print(datos['nombre'])  # Alicia

# Serializar a cadena JSON
cadena_json = json.dumps(datos, indent=2, ensure_ascii=False)

# Leer/escribir archivos
with open('datos.json') as f:
    datos = json.load(f)

with open('salida.json', 'w') as f:
    json.dump(datos, f, indent=2, ensure_ascii=False)

Conversión de JSON

JSON → CSV: Funciona cuando JSON es un array de objetos planos (sin objetos anidados). jq -r, in2csv de csvkit, o json_normalize de pandas.

JSON → XML: La estructura debe mapearse (arrays JSON → elementos XML repetidos; claves → nombres de etiqueta o atributos).

JSON → YAML: Casi sin pérdida para la mayoría de los datos, ya que YAML es un superconjunto de JSON. python -c "import json, yaml, sys; yaml.dump(json.load(sys.stdin), sys.stdout)".

Resumen

JSON es la lingua franca de las APIs web modernas, los archivos de configuración y el intercambio de datos. Su modelo de datos de seis tipos, su sintaxis estricta y su formato basado en texto equilibran la legibilidad humana con la capacidad de análisis mecánico. Las limitaciones clave — sin comentarios, sin tipo de fecha nativo, sin binario, límite de precisión de enteros en 2^53 — son bien conocidas y tienen soluciones establecidas. Para archivos de configuración que necesitan comentarios, JSON5 o JSONC son extensiones prácticas; para datos con jerarquías complejas, XML añade características de espacio de nombres y esquema; para configuraciones creadas por humanos, YAML es más legible. El propio JSON domina todo lo que hay entre medias.

Conversiones relacionadas

Conversiones de documento que siguen este tema:

• PDF a DOCX
• DOCX a PDF
• MD a PDF
• HTML a PDF
• ODT a PDF
• PDF a TXT