# JSON — Datos estructurados para programas, APIs y agentes de IA
> Guía práctica y completa sobre JSON: especificación de sintaxis, serialización con parse y stringify, consumo de APIs REST, validación con JSON Schema y salidas estructuradas para LLMs.
## 1. Qué es JSON y por qué se convirtió en el estándar de la industria
**JSON** (*JavaScript Object Notation*) es el estándar universal para el intercambio de datos estructurados entre servidores web, aplicaciones móviles, bases de datos y modernos agentes de inteligencia artificial.
Cuando los sistemas de software se comunican entre sí, intercambiar texto plano sin formato resulta frágil e ineficiente:
> *"Elena Kovalchuk, 29 años, Kiev, suscripción premium activa, habilidades: Python, SQL."*
Aunque un ser humano puede interpretar esa frase sin esfuerzo, un algoritmo requeriría una compleja lógica heurística para extraer cada entidad. En JSON, la misma información se expresa de forma determinista y estructurada:
```json
{
"id": 1042,
"name": "Elena Kovalchuk",
"age": 29,
"city": "Kiev",
"isPremium": true,
"skills": ["Python", "SQL"]
}
```
Cualquier parser en cualquier lenguaje moderno (JavaScript, Python, Go, Rust) puede acceder de inmediato a la clave `"city"` y obtener `"Kiev"` sin ambigüedades.
```mermaid
flowchart LR
A["Cliente UI
(React / App Móvil)"] -->|HTTP POST JSON| B["Servidor API REST
(Node.js / Python)"]
B -->|SQL / NoSQL JSONB| C["Base de datos
(PostgreSQL / MongoDB)"]
B -->|Structured Output JSON| D["LLM / Agente IA
(Claude / OpenAI)"]
```
### Por qué JSON es independiente del lenguaje
A pesar de incluir "JavaScript" en su nombre, JSON es un formato de texto completamente independiente del lenguaje de programación, formalizado en el estándar RFC 8259. Funciona como el medio de comunicación estándar entre sistemas operativos y microservicios mediante el tipo MIME `application/json`.
---
## 2. Anatomía de JSON: objetos, arrays y tipos de datos primitivos
Todo documento JSON está compuesto por dos estructuras contenedoras (objetos y arrays) y seis tipos de datos fundamentales.
### Objeto (JSON Object)
Un objeto es una colección no ordenada de pares `clave: valor` delimitada por llaves `{}`. Las claves deben ser siempre cadenas entre comillas dobles.
```json
{
"username": "alex_dev",
"email": "alex@example.com",
"role": "admin"
}
```
### Array (JSON Array)
Un array es una lista ordenada de valores delimitada por corchetes `[]`. Los elementos están indexados desde cero y pueden contener cualquier tipo de dato válido en JSON.
```json
{
"supportedLocales": ["uk", "en", "es", "de"],
"primeNumbers": [2, 3, 5, 7, 11]
}
```
### Tipos de valores permitidos
La especificación de JSON admite estrictamente seis tipos de valores primitivos y estructurados:
| Tipo de valor | Reglas de sintaxis y descripción | Ejemplo |
| :--- | :--- | :--- |
| **String** | Secuencia de caracteres Unicode delimitada por comillas dobles | `"¡Hola, Mundo!"` |
| **Number** | Entero o decimal en coma flotante (sin notación hexadecimal ni puntos finales) | `42`, `-12.5`, `1.5e3` |
| **Boolean** | Valor literal en minúsculas: `true` o `false` | `true`, `false` |
| **Null** | Literal que representa la ausencia intencional de valor | `null` |
| **Object** | Contenedor anidado de pares clave-valor | `{"nested": true}` |
| **Array** | Lista ordenada anidada de valores | `[1, 2, 3]` |
---
## 3. Reglas estrictas de sintaxis y errores comunes
La sintaxis de JSON es significativamente más estricta que la de JavaScript o Python. Una coma mal ubicada o unas comillas simples invalidan por completo todo el documento.
### Cinco reglas fundamentales de sintaxis
1. **Exclusividad de comillas dobles:** Tanto las claves como los valores de texto deben usar comillas dobles (`"texto"`). El uso de comillas simples (`'texto'`) genera un error de análisis sintáctico irrecuperable.
2. **Prohibición de comas finales (trailing commas):** Colocar una coma tras el último elemento de un objeto o array es un error de sintaxis estricto.
3. **Dos puntos para delimitación:** El carácter de dos puntos `:` es el único separador válido entre una clave y su valor.
4. **Cero comentarios permitidos:** JSON no admite comentarios `//` ni `/* */`. Cualquier metadato explicativo debe agregarse como una propiedad normal (por ejemplo, `"_comment": "Nota explicativa"`).
5. **Tipos no serializables en tiempo de ejecución:** JSON no puede representar directamente `undefined`, `NaN`, `Infinity`, funciones ni instancias de `Date`.
### Comparativa: JSON válido vs. JSON inválido
:::tabs
@tab JSON Válido
```json
{
"product": "MacBook Pro",
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple", "m-series"]
}
```
@tab JSON Inválido (Errores habituales)
```json
{
product: 'MacBook Pro', // Error: clave sin comillas y comillas simples
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple",], // Error: coma final en el array
} // Error: coma final antes de cerrar la llave
```
:::
---
## 4. Diferencias clave entre JSON y objetos de JavaScript
Es común confundir los objetos literales de JavaScript con JSON. Sin embargo, en la arquitectura de ejecución representan conceptos totalmente diferentes.
```mermaid
flowchart TD
subgraph Serialized_String["JSON (Flujo de texto serializado)"]
J["'{\"name\":\"Max\",\"age\":30}'"]
end
subgraph In_Memory_Structure["Objeto JavaScript (Estructura en memoria RAM)"]
O["{ name: 'Max', age: 30 }"]
end
J -->|JSON.parse| O
O -->|JSON.stringify| J
```
### Matriz de diferencias técnicas
| Característica | Objeto Literal en JavaScript | Especificación JSON |
| :--- | :--- | :--- |
| **Naturaleza** | Estructura de datos dinámica en memoria | Cadena de texto serializada |
| **Restricciones de claves** | Identificadores sin comillas, cadenas o Symbols | Exclusivamente cadenas entre comillas dobles |
| **Tipos soportados** | Funciones, `Date`, `Map`, `Set`, `undefined`, etc. | Exactamente 6 tipos (string, number, bool, null, obj, arr) |
| **Comentarios** | Totalmente permitidos (`//` y `/* */`) | Prohibidos |
| **Comas finales** | Permitidas en ECMAScript moderno | Prohibidas |
---
## 5. Navegación y consulta de estructuras de datos anidadas
En escenarios reales, las respuestas de las APIs presentan jerarquías profundas. El acceso a los valores requiere el uso de la notación de punto para objetos y corchetes con índice (`[]`) para arrays.
### Ejemplo de estructura anidada
```json
{
"orderId": "ORD-94821",
"customer": {
"fullName": "Taras Shevchenko",
"contacts": {
"email": "taras@example.org",
"phones": ["+380501112233", "+380679998877"]
}
},
"items": [
{ "id": 1, "title": "Monitor 4K", "price": 450, "qty": 1 },
{ "id": 2, "title": "Teclado mecánico", "price": 120, "qty": 2 }
]
}
```
### Rutas de acceso a los datos
- `order.orderId` $\rightarrow$ evalúa a `"ORD-94821"`
- `order.customer.fullName` $\rightarrow$ evalúa a `"Taras Shevchenko"`
- `order.customer.contacts.phones[0]` $\rightarrow$ evalúa a `"+380501112233"`
- `order.items[1].price` $\rightarrow$ evalúa a `120`
> [!TIP]
> En JavaScript y TypeScript moderno, utiliza siempre encadenamiento opcional (*optional chaining*) como `order?.customer?.contacts?.email` para evitar errores del tipo `TypeError: Cannot read properties of undefined`.
---
## 6. JSON en APIs REST: peticiones, respuestas y encabezados
La inmensa mayoría de los servicios web actuales utilizan JSON como formato de transporte de datos sobre el protocolo HTTP.
```mermaid
sequenceDiagram
autonumber
actor Cliente as Cliente (Navegador / App)
participant Servidor as Servidor API REST
Note over Cliente: Serialización de objeto a texto
Cliente->>Servidor: POST /api/users (Header: Content-Type: application/json)
Note over Servidor: Parseo JSON, validación y guardado en BD
Servidor-->>Cliente: 201 Created (Header: Content-Type: application/json)
Note over Cliente: Deserialización con response.json()
```
### Encabezados HTTP indispensables
1. **`Content-Type: application/json`:** Notifica al servidor o cliente que el cuerpo de la petición o respuesta contiene una carga útil en formato JSON serializado.
2. **`Accept: application/json`:** Informa al backend de que el cliente espera recibir la respuesta estrictamente en formato JSON (y no en XML o HTML).
---
## 7. Serialización y deserialización: parse y stringify
Convertir un objeto en memoria a una cadena de texto se denomina **Serialización**, mientras que reconstruir un objeto a partir de una cadena de texto es la **Deserialización**.
:::tabs
@tab JavaScript / TypeScript
```typescript
// 1. Deserialización (Texto -> Objeto)
const jsonString = '{"title":"Portátil","price":1200}';
const product = JSON.parse(jsonString);
console.log(product.title); // "Portátil"
// 2. Serialización (Objeto -> Texto)
const user = { name: "Danylo", active: true };
const serialized = JSON.stringify(user, null, 2); // Sangría de 2 espacios
```
@tab Python
```python
import json
# 1. Deserialización (Texto -> Diccionario)
raw_text = '{"title": "Portátil", "price": 1200}'
product = json.loads(raw_text)
print(product["title"])
# 2. Serialización (Diccionario -> Texto)
user_dict = {"name": "Danylo", "active": True}
json_string = json.dumps(user_dict, indent=2, ensure_ascii=False)
```
@tab Go
```go
package main
import (
"encoding/json"
"fmt"
)
type Product struct {
Title string `json:"title"`
Price int `json:"price"`
}
func main() {
raw := []byte(`{"title":"Portátil","price":1200}`)
var p Product
json.Unmarshal(raw, &p)
fmt.Println(p.Title)
}
```
:::
---
## 8. Diagnóstico de errores de sintaxis y validación
Cuando el texto de entrada contiene errores de sintaxis, la llamada a `JSON.parse()` lanza una excepción no controlada `SyntaxError` que puede interrumpir el flujo de ejecución si no se captura de forma segura.
```javascript
try {
const data = JSON.parse(untrustedUserInput);
} catch (error) {
console.error("Carga JSON inválida:", error.message);
}
```
### Lista rápida de diagnóstico
- [ ] ¿Están todas las llaves y corchetes abiertos correctamente cerrados con sus correspondientes `}` y `]`?
- [ ] ¿Están todas las claves y cadenas de texto delimitadas por comillas dobles `""`?
- [ ] ¿Se eliminaron todas las comas finales antes de los cierres `}` o `]`?
- [ ] ¿Se excluyeron valores incompatibles (`undefined`, `NaN`, comentarios)?
- [ ] ¿Están correctamente escapadas las comillas dobles internas: `"cita": "Palabra entre \"comillas\""`?
---
## 9. JSON Schema: cumplimiento de contratos y validación de datos
Un documento puede ser sintácticamente válido en JSON y, al mismo tiempo, incumplir los requisitos del dominio de la aplicación (por ejemplo, recibir una edad con valor `"veinte"` en vez de un número entero).
**JSON Schema** es el estándar internacional para describir y validar la estructura de los datos en JSON.
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "UserRegistrationSchema",
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"age": {
"type": "integer",
"minimum": 18
},
"roles": {
"type": "array",
"items": { "type": "string" },
"minItems": 1
}
},
"required": ["email", "age"]
}
```
Bibliotecas de validación como Ajv en Node.js o jsonschema en Python verifican automáticamente las cargas útiles contra este esquema antes de transferirlas a la lógica de negocio.
---
## 10. Salidas estructuradas para LLMs, llamadas a funciones y agentes de IA
En el desarrollo de agentes autónomos, las respuestas en texto no estructurado están siendo sustituidas por **Salidas Estructuradas (Structured Outputs)**.
Los agentes de IA (como Claude Code, OpenAI Function Calling o LangChain) se comunican con herramientas externas mediante parámetros expresados en JSON:
```json
{
"name": "sendEmailNotification",
"arguments": {
"recipient": "usuario@example.com",
"subject": "Factura generada",
"invoiceId": "INV-2026-09"
}
}
```
### Buenas prácticas para exigir JSON a modelos de lenguaje
1. **Definir esquemas explícitos:** Proporciona una interfaz de TypeScript o un JSON Schema estricto en el prompt del sistema.
2. **Exigir salida limpia:** Indica al modelo: *"Devuelve ÚNICAMENTE un objeto JSON válido y sin bloques markdown ni comentarios explicativos adicionales."*
3. **Aprovechar modos estructurados nativos:** Utiliza las funcionalidades a nivel de API del proveedor (como Anthropic Tool Use u OpenAI Structured Outputs) para forzar gramáticas estrictas por tokens.
---
## 11. Comparación de formatos: JSON vs. YAML vs. XML vs. TOML
| Formato | Legibilidad humana | Soporte de comentarios | Sobrecarga sintáctica | Caso de uso principal en la industria |
| :--- | :--- | :--- | :--- | :--- |
| **JSON** | Media / Alta | No | Mínima | APIs web, transporte cliente-servidor, tool calling en IA |
| **YAML** | Muy alta | Sí | Nula (basado en indentación) | Pipelines CI/CD (GitHub Actions, manifiestos de Kubernetes) |
| **TOML** | Muy alta | Sí | Baja | Configuración de aplicaciones (Cargo, pyproject.toml) |
| **XML** | Baja | Sí | Alta (etiquetas verbosas) | Servicios empresariales heredados, SOAP, gráficos SVG |
---
## 12. Taller práctico, autoevaluación y lista de verificación final
Consolida lo aprendido revisando un ciclo completo de consulta, parseo y lectura de datos desde una API.
### Flujo integral de consulta y consumo de datos
```typescript
// Consulta de datos de usuario mediante la Fetch API nativa
async function fetchUserProfile(userId: number) {
try {
const response = await fetch(`https://api.example.com/users/${userId}`, {
headers: { Accept: "application/json" }
});
if (!response.ok) {
throw new Error(`Error HTTP: ${response.status}`);
}
// Deserialización automática a objeto JavaScript
const user = await response.json();
// Lectura segura de propiedades con valores por defecto
console.log(`Usuario: ${user.name}`);
console.log(`Habilidad principal: ${user.skills?.[0] ?? 'ninguna'}`);
return user;
} catch (err) {
console.error("Fallo al recuperar el perfil de usuario:", err);
}
}
```
### Preguntas de repaso
> **1. ¿Qué error se produce al usar comillas simples para delimitar cadenas en un archivo JSON?**
>
> > [!TIP]
> > **Respuesta:** Se produce un error de análisis (`SyntaxError: Unexpected token ' in JSON`). La especificación oficial de JSON exige estrictamente comillas dobles `""`.
> **2. ¿Por qué están prohibidas las comas finales tras el último elemento de un objeto o array?**
>
> > [!TIP]
> > **Respuesta:** La especificación RFC 8259 lo prohíbe taxativamente. El parser espera encontrar otro elemento tras una coma; al toparse inmediatamente con una llave o corchete de cierre (`}` o `]`), falla.
> **3. ¿Qué función cumple JSON Schema en arquitecturas de servicios distribuidos?**
>
> > [!TIP]
> > **Respuesta:** Garantiza el cumplimiento de contratos de datos y tipos a nivel de negocio (campos obligatorios, rangos numéricos, formatos de email), asegurando que la carga sea no solo válida sintácticamente, sino también coherente con las reglas del sistema.
### Lista de verificación para producción
- [ ] Todas las claves y valores de texto están delimitados por comillas dobles `""`.
- [ ] Se comprobó que no existen comas finales antes de un cierre `}` o `]`.
- [ ] Se eliminaron todos los comentarios del documento.
- [ ] Se configuraron los encabezados `Content-Type: application/json` y `Accept: application/json`.
- [ ] Se protegieron las invocaciones a `JSON.parse()` mediante bloques defensivos `try/catch`.
- [ ] Se aplicaron contratos de validación mediante `JSON Schema` para cargas críticas en APIs y agentes de IA.