Introducción: Los Objetos JSON Parecen Simples, pero las Reglas Son Precisas
Un objeto JSON es el caballo de batalla de casi toda API web moderna, archivo de configuración y formato de intercambio de datos. Parece trivial: un par de llaves con algunas claves y valores dentro. Sin embargo, una parte sorprendente de los errores de "JSON inválido" proviene de un puñado de pequeñas violaciones de reglas — una clave sin comillas, una comilla simple donde debería ir una doble, una coma final o un comentario despistado. No son preferencias de estilo. Son requisitos estrictos definidos por la especificación que gobierna JSON, y cualquier analizador conforme rechazará el texto que las incumpla.
Esta guía es una referencia precisa y basada en ejemplos sobre cómo deben escribirse los objetos JSON según la RFC 8259 — el estándar de Internet vigente para el formato de intercambio de datos JSON. Cubriremos qué es realmente un objeto, por qué los nombres deben ser cadenas, por qué las cadenas deben usar comillas dobles, los seis caracteres estructurales, la prohibición de comas finales y comentarios, y la cuestión sorprendentemente sutil de los nombres duplicados. Cada regla va acompañada de ejemplos válidos e inválidos para que veas exactamente dónde los analizadores trazan la línea. Mientras los repasas, pega tus propios fragmentos en nuestro formateador y validador JSON para confirmar cada regla en la práctica — marca el carácter exacto donde un documento deja de ser JSON válido.
Qué Es Realmente la RFC 8259
La RFC 8259, "The JavaScript Object Notation (JSON) Data Interchange Format", se publicó en diciembre de 2017. Está designada como STD 90, lo que significa que es un estándar de Internet completo y no una mera propuesta, y deja obsoletas las anteriores RFC 7159 y RFC 4627. Coexiste con ECMA-404, el estándar mantenido por Ecma International; ambos documentos describen la misma gramática y se mantienen deliberadamente en concordancia, de modo que un documento válido bajo uno es válido bajo el otro.
La RFC define los cuatro tipos primitivos de JSON (cadenas, números, booleanos y null) y dos tipos estructurados (objetos y arrays). Mantiene la gramática pequeña de forma intencionada. No hay versionado, ni mecanismo de esquema, ni previsión de comentarios o extensiones dentro de la sintaxis misma. Ese minimalismo es la razón por la que JSON viaja tan bien entre lenguajes: hay muy poco sobre lo que discrepar. Nuestro foco aquí es el tipo objeto, que es donde ocurren la mayoría de los errores de sintaxis.
Un Objeto Es un Conjunto No Ordenado de Pares Nombre/Valor
La RFC 8259 define un objeto JSON como una colección no ordenada de cero o más pares nombre/valor, donde un nombre es una cadena y un valor es cualquier valor JSON válido. Los pares se envuelven en llaves, cada nombre se separa de su valor mediante dos puntos, y los pares se separan entre sí mediante comas.
El objeto más pequeño posible es el objeto vacío, escrito como dos llaves adyacentes:
{}
Un objeto con contenido tiene este aspecto:
{
"id": 42,
"name": "Ada Lovelace",
"active": true
}
Merece la pena interiorizar dos consecuencias de la definición. Primera, el orden no es significativo. La especificación describe un objeto como no ordenado, así que un analizador no está obligado a preservar la secuencia en la que aparecieron los pares, y dos objetos con los mismos pares en distinto orden representan los mismos datos. En la práctica muchos analizadores (incluido el de JavaScript) sí preservan el orden de inserción para claves de tipo cadena, pero nunca debes depender del orden para la corrección — una implementación conforme es libre de reordenar. Segunda, un objeto puede contener cero pares; el objeto vacío es perfectamente válido y frecuente como valor por defecto o marcador de posición.
Los valores dentro de un objeto pueden ser cualquier valor JSON, incluidos objetos y arrays anidados. Esta composición es lo que hace a JSON expresivo:
{
"user": {
"name": "Grace",
"roles": ["admin", "editor"]
},
"count": 0
}
Los Nombres (Claves) Deben Ser Cadenas
Esta es la regla que más incumplen los desarrolladores que vienen de JavaScript. En código fuente JavaScript puedes escribir un literal de objeto con claves como identificadores desnudos — { name: "Grace" } — y el lenguaje lo acepta. JSON no. En JSON, cada nombre de un par nombre/valor debe ser una cadena, lo que significa que debe ir encerrado entre comillas dobles.
Válido — el nombre es una cadena entre comillas:
{ "name": "Grace" }
Inválido — el nombre es un identificador desnudo, no una cadena:
{ name: "Grace" }
Inválido — el nombre usa comillas simples, que no producen una cadena JSON:
{ 'name': "Grace" }
Como los nombres son cadenas, pueden contener cualquier carácter que pueda contener una cadena JSON, incluidos espacios, puntuación y Unicode: { "full name": "Grace Hopper", "emoji": "ok" } es válido. Un nombre puede incluso ser la cadena vacía: { "": "value" } es legal, aunque rara vez una buena idea. Los números, booleanos y null no son nombres válidos; { 42: "x" } es inválido porque 42 es un token numérico, no una cadena. Si necesitas una clave numérica, ponla entre comillas: { "42": "x" }.
Las Cadenas Deben Ir Entre Comillas Dobles (U+0022)
Una cadena JSON — se use como nombre o como valor — debe comenzar y terminar con una comilla doble, el carácter " en el punto de código Unicode U+0022. No se permite ningún otro delimitador. Las comillas simples (', U+0027), los acentos graves y las diversas comillas tipográficas "curvas" no son delimitadores de cadena en JSON. Esta única regla elimina toda una familia de errores de sintaxis en cuanto la interiorizas.
Válido:
{ "message": "hola mundo" }
Inválido — comillas simples alrededor del valor:
{ "message": 'hola mundo' }
Inválido — comillas tipográficas curvas, que a menudo se cuelan al copiar texto desde un procesador de textos:
{ "message": "hola mundo" }
Ciertos caracteres dentro de una cadena deben escaparse con una barra invertida. Una comilla doble literal dentro de la cadena se escribe como \", y una barra invertida como \\. Los caracteres de control — puntos de código de U+0000 a U+001F — no deben aparecer literalmente en una cadena; se escriben mediante secuencias de escape en su lugar. Los escapes con nombre habituales son \n (salto de línea), \t (tabulador), \r (retorno de carro), \b (retroceso), \f (avance de página) y \/ (un escape opcional para la barra diagonal). Cualquier carácter Unicode también puede escribirse con un escape \u seguido de cuatro dígitos hexadecimales, por ejemplo é para la letra e con acento agudo.
Aquí un valor contiene legítimamente una comilla y un salto de línea, ambos escapados:
{ "quote": "Dijo \"hola\"", "line": "primera\nsegunda" }
Escribir un salto de línea o un tabulador real y sin escapar dentro de las comillas haría el documento inválido. Por eso los editores a veces informan de un "token inesperado" a mitad de una cadena larga — un carácter de control sin escapar la rompió.
Los Seis Caracteres Estructurales
La RFC 8259 identifica exactamente seis caracteres estructurales que forman el esqueleto de cualquier documento JSON. Todo lo demás es un valor, un nombre o espacio en blanco insignificante. Los seis son:
{— begin-object (llave izquierda)}— end-object (llave derecha)[— begin-array (corchete izquierdo)]— end-array (corchete derecho):— name-separator (dos puntos), entre un nombre y su valor,— value-separator (coma), entre pares o elementos de un array
La especificación permite espacio en blanco insignificante antes o después de cualquiera de estos caracteres estructurales. Los caracteres de espacio permitidos son el espacio, el tabulador horizontal, el salto de línea y el retorno de carro. Por eso el JSON con formato bonito, con sangría y saltos de línea, es exactamente igual de válido que el JSON minificado en una sola línea — el espacio entre tokens no aporta significado. Sin embargo, el espacio en blanco no está permitido dentro de un token: no puedes poner un espacio en medio de la palabra clave true ni entre los dígitos de un número.
Sin Comas Finales, Sin Comentarios
Dos de las omisiones más célebres de JSON hacen tropezar constantemente a los recién llegados, y ambas son deliberadas.
Las comas finales no están permitidas. La coma es un separador entre pares, así que no debe haber nada después del último par antes de la llave de cierre. Una coma sin un par a continuación es un error de sintaxis.
Válido:
{
"a": 1,
"b": 2
}
Inválido — la coma tras 2 no tiene ningún par a continuación:
{
"a": 1,
"b": 2,
}
La misma regla aplica a los arrays: [1, 2, 3,] es inválido. Muchos lenguajes de programación toleran comas finales en sus propios literales, y precisamente por eso el error es tan fácil de arrastrar hasta JSON.
Los comentarios no están permitidos. No existe el comentario de línea // ni el comentario de bloque /* ... */ en JSON. La gramática no tiene ninguna producción para ellos, así que cualquier analizador que siga estrictamente la RFC 8259 rechazará un documento que contenga uno. Si necesitas anotar un documento JSON, la solución habitual es añadir un campo de cadena dedicado como { "_comment": "explicación aquí", "value": 1 }. Los formatos que superponen comentarios sobre JSON — como JSON5 o JSONC — son dialectos separados y no estándar; no son JSON según la RFC, y un validador estricto marcará sus comentarios.
Nombres Duplicados: Permitidos por la Gramática, pero de Comportamiento No Especificado
Este es uno de los rincones peor comprendidos del estándar. La RFC 8259 no prohíbe que un objeto tenga dos pares con el mismo nombre. Un documento como este es JSON sintácticamente válido:
{ "id": 1, "id": 2 }
Sin embargo, la RFC señala que los nombres dentro de un objeto deberían ser únicos, y afirma explícitamente que el comportamiento del software que recibe un objeto con nombres duplicados es impredecible. Algunos analizadores conservan la última aparición, otros la primera, otros recopilan todos los valores y otros lanzan un error. Como el resultado depende de la implementación, debes tratar los nombres duplicados como un bug aunque la gramática los tolere. Nunca dependas de ninguna resolución concreta de una clave duplicada — distintos sistemas dentro del mismo pipeline pueden resolverla de forma diferente y corromper datos en silencio. Cuando generes JSON, garantiza nombres únicos; cuando lo consumas, considera rechazar directamente los objetos con duplicados. Nuestro formateador JSON facilita detectar duplicados mientras inspeccionas un payload.
Ejemplos Trabajados: Válido vs Inválido de un Vistazo
Juntando las reglas, aquí tienes un objeto totalmente válido que ejercita estructuras anidadas, caracteres escapados y todos los tipos primitivos:
{
"id": 1001,
"name": "Pedido \"A\"",
"paid": false,
"discount": null,
"items": [
{ "sku": "X1", "qty": 2 },
{ "sku": "Y7", "qty": 1 }
],
"note": "linea uno\nlinea dos"
}
Y aquí un catálogo de las formas más comunes en que un objeto sale mal, cada una con una razón de una línea:
{ id: 1 }— el nombre no es una cadena entre comillas.{ "id": 1, }— coma final antes de la llave de cierre.{ "id": 1 // clave primaria— no se permiten comentarios.
}{ "id": '1' }— el valor usa comillas simples en vez de dobles.{ "id": 1 "name": "x" }— falta la coma entre pares.{ "id" 1 }— faltan los dos puntos entre nombre y valor.{ "id": 1 }}— llaves desbalanceadas.
Cómo Encajan Estas Reglas en el Trabajo Real con JSON
Entender la sintaxis de objetos a este nivel da frutos directos cuando construyes y depuras APIs. Los cuerpos de petición mal formados, los archivos de configuración sutilmente rotos y los payloads que un servidor estricto rechaza casi siempre se remontan a una de las reglas anteriores. Para un recorrido más amplio por convenciones que van más allá de la sintaxis pura — envoltorios de respuesta, nombres y formatos de error — consulta nuestra guía complementaria sobre buenas prácticas de JSON para el desarrollo de APIs. Y si estás eligiendo un formato para configuración editada por humanos donde los comentarios y las comas finales importan, nuestra comparación de YAML vs JSON explica cuándo la severidad de JSON es una ventaja y cuándo un formato más amable te sirve mejor.
Cuando necesites un esquema para forzar estructura más allá de la sintaxis — nombres obligatorios, tipos de valor y propiedades permitidas — valida los documentos contra un contrato con nuestras herramientas JSON. La validez sintáctica es solo la primera puerta; un documento puede ser JSON perfectamente válido y aun así estar equivocado para tu aplicación, que es donde toma el relevo la validación de esquema.
Valida Cada Regla con el Formateador JSON
Nuestro formateador y validador JSON es la forma más rápida de confirmar todo lo de esta guía. Pega un documento y da formato bonito al JSON válido, señala el carácter exacto donde falla el JSON inválido y resalta problemas estructurales como llaves desbalanceadas, comas faltantes y nombres sin comillas. Como se ejecuta enteramente en tu navegador, ningún dato sale nunca de tu máquina — seguro para pegar payloads y credenciales de producción. Prueba los ejemplos inválidos anteriores uno a uno: cada uno fallará precisamente en el carácter que la regla predice, convirtiendo estos requisitos abstractos en algo que puedes ver y recordar.