¿Qué es un Documento JSON?

¿Qué es un documento JSON?

Un documento JSON es un archivo de texto o un mensaje escrito en JavaScript Object Notation: un formato pequeño y legible para datos estructurados formado por objetos, arrays, strings, números, booleanos y null. Las APIs, los archivos de configuración y las bases de datos documentales lo usan porque todos los lenguajes habituales pueden parsearlo. El formato está definido en RFC 8259 y en ECMA-404. Para un primer recorrido por la sintaxis, consulta JSON: guía para principiantes.

Los tipos de valor

Según el RFC 8259, un valor JSON debe ser un objeto, un array, un número o un string, o uno de los tres nombres literales true, false y null.

• Objeto: { "key": value }, un conjunto de pares nombre-valor. Los nombres siempre son strings.
• Array: [ value, value ], una lista ordenada.
• String: "hello", texto entre comillas dobles.
• Número: 42, 3.14, 1e10. El formato no distingue entre enteros y decimales.
• Booleano: true o false, en minúsculas y sin comillas.
• Null: null, la ausencia explícita de valor.

No hay tipo fecha, ni tipo binario, ni sintaxis de comentarios. Las fechas y los datos binarios viajan como strings por convención.

Un ejemplo

{
  "id": "order_42",
  "customer": { "name": "Alice", "verified": true },
  "items": [
    { "sku": "WIDGET-1", "qty": 2, "price": 9.99 },
    { "sku": "GIZMO-7", "qty": 1, "price": 19.95 }
  ],
  "shipped_at": null,
  "tags": ["priority", "gift"]
}

Cada valor es de uno de los tipos anteriores, y los objetos y arrays pueden anidarse todo lo que haga falta. El mismo texto da la misma estructura en cualquier lenguaje.

Dónde aparecen los documentos JSON

• APIs: cuerpos de petición y de respuesta, normalmente con el tipo de medio application/json. Consulta payload de una API y, para el estilo de llamada remota que envuelve sus mensajes en JSON, JSON-RPC.
• Configuración: package.json y tsconfig.json son ejemplos cotidianos.
• Bases de datos documentales: MongoDB, Firestore y DynamoDB trabajan con datos en forma de documento.
• Logs: el logging estructurado escribe un objeto JSON por línea.
• Datos estructurados para buscadores: JSON-LD incrusta datos de schema.org en una página web.

Errores que rompen un JSON

• Comas finales. {"a":1,} no es válido. JavaScript lo tolera, JSON no.
• Comentarios. JSON no los tiene. Formatos como JSON5 y JSONC los añaden, pero un parser estricto los rechaza.
• Comillas simples o nombres sin comillas. Los nombres y los strings necesitan comillas dobles.
• Enteros grandes. El RFC 8259 señala que el software suele usar números de doble precisión IEEE 754, y JSON.parse de JavaScript también, así que los enteros por encima de 2^53 - 1 (9007199254740991) pueden perder precisión. Envía los IDs de 64 bits como strings.
• Nombres duplicados. El RFC dice que los nombres dentro de un objeto deberían ser únicos y que, si no, el comportamiento es impredecible.
• Codificación incorrecta. Según el RFC, el texto JSON intercambiado entre sistemas debe ir en UTF-8.

JSON frente a otros formatos

• YAML es más fácil de escribir a mano y admite comentarios, por eso lo usan los archivos de CI y Kubernetes. También es sensible a la indentación.
• XML encaja con el marcado de documentos y los sistemas empresariales antiguos, a costa de una sintaxis más extensa.
• Protocol Buffers es binario y necesita un esquema, lo que sirve para RPC de alto volumen pero cuesta más leer.

Para describir qué aspecto tiene un documento válido se usa JSON Schema. El blog de LoadFocus lo explica en what is JSON Schema.

Probar endpoints JSON

Un endpoint JSON puede devolver 200 con un cuerpo incorrecto. La monitorización de API de LoadFocus comprueba el código de estado, el cuerpo, las cabeceras y el tiempo de respuesta de forma programada, y cita la coincidencia con un esquema JSON como ejemplo de comprobación. Las comprobaciones gratuitas se ejecutan cada 5 minutos. Para ver cómo se comporta un endpoint con muchos llamantes a la vez, haz una prueba de carga de API. Más sobre la práctica en monitorización de API.

Preguntas frecuentes: documentos JSON

¿Qué diferencia hay entre JSON y un objeto de JavaScript?

JSON es texto. Un objeto de JavaScript es un valor en memoria. JSON es más estricto: los nombres y los strings necesitan comillas dobles, y no admite funciones, undefined ni comentarios. JSON.parse convierte el texto en un objeto.

¿Cómo valido un documento JSON?

Pásalo por un parser. En la línea de comandos, jq . file.json muestra el documento o el primer error de sintaxis. Para comprobar también la estructura, valida contra un JSON Schema.

¿Qué tamaño puede tener un documento JSON?

El formato no fija un límite. Los límites vienen del parser, que puede cargar el documento entero en memoria, y de los servidores y gateways intermedios. Para conjuntos de datos muy grandes, envía un objeto JSON por línea (NDJSON) o usa un formato binario.

¿Cómo guardo una fecha en JSON?

JSON no tiene tipo fecha. Lo habitual es un string ISO 8601 como "2026-05-07T08:22:00Z". Ambos lados tienen que acordarlo.

¿Uso JSON o YAML para configuración?

JSON para archivos que generan herramientas. YAML para archivos que las personas editan a mano y donde importan los comentarios. Muchos ecosistemas tienen una convención, así que síguela.