Skip to content

JSON Hoja de referencia

Formato ligero de intercambio de datos para el intercambio de información.

01

Primeros pasos

Estructura básica

JSON soporta 6 tipos de datos: cadena, número, booleano, null, array y objeto. Las claves deben ser cadenas entre comillas dobles. JSON es independiente del lenguaje y fácil de leer para humanos y máquinas.

json
{
  "name": "Alice",
  "age": 30,
  "isStudent": false,
  "height": 1.65,
  "nullValue": null,
  "hobbies": ["reading", "coding", "music"],
  "address": {
    "city": "NYC",
    "zip": "10001"
  }
}

Reglas de sintaxis JSON

JSON tiene una sintaxis estricta: las claves y las cadenas usan solo comillas dobles, las comas separan elementos y las comas finales están prohibidas. El documento entero debe ser un único valor JSON. El JSON estándar no tiene comentarios—usa un preprocesador o JSON5 si los necesitas.

json
{
  "key": "value",          // key MUST be a double-quoted string
  "nested": { "a": 1 },    // objects use { } with comma-separated pairs
  "list": [1, 2, 3]        // arrays use [ ] with comma-separated values
}

// Rules:
// - Double quotes only for strings and keys (no single quotes)
// - Comma separates members; NO trailing comma
// - The whole document is ONE value (usually an object or array)
// - No comments allowed in standard JSON

Comentarios en JSON

El JSON estándar prohíbe los comentarios. Alternativas comunes: añadir un campo '_comment' (ignorado por el código), usar JSONC/JSON5 (soportados por VS Code y muchas herramientas), o eliminar los comentarios antes de parsear con una librería como comment-json o JSON.minify.

json
// Standard JSON does NOT allow comments.

// Workaround 1: include a descriptive field
{
  "_comment": "This is a config file for the app",
  "port": 8080
}

// Workaround 2: use JSON5 or JSONC (VS Code settings)
{
  // line comment
  "port": 8080 /* block comment */
}

// Workaround 3: strip comments before parsing
// (e.g., JSON.minify, comment-json npm package)

Espacios en blanco y formato

Los espacios en blanco fuera de las cadenas son insignificantes—las formas compacta y embellecida parsean al mismo valor. El JSON compacto ahorra ancho de banda; el embellecido (sangría de 2 espacios es lo común) ayuda a la legibilidad y a los diffs. La mayoría de serializadores ofrecen una opción 'pretty'.

json
// These are all equivalent:

{"a":1,"b":2}                       // compact (no whitespace)

{ "a": 1, "b": 2 }                  // readable

{
  "a": 1,
  "b": 2
}                                   // pretty-printed

// Whitespace between tokens is insignificant.
// Use compact for transmission, pretty for humans.

Extensión de archivo y tipo MIME

La extensión de archivo estándar es .json y el tipo MIME es application/json. Variantes como JSONC, JSON5, GeoJSON y NDJSON tienen sus propias convenciones. Usa siempre la codificación UTF-8; el BOM está desaconsejado.

json
// File extensions:
//   .json    standard JSON
//   .jsonc   JSON with comments (VS Code, TypeScript config)
//   .json5   JSON5 (relaxed syntax)
//   .geojson GeoJSON (geographic data)
//   .ndjson  Newline-Delimited JSON (JSON Lines)
//   .har     HTTP Archive (JSON-based)

// MIME type:
Content-Type: application/json

// Older/alternate MIME types (avoid):
//   text/json          (non-standard)
//   application/x-json (non-standard)

// UTF-8 is the default and recommended encoding.

Categorías de valores JSON

Los valores JSON caen en seis tipos: cadena, número, booleano, null, array y objeto. Los arrays y objetos son estructurados (pueden contener otros valores); el resto son primitivos. Un documento JSON válido es un valor—comúnmente un objeto o array, pero un número o cadena suelto también es válido.

json
// A JSON value is exactly one of these six types:

"hello"                 // string
42                      // number
3.14                    // number
true                    // boolean
false                   // boolean
null                    // null
[1, 2, 3]               // array
{ "a": 1 }              // object

// Structured types: array, object
// Primitive types: string, number, boolean, null
// A standalone JSON document is a single value of any type.
02

Tipos de datos

Tipo cadena

Las cadenas JSON son texto Unicode entre comillas dobles. Secuencias de escape comunes: \" (comilla), \\ (barra invertida), \/ (barra), \n, \t, \r, \b, \f, y \uXXXX para cualquier punto de código Unicode. Las comillas simples no están permitidas como delimitadores de cadena.

json
{
  "single": "double quotes only",
  "empty": "",
  "escaped": "He said \"hi\" and C:\\Users",
  "unicode": "Cafu00e9 \u00e9 \u1F600",
  "multiline": "line1\nline2\ttabbed"
}

// Strings MUST use double quotes.
// Single quotes are NOT valid in JSON.

Tipo número

Los números JSON siguen un subconjunto del doble de precisión IEEE 754: enteros, decimales y notación científica (por ejemplo, 6.022e23). Los ceros a la izquierda están prohibidos (007 es inválido). NaN, Infinity y -Infinity NO son válidos—codifícalos como null o cadenas si hace falta.

json
{
  "integer": 42,
  "negative": -7,
  "float": 3.14,
  "zero": 0,
  "scientific": 6.022e23,
  "small": 1.5e-10
}

// Numbers are NOT quoted.
// No leading zeros (007 is invalid).
// No NaN, Infinity, or -Infinity (not valid JSON).

Tipo booleano

Los booleanos JSON son las palabras clave literales true y false (en minúsculas, sin comillas). Los 'true'/'false' entre comillas son cadenas. JSON no tiene concepto de 0/1 o sí/no como booleanos—conviértelos en el código de tu aplicación.

json
{
  "enabled": true,
  "disabled": false,
  "flag": true
}

// Booleans are the bare keywords true and false.
// They are NOT quoted ("true" is a string).
// 0/1, yes/no, on/off are NOT booleans in JSON.

Tipo null

El null de JSON es la palabra clave suelta null (sin comillas). Señala la ausencia intencional de un valor. Ten en cuenta que null es distinto de una cadena vacía '', 0, false o una clave ausente. Muchos lenguajes mapean null a None/nil/null.

json
{
  "middleName": null,
  "deletedAt": null,
  "optional": null
}

// null is a bare keyword (unquoted).
// "null" (quoted) is a string, not null.
// null represents the intentional absence of value.

Tipo array

Los arrays JSON son listas ordenadas envueltas en [ ], separadas por comas, con índice desde cero. Pueden contener cualquier valor JSON, incluidos tipos mezclados y arrays/objetos anidados. Los arrays vacíos [] son válidos. El orden se conserva y es significativo.

json
{
  "numbers": [1, 2, 3],
  "mixed": [1, "two", true, null],
  "nested": [[1, 2], [3, 4]],
  "objects": [
    { "id": 1 },
    { "id": 2 }
  ],
  "empty": []
}

// Arrays are ordered, zero-indexed, and can hold mixed types.

Tipo objeto

Los objetos JSON son colecciones de clave/valor sin orden envueltas en { }. Las claves deben ser cadenas únicas entre comillas dobles; los valores pueden ser de cualquier tipo JSON. Aunque los objetos son conceptualmente sin orden, la mayoría de parsers conservan el orden de inserción; no dependas del orden para la corrección.

json
{
  "user": {
    "id": 1,
    "name": "Alice",
    "roles": ["admin", "user"],
    "active": true
  },
  "empty": {}
}

// Objects are unordered collections of key/value pairs.
// Keys MUST be unique strings (double-quoted).
// Values can be any JSON type.
03

Cadenas

Fundamentos de cadenas

Las cadenas JSON son secuencias de caracteres Unicode entre comillas dobles. La barra inclinada puede escaparse (\/) pero no es necesario—útil al incrustar JSON en etiquetas <script>. Las cadenas vacías son válidas.

json
{
  "name": "Alice",
  "email": "[email protected]",
  "url": "https://example.com/path?q=1",
  "path": "C:\\Users\\alice",
  "empty": ""
}

// Strings are double-quoted Unicode text.
// Forward slash may be escaped as \/ but does not have to be.

Secuencias de escape

JSON soporta estos escapes: \" (comilla), \\ (barra invertida), \/ (barra), \b (retroceso), \f (salto de página), \n (salto de línea), \r (retorno de carro), \t (tabulación) y \uXXXX (punto de código Unicode). Cualquier otra secuencia con barra invertida es inválida.

json
{
  "quote": "She said \"hello\"",
  "backslash": "C:\\Users\\name",
  "newline": "line1\nline2",
  "tab": "col1\tcol2",
  "carriage": "a\rb",
  "backspace": "a\bb",
  "formfeed": "a\fb",
  "slash": "a\/b"
}

// Valid escapes: \" \\ \/ \b \f \n \r \t \uXXXX

Caracteres Unicode

Usa \uXXXX para cualquier punto de código Unicode. Los caracteres por encima de U+FFFF (como muchos emojis) exigen un par sustituto: dos escapes \u. Los parsers modernos también aceptan el carácter UTF-8 crudo directamente en la cadena—\uXXXX sirve especialmente por seguridad o cuando no puedes teclear el carácter.

json
{
  "eacute": "Caf\u00e9",
  "euro": "Price: \u20ac10",
  "emoji": "Smile \ud83d\ude00",
  "chinese": "\u4f60\u597d",
  "raw": "Cafu00e9 u00e9 \u00e9"
}

// \uXXXX encodes a code point in the Basic Multilingual Plane.
// Surrogate pairs (two \u escapes) encode characters above U+FFFF.
// Modern parsers also accept the raw UTF-8 character directly.

Caracteres especiales en cadenas

Dentro de las cadenas JSON, la comilla doble y la barra invertida deben escaparse siempre (\" y \\). Los demás caracteres especiales (HTML, SQL, regex) siguen sus propias reglas, pero JSON solo exige escapar \" y \\ (más los caracteres de control). Una barra invertida literal se escribe como \\.

json
{
  "html": "<div class=\"x\">Hi</div>",
  "sql": "SELECT * FROM t WHERE name='O''Brien'",
  "regex": "^\\d{3}-\\d{4}$",
  "json": "{ \"k\": \"v\" }",
  "cmd": "echo \"hello\""
}

// Backslash is the universal escape character.
// To include a literal backslash, write \\.

Cadenas multilínea (solución)

Las cadenas JSON no pueden contener saltos de línea literales—debes escaparlos como \n. Para contenido multilínea, incrusta \n en la cadena, usa un array de cadenas por línea, o pásate a un formato como YAML o JSON5 que soporta cadenas multilínea. Los saltos de línea literales sin escapar son un error de sintaxis.

json
// JSON does NOT support real multi-line strings.
// The following is INVALID:
// { "text": "line1
// line2" }

// Workaround 1: escape the newline
{ "text": "line1\nline2" }

// Workaround 2: array of lines
{ "lines": ["line1", "line2"] }

// Workaround 3: JSON5 allows continued strings (still single logical line)

Trampas comunes con cadenas

Errores comunes con cadenas: usar comillas simples, dejar comas finales, olvidar escapar las comillas dobles internas, e incrustar caracteres de control literales (tabulación/salto de línea) en lugar de sus escapes \t/\n. Un parser estricto rechaza cada uno de estos.

json
// WRONG: single quotes
// { 'name': 'Alice' }

// WRONG: trailing comma
// { "a": 1, }

// WRONG: unescaped quote
// { "msg": "He said "hi"" }

// WRONG: literal tab/newline in string
// { "x": "a<TAB>b" }

// RIGHT:
{ "name": "Alice", "msg": "He said \"hi\"" }
04

Números

Entero y flotante

JSON tiene un único tipo de número que cubre enteros y valores de punto flotante. No hay un tipo entero separado a nivel de sintaxis—los enlaces de lenguaje pueden mapear enteros grandes a int, long, float o decimal según el valor y la librería.

json
{
  "count": 100,
  "negative": -42,
  "temperature": -273.15,
  "pi": 3.14159,
  "zero": 0,
  "negativeZero": -0
}

// Integers and floats use the same number type.
// JSON does not distinguish int from float at the syntax level.

Notación científica

JSON soporta la notación científica: una mantisa seguida de e o E y un exponente con signo opcional (6.022e23 = 6.022 * 10^23). Se aceptan tanto e como E. Es esencial para números muy grandes o muy pequeños en datos científicos.

json
{
  "avogadro": 6.022e23,
  "planck": 6.626e-34,
  "speedOfLight": 2.998e8,
  "small": 1.5E-10
}

// e or E is allowed (case-insensitive).
// 6.022e23 means 6.022 * 10^23.
// The exponent may be negative.

Precisión de números

Los números JSON se parsean típicamente como dobles IEEE 754, así que los enteros por encima de 2^53-1 (9007199254740991) pierden precisión en JavaScript. Los valores decimales como 0.1 no pueden representarse exactamente. Para dinero o enteros de precisión arbitraria, codifícalos como cadenas y usa un tipo Decimal/BigInteger en tu código.

json
{
  "big": 9007199254740993,
  "decimal": 0.1,
  "sum": 0.1,
  "money": 19.99
}

// JavaScript stores numbers as IEEE 754 doubles.
// Integers are safe up to 2^53 - 1 (9007199254740991).
// 0.1 + 0.2 === 0.30000000000000004 (float precision loss).

// For money or big integers, parse as string or use a Decimal type.

Valores especiales (no permitidos)

El JSON estándar no permite NaN, Infinity ni -Infinity. Soluciones: usa null para NaN, codifica Infinity como cadena, o usa un valor centinela finito. Algunos serializadores (el json de Python por defecto, JSON5) los emiten como extensiones, pero la salida no es estándar y puede ser rechazada por parsers estrictos.

json
// NaN, Infinity, and -Infinity are NOT valid JSON.

// INVALID:
// { "x": NaN }
// { "y": Infinity }
// { "z": -Infinity }

// Common workarounds:
{
  "x": null,           // represent NaN/null
  "y": "Infinity",     // encode as a string
  "z": 1.7976931348623157e308  // use a finite max
}

// Many serializers (e.g., Python json) accept these as extensions
// but the output is not standard JSON.

Formatos de números

Números JSON válidos: menos opcional, parte entera (sin ceros a la izquierda salvo para 0), parte decimal opcional, exponente opcional. El hexadecimal (0x), el binario (0b), el octal, los guiones bajos, el + inicial, los ceros a la izquierda y un punto sin dígitos a ambos lados son inválidos sin excepción.

json
// VALID JSON numbers:
42
-7
0
3.14
-0.5
6.022e23
1.5E-10
100.00

// INVALID:
007        // leading zero
.5         // no leading digit
5.         // no trailing digit after dot
+5         // leading plus sign
0x1F       // hex
0b101      // binary
1_000      // underscores

Números grandes y BigInt

Para valores por encima de 2^53-1 (por ejemplo, IDs snowflake de Twitter, enteros de 64 bits, saldos grandes), codifícalos como cadenas para evitar la pérdida de precisión. Si debes usar un reviver en JSON.parse para convertir números a BigInt, recuerda que BigInt no puede re-serializarse por JSON.stringify sin un replacer—las cadenas son más seguras en el cable.

json
{
  "snowflake": "1234567890123456789",
  "timestamp": 1696000000000,
  "balance": "99999999999999999999"
}

// Numbers above 2^53-1 lose precision in JS.
// Use STRINGS for IDs, snowflakes, and big integers.

// In JavaScript, parse with a reviver:
// JSON.parse(str, (k, v) =>
//   typeof v === "number" && v > Number.MAX_SAFE_INTEGER
//     ? BigInt(v) : v);  // careful: BigInt can't be in JSON.stringify

// Better: keep them as strings on the wire.
05

Booleanos y null

Valores booleanos

Los booleanos JSON son las palabras clave sueltas true y false. Los 'true'/'false' entre comillas son cadenas. JSON no tiene concepto de truthy/falsy a nivel de sintaxis—1, 0, yes, no, on, off son cadenas o números, no booleanos. Conviértelos en el código de la aplicación.

json
{
  "enabled": true,
  "disabled": false,
  "isPublic": true,
  "isActive": false
}

// Only two boolean values: true and false (lowercase, unquoted).
// "true" (quoted) is a STRING, not a boolean.
// 1/0, yes/no, on/off are NOT booleans.

Significado de null

El null de JSON señala la ausencia intencional de un valor. Es distinto de una clave ausente (la clave no está en el objeto), una cadena vacía '', 0, false o una colección vacía. Usa null cuando el campo existe pero no tiene valor; omite la clave cuando el campo en sí no aplica.

json
{
  "middleName": null,
  "deletedAt": null,
  "parent": null,
  "optional": null
}

// null means "no value" or "intentionally absent".
// Distinct from:
//   - missing key (key not present at all)
//   - empty string ""
//   - 0 or false
//   - empty array [] or object {}

Null vs vacío vs ausente

Tres estados distintos: una clave con valor vacío (""), una clave explícitamente null y una clave ausente. En JavaScript, undefined significa que la clave está ausente mientras que null significa que está presente pero sin valor. Las APIs deberían documentar qué convención usan para los campos opcionales.

json
{
  "name": "Alice",
  "nickname": "",          // empty string (present, empty)
  "middleName": null,      // explicit null (present, no value)
  // "maidenName"           // missing (key not in object)
}

// In JavaScript:
//   obj.nickname === ""           // true
//   obj.middleName === null       // true
//   obj.maidenName === undefined  // true (key absent)
//   "maidenName" in obj           // false

// Choose deliberately: null vs "" vs missing.

Usar booleanos en condiciones

Al consumir booleanos JSON, prefiere la comparación estricta (=== true) a las comprobaciones truthy si necesitas distinguir false de ausente. En las respuestas de la API, incluye siempre los campos booleanos incluso cuando sean false—omitirlos obliga a los clientes a adivinar el valor por defecto.

json
{
  "isAdmin": true,
  "canEdit": false,
  "active": true
}

// In application code (JavaScript):
// if (user.isAdmin) { ... }       // truthy check
// const canEdit = user.canEdit === true;  // strict boolean check

// Be careful: a missing 'canEdit' key is undefined (falsy),
// but explicit false is also falsy. Distinguish if needed.

// API design: always send the boolean, even when false.

Trampas comunes

Trampas comunes: entrecomillar true/false/null los convierte en cadenas; usar True/TRUE/None (Python) o true/false con mayúsculas incorrectas es inválido; JSON no tiene undefined (solo null). Las únicas formas válidas son las palabras clave en minúsculas sin comillas true, false y null.

json
// Pitfall 1: quoting booleans/null
// { "x": "true" }   -> x is a STRING, not a boolean
// { "y": "null" }   -> y is a STRING, not null

// Pitfall 2: wrong case
// { "x": True }     -> INVALID (Python-style, not JSON)
// { "x": TRUE }     -> INVALID
// { "x": None }     -> INVALID

// Pitfall 3: confusing null with undefined
//   null exists in JSON; undefined does NOT.

// Correct:
{ "x": true, "y": null }
06

Arrays

Fundamentos de arrays

Los arrays JSON son listas ordenadas, con índice desde cero, envueltas en [ ], con valores separados por comas. Los arrays vacíos y los de un solo elemento son válidos. El orden es significativo y lo conservan los parsers. No se permite coma final.

json
{
  "numbers": [1, 2, 3, 4, 5],
  "strings": ["a", "b", "c"],
  "booleans": [true, false, true],
  "empty": [],
  "single": [42]
}

// Arrays are ordered, zero-indexed lists in [ ].
// Elements are separated by commas (no trailing comma).
// Empty arrays [] and single-element arrays are valid.

Arrays de tipos mezclados

Los arrays JSON pueden contener legalmente tipos mezclados ([1, 'two', true, null]). Es válido pero a menudo indica un diseño de esquema débil. Los arrays homogéneos (solo cadenas, solo objetos) son más fáciles de validar, documentar y consumir. Usa un esquema para imponer los tipos de elemento.

json
{
  "mixed": [1, "two", true, null, 3.14],
  "nested": [[1, 2], "x", { "a": 1 }]
}

// JSON arrays CAN hold values of different types.
// This is valid but often a sign of weak schema design.
// Prefer homogeneous arrays for clarity and validation.

Arrays anidados

Los arrays pueden anidarse a cualquier profundidad, útil para matrices, cuadrículas y estructuras de árbol. JSON no impone que los arrays anidados tengan la misma longitud (un array 'dentado' es válido). Si necesitas una matriz rectangular, imponla con un esquema o código de aplicación.

json
{
  "matrix": [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
  ],
  "ragged": [[1, 2], [3, 4, 5], [6]]
}

// Arrays can nest arbitrarily deep.
// JSON does not enforce rectangular shape—use a schema if needed.

Array de objetos

Un array de objetos es el patrón más común para listas de registros (usuarios, productos, publicaciones). Cada elemento típicamente tiene la misma forma, pero JSON no lo impone—usa un esquema (los 'items' de JSON Schema) para validar que cada elemento cumpla.

json
{
  "users": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" },
    { "id": 3, "name": "Carol" }
  ],
  "empty": []
}

// A very common pattern: a list of records.
// Each element is an object with the same shape.

Arrays vacíos y de un elemento

Los arrays vacíos [] y los de un elemento son válidos. En el diseño de APIs, distingue [] (presente, lista vacía) de null (presente, sin lista) y de una clave ausente (campo no aplicable). Devolver [] para 'sin ítems' suele ser más amigable que null.

json
{
  "empty": [],
  "single": [42],
  "tags": [],
  "items": ["one"]
}

// Both forms are valid.
// Distinguish [] from null and from a missing key:
//   "tags": []      -> present, empty list
//   "tags": null    -> present, no list
//   // (no tags)    -> missing key

Acceso a arrays en código

Tras el parseo, los arrays JSON se convierten en arrays/listas nativas de tu lenguaje (Array de JS, list de Python, List de Java, etc.). Usa el acceso por índice estándar, la longitud y la iteración. Los límites y la seguridad de tipos son tu responsabilidad—JSON en sí no impone los tipos de elemento.

json
{
  "list": ["a", "b", "c"]
}

// JavaScript:
//   const arr = JSON.parse(json).list;
//   arr[0]            // "a"
//   arr.length        // 3
//   arr.includes("b") // true
//   arr.map(x => x.toUpperCase())  // ["A", "B", "C"]

// Python:
//   data = json.loads(json_str)
//   data["list"][0]   # "a"
//   len(data["list"]) # 3
07

Objetos

Fundamentos de objetos

Los objetos JSON son colecciones de pares clave/valor sin orden envueltas en { }. Las claves deben ser cadenas entre comillas dobles; los valores pueden ser de cualquier tipo JSON. Los pares van separados por comas sin coma final. Los objetos son la estructura JSON de nivel superior más común.

json
{
  "id": 1,
  "name": "Alice",
  "email": "[email protected]",
  "active": true
}

// Objects are unordered { } collections of key/value pairs.
// Keys MUST be double-quoted strings.
// Pairs are comma-separated (no trailing comma).

Reglas de nombrado de claves

Las claves JSON pueden ser cualquier cadena entre comillas dobles, incluidas vacías, con espacios, puntos o dígitos. Sin embargo, por claridad en la API, prefiere un camelCase, snake_case o kebab-case consistente. Evita espacios, puntos (conflicto con la sintaxis de ruta) y claves vacías en APIs públicas.

json
{
  "simple": "ok",
  "with-dash": "ok",
  "with_underscore": "ok",
  "with.dot": "ok",
  "with space": "ok (but avoid)",
  "123numeric": "ok (but avoid)",
  "": "empty key is valid"
}

// Keys are arbitrary strings (double-quoted).
// Convention: use camelCase, snake_case, or kebab-case consistently.
// Avoid empty keys and keys with spaces/dots in APIs.

Objetos anidados

Los objetos pueden anidarse a cualquier profundidad, útil para datos jerárquicos. El anidamiento profundo es válido pero puede perjudicar la legibilidad y aumentar el acoplamiento. Para APIs públicas, prefiere una estructura más plana o usa referencias (IDs) en lugar de árboles profundamente anidados.

json
{
  "user": {
    "name": "Alice",
    "address": {
      "street": "123 Main St",
      "city": "NYC",
      "geo": { "lat": 40.7, "lng": -74.0 }
    }
  }
}

// Objects can nest arbitrarily deep.
// Deep nesting is valid but can hurt readability—flatten when sensible.

Objeto con arrays

Combinar objetos (para campos con clave) y arrays (para listas ordenadas) modela casi cualquier dato del mundo real. Un patrón común es un objeto que envuelve arrays de objetos anidados (un usuario con pedidos). Usa un esquema para documentar y validar la forma esperada.

json
{
  "user": {
    "name": "Alice",
    "roles": ["admin", "user"],
    "orders": [
      { "id": 1, "total": 19.99 },
      { "id": 2, "total": 5.99 }
    ]
  }
}

// Combining objects and arrays models most real-world data.

Orden de los miembros

La especificación JSON trata los objetos como sin orden. En la práctica, la mayoría de parsers modernos (V8 de JavaScript, Python 3.7+, LinkedHashMap de Java) conservan el orden de inserción, pero no deberías depender de esto para la corrección. Si el orden importa para el hasheo o la firma, ordena las claves explícitamente.

json
{
  "z": 1,
  "a": 2,
  "m": 3
}

// JSON objects are SPECIFIED as unordered.
// In practice, most parsers (JS, Python 3.7+) preserve insertion order.
// DO NOT rely on order for correctness—sort keys if order matters.

// Sorting keys (e.g., for stable hashing):
//   JSON.stringify(obj, Object.keys(obj).sort())

Claves duplicadas

La especificación JSON no prohíbe las claves duplicadas, pero su comportamiento no está definido—la mayoría de parsers conservan el último valor, algunos el primero. Las claves duplicadas son una fuente común de bugs sutiles. JSON Schema puede imponer uniqueKeys; los linters y parsers estrictos pueden rechazarlas.

json
// Technically valid JSON, but behavior is UNDEFINED:
{
  "name": "Alice",
  "name": "Bob"
}

// Most parsers keep the LAST value ("Bob"),
// but some keep the first. Avoid duplicate keys!

// JSON Schema (draft 2019-09+) has 'uniqueKeys' to forbid them.
// JSON.parse in JS keeps the last value (object property override).
08

Estructuras anidadas

Anidamiento profundo

JSON permite profundidad de anidamiento arbitraria, pero las estructuras muy profundas perjudican la legibilidad y pueden alcanzar los límites de los parsers (muchos imponen un tope de profundidad, por ejemplo, 1000, para prevenir denegaciones de servicio). Prefiere estructuras más planas con IDs/referencias para datos profundamente jerárquicos.

json
{
  "a": {
    "b": {
      "c": {
        "d": {
          "e": { "value": 42 }
        }
      }
    }
  }
}

// Nesting depth is theoretically unlimited.
// Many parsers impose a limit (e.g., 1000) to prevent DoS.
// Deep nesting hurts readability—consider flattening or references.

Ejemplo del mundo real

El JSON del mundo real mezcla objetos y arrays para modelar entidades y sus relaciones. Este ejemplo de pedido anida el cliente, los ítems (un array de objetos) y el envío. Usa un esquema para documentar la forma; mantén el anidamiento moderado por legibilidad.

json
{
  "order": {
    "id": "ord-123",
    "customer": {
      "id": "cus-1",
      "name": "Alice",
      "email": "[email protected]"
    },
    "items": [
      { "sku": "A1", "qty": 2, "price": 9.99 },
      { "sku": "B2", "qty": 1, "price": 19.99 }
    ],
    "shipping": {
      "address": { "city": "NYC", "zip": "10001" },
      "method": "express"
    },
    "total": 39.97
  }
}

Estructuras de árbol

Los árboles se modelan recursivamente: cada nodo tiene un valor y un array de nodos hijos. Este patrón aparece en sistemas de archivos, organigramas y ASTs. Cuidado con los ciclos—JSON no tiene sintaxis de referencias, así que los grafos cíclicos deben usar IDs o serializarse como lista plana con punteros al padre.

json
{
  "name": "root",
  "children": [
    {
      "name": "child-a",
      "children": [
        { "name": "grandchild-1", "children": [] },
        { "name": "grandchild-2", "children": [] }
      ]
    },
    { "name": "child-b", "children": [] }
  ]
}

// Recursive structures: a node contains an array of child nodes.

Acceder a valores anidados

Acceder a valores profundamente anidados arriesga TypeError/KeyError si faltan claves intermedias. Usa el encadenamiento opcional (JS ?. y ??) o el .get() encadenado (Python) con valores por defecto. Librerías como lodash.get o jq simplifican la extracción profunda y aportan valores por defecto.

json
{
  "user": { "address": { "city": "NYC" } }
}

// JavaScript (optional chaining):
//   const city = data?.user?.address?.city ?? "unknown";

// Python:
//   city = data.get("user", {}).get("address", {}).get("city", "unknown")

// Deep access without guards throws on missing keys.
// Use optional chaining or a helper like lodash.get.

Aplanar datos anidados

Aplanar objetos anidados (por ejemplo, 'user.name' en lugar de { user: { name } }) simplifica el acceso para variables de entorno, campos de formulario e indexación de búsqueda. La contrapartida es la pérdida de estructura y un viaje de ida y vuelta más difícil. Usa una librería (flat, lodash) para aplanar/desaplanar.

json
// Nested form:
{ "user": { "name": "Alice", "city": "NYC" } }

// Flattened form (dot notation):
{ "user.name": "Alice", "user.city": "NYC" }

// Flattened form (separate keys):
{ "userName": "Alice", "userCity": "NYC" }

// Use cases: environment variables, form fields, search indexing.
// Trade-off: simpler access vs. loss of structure.
09

JSON Schema

Fundamentos del esquema

JSON Schema es un vocabulario JSON para describir y validar documentos JSON. La raíz declara $schema (versión del draft) y type. Properties lista los campos con sus tipos; required lista las claves obligatorias. Validadores como Ajv (JS) o jsonschema (Python) comprueban el cumplimiento.

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/user.json",
  "title": "User",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

Validación de tipos

La palabra clave 'type' valida el tipo JSON de un valor: string, number, integer, boolean, null, array u object. Puede ser un único tipo o un array (por ejemplo, ['string', 'null'] para una cadena opcional nullable). 'integer' coincide con números sin parte decimal.

json
{
  "type": "object",
  "properties": {
    "name":   { "type": "string" },
    "age":    { "type": "integer" },
    "active": { "type": "boolean" },
    "score":  { "type": "number" },
    "tags":   { "type": "array", "items": { "type": "string" } },
    "meta":   { "type": "object" },
    "middle": { "type": ["string", "null"] }
  }
}

// 'type' can be a single type or an array of allowed types.

Restricciones de cadena

Restricciones de cadena: minLength, maxLength, pattern (regex), enum (valores permitidos) y format (pista semántica como 'email', 'uri', 'date-time', 'ipv4'). 'format' es solo anotación por defecto—los validadores deben optar por imponerla. Usa pattern para validación estricta por regex.

json
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 254
    },
    "username": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_]{3,20}$",
      "minLength": 3,
      "maxLength": 20
    },
    "bio": { "type": "string", "maxLength": 500 }
  }
}

// 'format' is a semantic hint (email, uri, date, ipv4).
// 'pattern' is a regular expression.

Restricciones numéricas

Restricciones numéricas: minimum, maximum (inclusivos), exclusiveMinimum, exclusiveMaximum y multipleOf. Para el tipo 'integer', los valores no deben tener parte decimal. Combina restricciones para modelar rangos (por ejemplo, una valoración de 1 a 5).

json
{
  "type": "object",
  "properties": {
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 },
    "price": { "type": "number", "minimum": 0, "exclusiveMinimum": 0 },
    "rating":{ "type": "integer", "minimum": 1, "maximum": 5 },
    "count": { "type": "integer", "multipleOf": 5 }
  }
}

// minimum/maximum are inclusive;
// exclusiveMinimum/exclusiveMaximum are exclusive.

Restricciones de objeto y array

Restricciones de array: items (esquema del elemento), minItems, maxItems, uniqueItems. Restricciones de objeto: required (claves obligatorias), properties (esquemas de campo), additionalProperties (false para prohibir claves extra, o un esquema para ellas), minProperties, maxProperties.

json
{
  "type": "object",
  "properties": {
    "id":   { "type": "integer" },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true
    }
  },
  "required": ["id"],
  "additionalProperties": false
}

// minItems/maxItems/uniqueItems constrain arrays.
// required lists mandatory keys; additionalProperties
// controls whether extra keys are allowed.

Validación avanzada

JSON Schema avanzado: oneOf/anyOf/allOf combinan subesquemas; $ref referencia definiciones reutilizables; if/then/else aplica validación condicional; const exige un valor exacto; enum lista los valores permitidos. Estos te permiten expresar restricciones ricas y tipos reutilizables.

json
{
  "oneOf": [
    { "type": "string" },
    { "type": "integer" }
  ],
  "definitions": {
    "address": {
      "type": "object",
      "properties": { "city": { "type": "string" } }
    }
  },
  "properties": {
    "home": { "$ref": "#/definitions/address" },
    "work": { "$ref": "#/definitions/address" }
  },
  "if":   { "properties": { "type": { "const": "vip" } } },
  "then": { "required": ["discount"] }
}

// oneOf/anyOf/allOf combine schemas.
// $ref reuses definitions; if/then/else is conditional.
10

JSONPath

Sintaxis JSONPath

JSONPath es un lenguaje de consulta para JSON, inspirado en XPath. '$' es la raíz, '.' selecciona un hijo, '[índice]' selecciona un elemento de array, '*' es un comodín y '..' es el descenso recursivo. Librerías como jsonpath-plus (JS) o jsonpath-ng (Python) lo implementan.

json
// JSONPath queries JSON like XPath queries XML.

// Sample data:
{
  "store": {
    "book": [
      { "category": "fiction", "price": 12.99 },
      { "category": "web",     "price": 29.99 }
    ]
  }
}

// Common JSONPath expressions:
$.store.book[0].category      // "fiction"
$.store.book[*].price         // [12.99, 29.99]
$..price                      // all prices anywhere
$.store..category             // all categories under store

Raíz e hijo

'$' referencia la raíz. '.' selecciona un hijo por nombre; '[]' es la alternativa de corchetes que maneja claves con puntos, espacios o comillas. '[índice]' selecciona un elemento del array (base 0); algunas implementaciones soportan índices negativos para contar desde el final.

json
// '$' = root object/array
// '.' or '[]' = child

$.user.name              // dot notation
$['user']['name']        // bracket notation (use for special chars)
$.users[0]               // first element of users array
$.users[-1]              // last element (some implementations)

// Use bracket notation when keys contain dots, spaces, or quotes:
$['user.name']
$['first name']

Descenso recursivo

'..' (descenso recursivo) coincide con una clave o elemento a cualquier profundidad. '$..price' devuelve cada valor 'price' sin importar dónde aparezca. '$..*' devuelve cada nodo. Esto es inestimable para buscar en JSON grande o profundamente anidado cuando no conoces la ruta exacta.

json
{
  "a": { "b": { "c": 1 }, "c": 2 }
}

// '..' searches at all depths:
$..c                      // [1, 2] (all 'c' keys anywhere)
$..a                      // all 'a' keys
$..*                      // every node (everything)

// Useful for finding a key without knowing the exact path:
$..price                  // every price, no matter how nested

Expresiones de filtro

Los filtros usan [?(expresión)] donde '@' se refiere al ítem actual. Los operadores soportados varían según la implementación pero típicamente incluyen ==, !=, <, <=, >, >=, && (and), || (or) y a veces =~ para regex. Funciones como length() y contains() añaden potencia.

json
// Filter with [?(expression)]:

$.store.book[?(@.price < 20)]            // books under 20
$.store.book[?(@.category == 'web')]     // web books
$.store.book[?(@.price < 30 && @.category == 'web')]

// '@' refers to the current item being filtered.
// Operators: == != < <= > >= && || =~ (regex in some impls)
// Functions: length(), contains(), matches()

Comodines

'*' es un comodín que coincide con cada hijo de un objeto o cada elemento de un array. '$.users[*].name' devuelve el 'name' de cada usuario. '$..*' devuelve cada nodo. Los resultados se devuelven como un array de coincidencias, incluso si solo hay una.

json
{
  "users": [
    { "name": "Alice", "age": 30 },
    { "name": "Bob",   "age": 25 }
  ]
}

// '*' matches all elements/children:
$.users[*]               // all user objects
$.users[*].name          // ["Alice", "Bob"]
$.users[0].*             // all values of first user: ["Alice", 30]
$..*                     // every node in the document

// Wildcards return arrays of matches.

Funciones comunes y ejemplos

Las funciones de JSONPath varían según la implementación: length(), min(), max(), avg(), sum(), contains() y matches() son comunes. Combina filtros y descenso recursivo para consultas potentes. Para la línea de comandos, jq es el estándar de facto y usa una sintaxis ligeramente distinta.

json
// length(): array length or string length
$.users.length()                    // number of users
$.store.book[?(@.title.length() > 10)]

// min(), max(), avg(), sum() (some implementations)
$.store.book..price.min()

// Realistic query: titles of cheap web books
$.store.book[?(@.price < 20 && @.category == 'web')].title

// Tools: jq (CLI), jsonpath-plus (JS), jsonpath-ng (Python),
//        Jayway (Java), GoJSONQ (Go)
11

JSON vs XML y YAML

Sintaxis JSON vs XML

JSON es más ligero (sin etiquetas de cierre, tipos nativos para números/booleanos/null) y se mapea directamente a las estructuras de datos de la mayoría de lenguajes. XML es más pesado pero más rico: atributos, espacios de nombres, contenido mezclado, esquemas (XSD) y transformaciones (XSLT). JSON domina las APIs web; XML persiste en entornos empresariales/SOAP.

json
// JSON:
{
  "name": "Alice",
  "age": 30,
  "hobbies": ["reading", "coding"]
}

<!-- XML: -->
<person>
  <name>Alice</name>
  <age>30</age>
  <hobbies>
    <hobby>reading</hobby>
    <hobby>coding</hobby>
  </hobbies>
</person>

// JSON: lighter, no closing tags, types (number/boolean/null).
// XML:  heavier, supports attributes, namespaces, mixed content.

Sintaxis JSON vs YAML

YAML usa sangría en lugar de llaves/comillas, soporta comentarios, cadenas multilínea y anclas/alias. JSON es más estricto (comillas obligatorias, sin comentarios) pero más rápido y ubicuo. YAML es un superconjunto de JSON—cada archivo JSON válido también es YAML válido.

json
# YAML:
name: Alice
age: 30
hobbies:
  - reading
  - coding

// JSON (equivalent):
{
  "name": "Alice",
  "age": 30,
  "hobbies": ["reading", "coding"]
}

// YAML: no quotes/braces, indentation-based, supports comments.
// JSON: stricter, faster to parse, ubiquitous in APIs.

Conversión de JSON a YAML

Convertir JSON a YAML es directo porque YAML es un superconjunto de JSON. El yaml.dump de Python y el js-yaml de Node lo manejan. El resultado usa sangría y sin comillas (mayormente). Los comentarios y las cadenas multilínea de YAML no sobreviven al viaje de ida y vuelta desde JSON (JSON no tiene ninguno).

json
// JSON input:
{ "name": "Alice", "roles": ["admin", "user"] }

// YAML output:
name: Alice
roles:
  - admin
  - user

// Python:
//   import yaml, json
//   yaml.dump(json.loads(json_str), sort_keys=False)

// Node.js:
//   const yaml = require('js-yaml');
//   yaml.dump(JSON.parse(jsonStr));

Conversión de YAML a JSON

Convertir YAML a JSON funciona para YAML simple pero pierde las características específicas de YAML: comentarios, anclas/alias, flujos multidocumento, tags y claves complejas. Usa yaml.safe_load para evitar la ejecución arbitraria de código por tags personalizados. El resultado es JSON estándar.

json
# YAML input:
server:
  host: localhost
  port: 8080
  debug: true

// JSON output:
{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true
  }
}

// Python:
//   import yaml, json
//   json.dumps(yaml.safe_load(yaml_str), indent=2)

// Watch for YAML-specific features: anchors, tags, multi-docs.

Diferencias de modelado de datos

JSON modela los datos como objetos y arrays—sin atributos ni espacios de nombres. XML añade atributos, espacios de nombres, contenido mezclado y esquemas ricos. YAML añade comentarios, anclas y soporte multidocumento. TOML apunta a archivos de configuración con tablas. Elige según necesidades: APIs (JSON), documentos (XML), configuración (YAML/TOML).

json
// JSON: objects and arrays, no attributes.
//   Attribute-style metadata needs a convention (e.g., @_prefix).

// XML: elements + attributes, namespaces, mixed content.
//   <book id="b1" category="web"><title>...</title></book>

// YAML: maps, sequences, scalars, anchors, multi-doc.
//   Supports comments and multi-line strings natively.

// TOML: tables + key/value, designed for config files.
//   Best for configuration; not ideal for nested data.

Cuándo usar cada formato

JSON para APIs web y almacenamiento NoSQL (universal, rápido). XML para servicios empresariales, datos centrados en documentos (SVG, XHTML) y esquemas ricos. YAML para configuración escrita por humanos (CI/CD, docker-compose) gracias a los comentarios y la legibilidad. TOML para archivos de configuración pequeños. Ajusta el formato al caso de uso.

json
// Use JSON when:
//   - building web/REST APIs (universal browser support)
//   - storing structured data (NoSQL databases)
//   - configuration with simple needs (package.json)

// Use XML when:
//   - enterprise/SOAP web services
//   - documents with mixed content (SVG, XHTML, DocBook)
//   - you need schemas, namespaces, or XSLT transforms

// Use YAML when:
//   - human-written config (CI/CD, docker-compose)
//   - you need comments and multi-line strings

// Use TOML when:
//   - small config files (Cargo, pyproject)
12

Parseo en JavaScript

JSON.parse

JSON.parse convierte una cadena JSON en un valor de JavaScript. Acepta cualquier valor JSON válido (objeto, array, cadena, número, booleano, null). El JSON inválido lanza un SyntaxError. Envuelve siempre JSON.parse en try/catch al manejar entrada no confiable.

json
// Parse a JSON string into a JavaScript value.
const json = '{"name":"Alice","age":30}';
const obj = JSON.parse(json);

console.log(obj.name); // "Alice"
console.log(obj.age);  // 30

// JSON.parse accepts a string only.
// Passing a number/boolean/object throws or coerces.
// JSON.parse("42")    === 42       (valid)
// JSON.parse("true")  === true     (valid)
// JSON.parse("null")  === null     (valid)
// JSON.parse(undefined) // throws SyntaxError

JSON.stringify

JSON.stringify convierte un valor de JavaScript en una cadena JSON. Las funciones, Symbols y undefined se omiten (en objetos) o se convierten en null (en arrays). BigInt lanza TypeError—conviértelo a cadena primero. Usa el tercer argumento (espacio) para el embellecido.

json
// Serialize a JavaScript value to a JSON string.
const obj = { name: "Alice", age: 30 };
const json = JSON.stringify(obj);
// '{"name":"Alice","age":30}'

// Pretty-print with 2-space indent:
JSON.stringify(obj, null, 2);
// {
//   "name": "Alice",
//   "age": 30
// }

// Functions, Symbols, and undefined are omitted.
// BigInt throws; use a replacer or String() first.

Función reviver

El reviver de JSON.parse transforma valores durante el parseo. Se llama de abajo hacia arriba por cada par clave/valor (incluida la raíz, con clave ''). Devuelve el valor transformado, o undefined para omitir la propiedad. Útil para parseo de fechas, BigInt y tipos personalizados.

json
// JSON.parse accepts a 'reviver' to transform values.
const json = '{"date":"2024-01-15","count":"42"}';

const obj = JSON.parse(json, (key, value) => {
  if (key === "date") return new Date(value);
  if (key === "count") return Number(value);
  return value;
});

// obj.date is a Date object; obj.count is a number.

// Reviver is called bottom-up for every key, including the root.

Función replacer

El replacer de JSON.stringify filtra o transforma valores durante la serialización. Como función, se llama por cada clave—devuelve undefined para omitir una propiedad. Como array, actúa como lista permitida de claves a incluir. Útil para censurar secretos y seleccionar campos.

json
// JSON.stringify accepts a 'replacer' to filter/transform.
const obj = { name: "Alice", password: "secret", age: 30 };

// Replacer as a function:
const safe = JSON.stringify(obj, (key, value) => {
  if (key === "password") return undefined; // omit
  return value;
});
// '{"name":"Alice","age":30}'

// Replacer as an array (allowlist of keys):
JSON.stringify(obj, ["name", "age"]);
// '{"name":"Alice","age":30}'

Embellecido

Pasa un argumento de espacio a JSON.stringify para embellecer: un número (profundidad de sangría) o una cadena (por ejemplo, '\t'). Para un orden de claves estable (útil para hasheo o firma), ordena las claves antes de serializar. Combínalo con un replacer para filtrar campos mientras embelleces.

json
const obj = { name: "Alice", age: 30 };

// Compact (default):
JSON.stringify(obj);
// '{"name":"Alice","age":30}'

// 2-space indent:
JSON.stringify(obj, null, 2);

// Tab indent:
JSON.stringify(obj, null, "\t");

// Combine replacer and indent:
JSON.stringify(obj, ["name", "age"], 2);

// To insert a stable key order, sort keys first:
const sorted = Object.keys(obj).sort()
  .reduce((acc, k) => (acc[k] = obj[k], acc), {});
JSON.stringify(sorted, null, 2);

Manejo de errores

JSON.parse lanza SyntaxError ante una entrada inválida—envuélvelo siempre en try/catch para datos no confiables. Causas comunes: comas finales, comillas simples, comentarios o entrada truncada. Para JSON muy grande o profundamente anidado, considera un parser en streaming o un límite de profundidad para prevenir denegaciones de servicio.

json
// Always wrap JSON.parse in try/catch for untrusted input.
function safeParse(str) {
  try {
    return { ok: true, value: JSON.parse(str) };
  } catch (e) {
    return { ok: false, error: e.message };
  }
}

// Common errors:
//   SyntaxError: Unexpected token
//   SyntaxError: Unexpected end of JSON input
//   (no undefined/NaN/Infinity accepted)

// For deeply nested untrusted JSON, limit depth to avoid DoS.
// Consider a streaming parser for very large files.
13

Parseo en Python

json.loads

json.loads parsea una cadena JSON en objetos de Python. Los objetos JSON se vuelven dicts, los arrays se vuelven listas, las cadenas se vuelven str, los números se convierten automáticamente en int o float, true/false se vuelven True/False y null se vuelve None. 'loads' significa 'load string'.

json
import json

json_str = '{"name": "Alice", "age": 30}'
data = json.loads(json_str)

print(data["name"])  # Alice
print(data["age"])   # 30

# loads = "load string"
# Returns Python objects: dict, list, str, int/float, bool, None
# JSON true/false/null  ->  Python True/False/None
# JSON numbers          ->  int or float (auto)

json.dumps

json.dumps serializa un objeto de Python a una cadena JSON. Usa indent para embellecer, ensure_ascii=False para conservar los caracteres Unicode (en lugar de escapes \uXXXX) y sort_keys=True para una salida estable. True/False/None de Python se mapean a true/false/null de JSON.

json
import json

data = {"name": "Alice", "age": 30, "active": True}

# Compact:
json.dumps(data)
# '{"name": "Alice", "age": 30, "active": true}'

# Pretty-printed:
json.dumps(data, indent=2, ensure_ascii=False)
# {
#   "name": "Alice",
#   "age": 30,
#   "active": true
# }

# ensure_ascii=False keeps Unicode characters readable.
# sort_keys=True produces stable output.

Parsear archivos

Usa json.load (objeto de archivo) y json.dump (objeto de archivo) para archivos; json.loads y json.dumps para cadenas. Abre siempre los archivos con encoding='utf-8' para evitar los valores por defecto de la plataforma. Para archivos grandes, considera ijson (streaming) u orjson (más rápido) por mejor rendimiento.

json
import json

# Read from a file:
with open("data.json", "r", encoding="utf-8") as f:
    data = json.load(f)

# Write to a file:
with open("out.json", "w", encoding="utf-8") as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

# load/dump work on file objects; loads/dumps work on strings.
# Always specify encoding="utf-8" for portability.

Encoders personalizados

Hereda de json.JSONEncoder y sobrescribe default() para serializar tipos que JSON no soporta de forma nativa (datetime, set, Decimal, clases personalizadas). Devuelve una representación serializable a JSON. Para decodificar, escribe un hook personalizado (object_hook) para invertir la transformación.

json
import json
from datetime import datetime, date

class CustomEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, (datetime, date)):
            return obj.isoformat()
        if isinstance(obj, set):
            return sorted(obj)
        return super().default(obj)

data = {"now": datetime.now(), "tags": {"a", "b"}}
json.dumps(data, cls=CustomEncoder)
# '{"now": "2024-...", "tags": ["a", "b"]}'

# The default() method is called for objects json can't serialize.

Manejo de errores

json.loads lanza json.JSONDecodeError ante una entrada inválida, con información de línea/columna. Causas comunes: comas finales, comillas simples, comentarios, NaN/Infinity (rechazados por defecto) y caracteres de control en cadenas. Usa parse_constant para manejar NaN/Infinity/-Infinity si hace falta.

json
import json

def safe_loads(s):
    try:
        return {"ok": True, "value": json.loads(s)}
    except json.JSONDecodeError as e:
        return {"ok": False, "error": str(e), "line": e.lineno, "col": e.colno}

# json.JSONDecodeError gives line and column of the error.
# Common causes: trailing commas, single quotes, comments,
#   NaN/Infinity (rejected by default), control chars in strings.

# To allow NaN/Infinity (non-standard):
json.loads('{"x": NaN}', parse_constant=lambda x: None)  # or float(x)

Trabajar con Decimal y DateTime

Por defecto, json parsea cada número como float, perdiendo precisión en decimales como el dinero. Pasa parse_float=Decimal para conservar la precisión, y serializa con un hook default que convierta el Decimal de vuelta (a str para preservar la precisión, o float si la pérdida es aceptable). Usa str para una representación exacta del dinero.

json
import json
from decimal import Decimal
from datetime import datetime

# Decimal: parse_float keeps precision (default would lose it)
data = json.loads('{"price": 19.99}', parse_float=Decimal)
print(data["price"])        # Decimal('19.99')
print(data["price"] + Decimal("0.01"))  # 20.00 exact

# Serialize Decimal back:
def encode(obj):
    if isinstance(obj, Decimal):
        return float(obj)   # or str(obj) to keep precision
    raise TypeError

json.dumps({"price": Decimal("19.99")}, default=encode)

# parse_float=float is the default; use Decimal for money.
14

Parseo en Java

Fundamentos de Jackson

Jackson es la librería JSON de Java más popular. ObjectMapper.readValue parsea JSON a POJOs; writeValueAsString los serializa. Añade jackson-databind (más jackson-core y jackson-annotations) como dependencias. Jackson es rápido, maduro y se integra con Spring Boot por defecto.

json
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper();

// Parse JSON to a Java object:
String json = "{\"name\":\"Alice\",\"age\":30}";
User user = mapper.readValue(json, User.class);

// Serialize a Java object:
String out = mapper.writeValueAsString(user);

// Pretty-print:
String pretty = mapper.writerWithDefaultPrettyPrinter()
                      .writeValueAsString(user);

// Jackson is the de facto JSON library for Java.
// Add: com.fasterxml.jackson.core:jackson-databind

Fundamentos de Gson

Gson es la librería JSON de Google, más simple que Jackson para uso básico. Gson.fromJson parsea; toJson serializa. Usa GsonBuilder para opciones (embellecido, serialización de nulls, adaptadores personalizados). Añade com.google.code.gson:gson como dependencia. Gson es común en Android.

json
import com.google.gson.Gson;

Gson gson = new Gson();

// Parse:
User user = gson.fromJson(json, User.class);

// Serialize:
String out = gson.toJson(user);

// Pretty-print:
Gson pretty = new GsonBuilder().setPrettyPrinting().create();
String s = pretty.toJson(user);

// Gson (by Google) is simpler than Jackson for basic use.
// Add: com.google.code.gson:gson

Modelo de árbol JsonNode

El JsonNode de Jackson es un modelo de árbol para navegar JSON sin un POJO. Usa get() (devuelve null si falta) o path() (devuelve un 'nodo faltante' seguro para encadenar). asText/asInt/asBoolean tienen sobrecargas con valor por defecto. Útil cuando el esquema es desconocido o varía.

json
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper();
JsonNode root = mapper.readTree(json);

String name = root.get("name").asText();     // "Alice"
int age = root.get("age").asInt();            // 30
JsonNode hobbies = root.get("hobbies");       // array
for (JsonNode h : hobbies) {
    System.out.println(h.asText());
}

// get() returns null for missing keys; path() returns a
// 'missing node' that you can chain safely.
String city = root.path("address").path("city").asText("unknown");

Deserialización personalizada

Un JsonDeserializer personalizado maneja codificaciones JSON no estándar (por ejemplo, '$19.99' para dinero). Anota un campo con @JsonDeserialize(using = ...) o registra un SimpleModule para un tipo. Usa JsonSerializer para la serialización personalizada. Esto mantiene tus POJOs limpios de lógica de parseo.

json
import com.fasterxml.jackson.databind.*;
import com.fasterxml.jackson.core.*;
import java.io.IOException;

public class MoneyDeserializer extends JsonDeserializer<Double> {
    @Override
    public Double deserialize(JsonParser p, DeserializationContext ctxt)
            throws IOException {
        String s = p.getText();           // e.g. "$19.99"
        return Double.parseDouble(s.replaceAll("[^0-9.]", ""));
    }
}

// Annotate the field:
//   @JsonDeserialize(using = MoneyDeserializer.class)
//   public double price;

// Or register a module for a type.

API de streaming

La API de streaming de Jackson (JsonParser/JsonGenerator) lee y escribe JSON token a token con memoria constante—ideal para archivos enormes. Tú controlas el bucle de parseo y puedes saltarte subárboles con skipChildren(). Emparéjalo con el modelo de árbol o POJO para las partes que realmente necesites.

json
import com.fasterxml.jackson.core.*;

// Jackson streaming: low memory, fast, for huge files.
JsonFactory f = new JsonFactory();
try (JsonParser p = f.createParser(new File("huge.json"))) {
    while (p.nextToken() != JsonToken.END_OBJECT) {
        String field = p.getCurrentName();
        if ("name".equals(field)) {
            p.nextToken();
            System.out.println(p.getText());
        }
        // skip complex values you don't need:
        // p.skipChildren();
    }
}

// Use streaming for files that won't fit in memory.
15

Parseo en PHP

json_encode

json_encode serializa un valor de PHP a JSON. Los arrays de PHP se vuelven objetos JSON (asociativos) o arrays (secuenciales). Flags comunes: JSON_PRETTY_PRINT, JSON_UNESCAPED_UNICODE (conservar Unicode legible), JSON_UNESCAPED_SLASHES (no escapar /). Combina flags con el operador |.

json
<?php
$data = ["name" => "Alice", "age" => 30, "active" => true];

// Compact (default):
$json = json_encode($data);
// {"name":"Alice","age":30,"active":true}

// Pretty-print:
$pretty = json_encode($data, JSON_PRETTY_PRINT);

// Keep Unicode readable (don't escape to \uXXXX):
$unicode = json_encode($data, JSON_UNESCAPED_UNICODE);

// Combine flags with |:
json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE
           | JSON_UNESCAPED_SLASHES);

json_decode

json_decode parsea JSON a PHP. El segundo argumento controla el resultado: true devuelve arrays asociativos, false (por defecto) devuelve objetos stdClass. Elige según tu estilo de acceso ($arr['key'] vs $obj->key). Los arrays de PHP con claves no secuenciales se vuelven objetos JSON.

json
<?php
$json = '{"name":"Alice","age":30,"hobbies":["reading"]}';

// Default: returns associative array OR object (stdClass)
$data = json_decode($json);
echo $data->name;            // Alice

// Force associative array:
$arr = json_decode($json, true);
echo $arr["name"];           // Alice

// The second argument (assoc) controls array vs object.
// PHP objects become stdClass instances by default.

Manejo de errores

El json_decode de PHP no lanza por defecto—comprueba json_last_error() y json_last_error_msg() tras parsear. Pasa JSON_THROW_ON_ERROR (PHP 7.3+) para que lance JsonException en su lugar, lo cual es más limpio. Errores comunes: comas finales, comillas simples y UTF-8 inválido.

json
<?php
$json = '{invalid json}';
$data = json_decode($json);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "Parse error: " . json_last_error_msg();
    // e.g., "Syntax error"
}

// PHP does not throw on JSON errors; check json_last_error().
// Common errors: trailing comma, single quotes, invalid UTF-8.

// To throw exceptions instead:
try {
    $data = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo $e->getMessage();
}

Embellecido y flags

Flags comunes de json_encode: JSON_PRETTY_PRINT (sangría), JSON_UNESCAPED_UNICODE (conservar no ASCII legible), JSON_UNESCAPED_SLASHES (no escapar /), JSON_NUMERIC_CHECK (convertir cadenas numéricas a números), JSON_THROW_ON_ERROR (lanzar ante fallo). Combínalos con |.

json
<?php
$data = ["path" => "C:\\Users", "url" => "https://x.com/"];

// Default escapes / and non-ASCII:
json_encode($data);
// {"path":"C:\\Users","url":"https:\/\/x.com\/"}

// Cleaner output:
json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
           | JSON_PRETTY_PRINT);
// {
//     "path": "C:\\Users",
//     "url": "https://x.com/"
// }

// JSON_NUMERIC_CHECK converts numeric strings to numbers:
json_encode(["id" => "42"], JSON_NUMERIC_CHECK);  // {"id":42}

Serialización personalizada

Implementa JsonSerializable y define jsonSerialize() para controlar cómo se codifica un objeto. Es la forma más limpia de censurar campos (por ejemplo, omitir la contraseña), renombrar claves o calcular valores derivados durante la serialización. La función devuelve cualquier estructura serializable a JSON.

json
<?php
class User implements JsonSerializable {
    public $name;
    public $password;

    public function __construct($name, $password) {
        $this->name = $name;
        $this->password = $password;
    }

    public function jsonSerialize(): mixed {
        return [
            "name" => $this->name,
            // omit password for security
        ];
    }
}

echo json_encode(new User("Alice", "secret"));
// {"name":"Alice"}

// JsonSerializable lets the class control its JSON form.
16

Especificación JSON:API

Estructura del documento

JSON:API es una especificación para construir APIs JSON consistentes. Un documento tiene un objeto 'jsonapi' de versión en el nivel superior, un recurso primario 'data', recursos relacionados 'included' opcionales, 'meta' para información no estándar, 'links' para la paginación y 'errors' para los fallos. El tipo de medios es application/vnd.api+json.

json
{
  "jsonapi": { "version": "1.1" },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API Basics"
    },
    "relationships": {
      "author": { "data": { "type": "people", "id": "9" } }
    }
  },
  "included": [
    { "type": "people", "id": "9", "attributes": { "name": "Jane" } }
  ]
}

// JSON:API is a convention for building JSON APIs.
// Top-level keys: jsonapi, data, errors, meta, links, included.

Objetos de recurso

Un objeto de recurso JSON:API tiene un 'type' (la clase de recurso) y un 'id' (un identificador de cadena), más 'attributes' (los datos) y opcionalmente 'relationships' (enlaces a otros recursos) y 'links' (URLs como self). Los IDs deben ser cadenas. El type y el id no deben aparecer en attributes.

json
{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "Hello",
      "published": true,
      "views": 42
    },
    "links": {
      "self": "/articles/1"
    }
  }
}

// Every resource has a 'type' (string) and 'id' (string).
// 'attributes' holds data; 'relationships' holds links to others.
// 'id' and 'type' MUST NOT appear inside attributes.

Relaciones

Las relaciones enlazan un recurso con otros vía objetos identificador de recurso ({type, id}). Las relaciones a uno usan un único identificador; a muchos usan un array. El objeto 'links' proporciona 'self' (la URL de la relación) y 'related' (la URL del recurso relacionado) para la navegación.

json
{
  "data": {
    "type": "articles",
    "id": "1",
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" },
        "links": {
          "self": "/articles/1/relationships/author",
          "related": "/articles/1/author"
        }
      },
      "tags": {
        "data": [
          { "type": "tags", "id": "1" },
          { "type": "tags", "id": "2" }
        ]
      }
    }
  }
}

// to-one: data is a single resource identifier.
// to-many: data is an array of resource identifiers.

Meta y links

'meta' lleva información no estándar como totales, límites de tasa o advertencias. 'links' proporciona navegación de hipermedia: self, first, prev, next, last para la paginación, más URLs relacionadas. Usa null para un enlace ausente (por ejemplo, prev en la primera página).

json
{
  "meta": {
    "totalPages": 5,
    "currentPage": 1,
    "rateLimit": 100
  },
  "links": {
    "self": "/articles?page=1",
    "first": "/articles?page=1",
    "prev": null,
    "next": "/articles?page=2",
    "last": "/articles?page=5"
  },
  "data": [ /* ... */ ]
}

// meta: non-standard metadata (counts, rate limits, etc.).
// links: pagination and resource URLs.

Errores

Los documentos de error JSON:API tienen un array 'errors' en el nivel superior (y sin 'data'). Cada objeto de error tiene campos opcionales: id, status (código HTTP como cadena), code (específico de la app), title (resumen corto), detail (explicación humana), source (puntero al campo erróneo vía JSON Pointer) y meta.

json
{
  "errors": [
    {
      "id": "err-123",
      "status": "404",
      "code": "NOT_FOUND",
      "title": "Resource Not Found",
      "detail": "Article 99 does not exist.",
      "source": { "pointer": "/data/attributes/id" },
      "meta": { "requestId": "abc-9" }
    }
  ]
}

// Errors is an array of error objects.
// status: HTTP status string; code: app-specific code.
// source.pointer: JSON Pointer to the offending field.
17

JSON5

Características de JSON5

JSON5 es un superconjunto de JSON diseñado para configuración escrita por humanos. Añade comentarios, cadenas sin comillas/entre comillas simples, comas finales, números hex/Infinity/NaN y formatos numéricos relajados. JSON5 no es JSON estándar—usa un parser JSON5 (paquete npm json5) y convierte a JSON para el intercambio.

json
// JSON5 is a superset of JSON with friendlier syntax.
{
  // line comments
  /* block comments */
  unquotedKey: "ok",            // unquoted keys
  "with space": "ok",            // quoted keys still allowed
  singleQuote: 'single',        // single-quoted strings
  trailing: [1, 2, 3,],         // trailing commas
  hex: 0x1F,                     // hexadecimal numbers
  inf: Infinity,                 // Infinity, -Infinity, NaN
  leadingDot: .5,                // leading decimal point
  trailingDot: 5.,               // trailing decimal point
  plus: +5,                      // leading plus
}

// JSON5 is NOT standard JSON—use a JSON5 parser.

Comentarios

JSON5 soporta tanto comentarios de línea // como de bloque /* */, que el JSON estándar prohíbe. Esto hace que JSON5 sea ideal para archivos de configuración escritos por humanos. El settings.json de VS Code y el tsconfig.json de TypeScript usan JSONC (JSON con comentarios), un subconjunto similar pero ligeramente distinto.

json
{
  // Single-line comment (like JS)
  "name": "Alice",

  /* Block comment
     spanning multiple lines */
  "age": 30,

  "active": true // end-of-line comment
}

// Standard JSON rejects comments.
// JSON5 supports // and /* */ comments everywhere.
// VS Code's settings.json and tsconfig.json use JSONC (a subset).

Comas finales

JSON5 permite comas finales tras el último elemento de objetos y arrays. El JSON estándar las rechaza. Las comas finales reducen el ruido en los diffs al añadir o reordenar campos (cada línea puede terminar con coma). Muchos lenguajes y formatos de configuración modernos ya lo permiten.

json
{
  "a": 1,
  "b": 2,
  "c": 3,           // <-- trailing comma OK in JSON5
}

// Arrays too:
[1, 2, 3,]

// Standard JSON rejects trailing commas.
// JSON5 allows them, reducing diff noise when adding fields.

Cadenas sin comillas y con comillas simples

JSON5 permite claves identificador sin comillas (que coincidan con [A-Za-z_$][A-Za-z0-9_$]*) y cadenas tanto entre comillas simples como dobles. Dentro de una cadena entre comillas simples, escapa ' como \'; dentro de una entre dobles, escapa " como \". Esto refleja la sintaxis de literales de objeto de JavaScript por legibilidad.

json
{
  unquoted: "value",          // unquoted identifier key
  "quoted key": "value",       // quoted key (for special chars)
  single: 'single-quoted',     // single-quoted string value
  mixed: 'it\'s ok',           // escape single quote inside
  double: "she said \"hi\"",  // escape double quote inside
}

// Unquoted keys must be valid identifiers ([A-Za-z_$][A-Za-z0-9_$]*).
// Single and double quotes are both allowed for strings.

Números y cadenas (extendidos)

JSON5 extiende los números: hexadecimal (0xFF), puntos decimales inicial/final (.5, 5.), más inicial (+5) y las palabras clave Infinity, -Infinity y NaN. Cada una de estas formas es rechazada por el JSON estándar. Las cadenas JSON5 siguen usando secuencias de escape (\n) para saltos de línea—no hay cadenas multilínea sueltas.

json
{
  hex: 0xFF,                    // hexadecimal
  leadingDot: .5,               // .5 instead of 0.5
  trailingDot: 5.,              // 5. instead of 5.0
  leadingPlus: +5,              // +5 (standard JSON rejects +)
  infinity: Infinity,           // Infinity (not in standard JSON)
  negativeInfinity: -Infinity,
  nan: NaN,
  multiline: 'line1\nline2'    // escape sequences like JSON
}

// JSON5 does NOT support real multi-line strings or bareword NaN.
18

JSON Lines (JSONL)

Formato JSONL

JSON Lines (JSONL o NDJSON) es un formato donde cada línea es un valor JSON separado y completo. No hay array envolvente. Esto lo hace ideal para streaming, logs y datasets grandes: puedes procesar línea por línea sin cargar el archivo completo. Extensiones: .jsonl, .ndjson.

json
// A JSON Lines file (.jsonl / .ndjson) is one JSON value per line:

{"name": "Alice", "age": 30}
{"name": "Bob", "age": 25}
{"name": "Carol", "age": 35}

// Rules:
//   - Each line is a COMPLETE, valid JSON value.
//   - Lines are separated by newlines (\n).
//   - No enclosing [ ] array.
//   - Each line is parsed independently.

Leer JSONL

Lee JSONL iterando las líneas y parseando cada una con JSON.parse/loads. Esto transmite el archivo con memoria constante—ideal para datasets enormes. Sáltate las líneas en blanco. En Node.js, usa readline sobre un stream de archivo; en Python, itera directamente el objeto de archivo. No hace falta cargar el archivo completo.

json
// JavaScript (Node.js) — line by line:
const fs = require("fs");
const readline = require("readline");

const rl = readline.createInterface({
  input: fs.createReadStream("data.jsonl"),
  crlfDelay: Infinity,
});

for await (const line of rl) {
  if (!line.trim()) continue;
  const obj = JSON.parse(line);
  console.log(obj.name);
}

// Python:
//   import json
//   with open("data.jsonl") as f:
//       for line in f:
//           obj = json.loads(line)

Escribir JSONL

Escribe JSONL serializando cada registro con JSON.stringify/dumps (compacto, sin sangría) y añadiendo un salto de línea. Usa un stream escribible (Node) o abre el archivo en modo escritura (Python) por eficiencia. La forma compacta mantiene las líneas cortas y parseables; un registro por línea es la regla.

json
// JavaScript (Node.js):
const fs = require("fs");
const out = fs.createWriteStream("out.jsonl");
for (const obj of records) {
  out.write(JSON.stringify(obj) + "\n");
}
out.end();

// Python:
//   import json
//   with open("out.jsonl", "w") as f:
//       for obj in records:
//           f.write(json.dumps(obj) + "\n")

// One JSON per line; compact form (no indent) is conventional.

Casos de uso

JSONL brilla para archivos de log, datasets grandes, datos de entrenamiento de ML, volcados de base de datos y flujos de eventos de solo adición. Cada línea es independiente, así que puedes añadir sin reescribir, reanudar el parseo tras una línea corrupta y procesar en paralelo. Herramientas como jq y los pipes del shell funcionan naturalmente con él.

json
// JSONL is ideal for:
//   - log files (one event per line)
//   - large datasets (streaming, append-only)
//   - machine learning training data
//   - database exports/imports
//   - append-only event streams

// Example: log entry per line
{"ts": "2024-01-15T10:00:00Z", "level": "info", "msg": "started"}
{"ts": "2024-01-15T10:00:01Z", "level": "error", "msg": "failed"}

// Tools: jq, xargs, awk | json.loads — all work line-by-line.

JSONL vs array JSON

Un array JSON envuelve los registros en [ ] y exige cargar (o transmitir cuidadosamente) el archivo completo para parsearlo. JSONL pone un registro por línea, habilitando streaming verdadero, adición fácil y recuperación de líneas corruptas. Para datasets grandes o en crecimiento, JSONL es casi siempre la mejor elección.

json
// JSON Array (one big file):
[
  {"name": "Alice"},
  {"name": "Bob"},
  {"name": "Carol"}
]

// JSONL (one per line):
{"name": "Alice"}
{"name": "Bob"}
{"name": "Carol"}

// JSON Array: must load whole file to parse; hard to append.
// JSONL: streamable, appendable, resumable; slightly more
//        per-record overhead but far better for big files.
19

Seguridad

Riesgos de JSONP

JSONP envuelve JSON en un callback de JavaScript para que una etiqueta <script> pueda obtener datos entre orígenes, saltándose la misma política de origen. Esto es peligroso: cualquier sitio puede leer la respuesta, la inyección de callback habilita XSS y las peticiones llevan las cookies de la víctima. Usa CORS en su lugar—JSONP es herencia y no es seguro.

json
// JSONP (JSON with Padding) bypasses same-origin policy
// by wrapping JSON in a script callback:
callbackHandler({"secret": "data"});

// Loaded via <script src="https://api.example.com/data?callback=callbackHandler">

// RISKS:
//   - Any site can include the URL and read the response.
//   - XSS if the callback name is attacker-controlled.
//   - CSRF: the request is made with the victim's cookies.

// MODERN ALTERNATIVE: use CORS instead of JSONP.
// JSONP is legacy—avoid it for new APIs.

Prevención de XSS

El JSON incrustado en etiquetas HTML <script> puede causar XSS: la cadena '</script>' termina el script antes de tiempo. Además, U+2028 y U+2029 (separadores de línea/párrafo) son válidos en cadenas JSON pero rompen JavaScript. Escapa <, >, &, U+2028, U+2029 al incrustar JSON en HTML, o usa una librería como serialize-javascript.

json
// JSON itself is data, not executable—BUT embedding it in
// HTML can cause XSS if not careful.

// BAD: output JSON inside <script> without escaping:
//   <script>
//     var data = {"name": "</script><script>alert(1)</script>"};
//   </script>

// GOOD: escape < and > (and &) when embedding in HTML:
const safe = JSON.stringify(data)
  .replace(/</g, "\\u003c")
  .replace(/>/g, "\\u003e")
  .replace(/&/g, "\\u0026")
  .replace(/\u2028/g, "\\u2028")
  .replace(/\u2029/g, "\\u2029");

// Or use a library: js-xss, serialize-javascript.

Contaminación de prototipos

La contaminación de prototipos ocurre cuando JSON no confiable con claves como '__proto__' o 'constructor' se fusiona en objetos, envenenando Object.prototype y afectando a cada objeto. Defensas: usa Object.create(null), bloquea las claves peligrosas, prefiere Map para datos no confiables y mantén actualizadas las librerías de fusión.

json
// Merging untrusted JSON into objects can pollute prototypes:
const evil = JSON.parse('{"__proto__": {"isAdmin": true}}');

// BAD merge (Object.assign does NOT pollute, but some libs do):
//   function merge(target, src) {
//     for (const k in src) target[k] = src[k];
//   }

// Attackers can set Object.prototype.isAdmin = true,
// affecting ALL objects.

// Defenses:
//   - Use Object.create(null) for parsed objects.
//   - Block keys like __proto__, constructor, prototype.
//   - Use Map instead of plain objects for untrusted data.
//   - Keep dependencies updated (some had merge() flaws).

Inyección vía JSON

JSON en sí resiste la inyección, pero construirlo mediante concatenación de cadenas es peligroso—la entrada del usuario puede romper la estructura JSON. Usa siempre un serializador real (JSON.stringify). Lo mismo aplica aguas abajo: usa consultas SQL parametrizadas, execFile con arrays de argumentos y motores de plantillas con escape HTML.

json
// JSON itself is not injectable, but building JSON by
// concatenation is dangerous:

// BAD: string concatenation
//   const json = '{"name": "' + userInput + '"}';
//   // userInput = '"); drop table; //'  ->  breaks out

// GOOD: always use a real serializer
const json = JSON.stringify({ name: userInput });

// For SQL: use parameterized queries, not JSON interpolation.
// For shell: use execFile with arg arrays, not string concat.
// For HTML: use textContent or a templating engine that escapes.

DoS vía JSON grande o profundo

DoS basado en JSON: archivos enormes agotan la RAM, el anidamiento profundo desborda la pila del parser y las estructuras patológicas (el análogo JSON de 'billion laughs') inflan una entrada pequeña. Defensas: limita el tamaño del body en el proxy, limita la profundidad de parseo, usa parsers en streaming para entradas grandes y fija timeouts.

json
// Attackers can craft JSON to exhaust memory or CPU:
//
//   1. Huge file: 1 GB of '[1,1,1,...]' to exhaust RAM.
//   2. Deep nesting: '{"a":{"a":{"a":...}}}' (10000 levels)
//      to overflow the parser's stack.
//   3. 'Billion laughs': nested entity expansion (XML-era,
//      but JSON analogs exist with $ref in some libs).
//   4. Many keys: 10 million keys in one object.

// Defenses:
//   - Cap request body size at the server/reverse proxy.
//   - Limit parsing depth (Ajv, fast-json-parse options).
//   - Use streaming parsers (stream-json, oboe) for big input.
//   - Set timeouts on parsing.

Prácticas de parseo seguro

Parseo JSON seguro: usa siempre JSON.parse (nunca eval), valida contra un esquema (Ajv, jsonschema) antes de usar, limita la profundidad y el número de claves, deshabilita las claves __proto__ y considera parsear la entrada no confiable en un Web Worker o sandbox. JSON.parse en sí es seguro frente a la ejecución de código; los riesgos están en cómo usas los datos parseados.

json
// 1. Validate with a schema before using untrusted JSON.
const Ajv = require("ajv");
const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);
if (!validate(data)) throw new Error(ajv.errorsText(validate.errors));

// 2. Limit depth and key count when parsing.
// 3. Use reviver/replacer to coerce types safely.
// 4. Never eval() or Function('return ' + json) — use JSON.parse.
// 5. Disable dangerous features (e.g., __proto__ keys).
// 6. Parse untrusted JSON in a sandbox or worker if possible.

// JSON.parse is safe; eval is NOT.
20

Buenas prácticas y herramientas

Esquema primero

Diseña las APIs con esquema primero: define un JSON Schema, genera los tipos del lenguaje a partir de él (typescript-json-schema, quicktype, jsonschema2pojo) y valida peticiones/respuestas en tiempo de ejecución. Esto detecta temprano las violaciones de contrato, habilita la generación de código y sirve como documentación viva.

json
// Define a JSON Schema before shipping an API.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "name"],
  "properties": {
    "id":   { "type": "integer" },
    "name": { "type": "string", "minLength": 1, "maxLength": 100 }
  },
  "additionalProperties": false
}

// Generate types from the schema (TypeScript, Java, Go, ...).
// Validate both requests and responses against the schema.
// Publish the schema for clients (OpenAPI, JSON Schema).

Nombrado consistente

Elige una convención de nombrado para las claves y aplícala consistentemente: camelCase (la mayoría de APIs JSON y JS), snake_case (backends de Python/Ruby, APIs de Google) o PascalCase (.NET). Mezclar estilos es confuso. Si el frontend y el backend difieren, convierte en una única frontera en lugar de mezclar en el esquema.

json
// Pick ONE naming convention and apply it everywhere.

// camelCase (most JSON APIs, JavaScript ecosystem):
{ "firstName": "Alice", "lastName": "Smith" }

// snake_case (Python/Ruby backends, many Google APIs):
{ "first_name": "Alice", "last_name": "Smith" }

// kebab-case (rare in JSON, common in URLs/config):
{ "first-name": "Alice" }

// PascalCase (rare in JSON keys, common in C#/.NET types):
{ "FirstName": "Alice" }

// Avoid mixing; convert at the boundary if the front/back differ.

Versionado

Versiona las APIs desde el primer día: en la ruta de la URL (/v1/), un campo de versión en el payload, el header Accept (tipo de medios) o un espacio de nombres (el @context de JSON-LD). Los cambios aditivos (nuevos campos opcionales) normalmente no rompen compatibilidad; sube la versión ante campos eliminados/renombrados o semántica cambiada.

json
// 1. Version in the URL path:
//    https://api.example.com/v1/users

// 2. Version field in the payload:
{ "version": "1.0", "data": { ... } }

// 3. Accept header / media type:
//    Accept: application/vnd.example.v1+json

// 4. Namespace the JSON (JSON-LD, JSON:API 'type'):
{ "@context": "https://schema.org/v1", ... }

// Plan for evolution: add optional fields freely, but bump
// the version for breaking changes (removed/renamed fields,
// changed semantics or types).

Codificación (UTF-8)

UTF-8 es la codificación por defecto y la única ampliamente recomendada para JSON. Guarda los archivos como UTF-8 sin BOM (algunos parsers lo manejan mal), fija el Content-Type con charset=utf-8 y fija Content-Length en bytes. En Python, pasa ensure_ascii=False para mantener los caracteres Unicode legibles en lugar de escapes \uXXXX.

json
// Always use UTF-8 for JSON.
//   - Save files as UTF-8 (no BOM).
//   - Set Content-Type: application/json; charset=utf-8.
//   - Set Content-Length in bytes (not characters).

// In Node.js:
res.setHeader("Content-Type", "application/json; charset=utf-8");
res.end(JSON.stringify(data));

// In Python:
import json
with open("out.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False)

// ensure_ascii=False keeps Unicode readable in the file.

Consejos de rendimiento

Por rendimiento: transmite JSON grande en streaming (ijson, stream-json, Jackson streaming) en lugar de almacenarlo en búfer; usa serializadores rápidos (orjson, fast-json-stringify); transmite compacto y comprime con gzip/brotli sobre HTTP; evita el anidamiento profundo y los arrays enormes; cachea los resultados parseados para no volver a parsear.

json
// 1. Stream large JSON instead of buffering it all.
//    - Node: stream-json, JSONStream
//    - Python: ijson
//    - Java: Jackson streaming API

// 2. Use a fast serializer:
//    - Node: fast-json-stringify (schema-based), orjson (Python)
//    - Compile serializers from a schema for hot paths.

// 3. Compact JSON for transmission; pretty only for humans.

// 4. Avoid deep nesting and huge arrays when possible.

// 5. Compress with gzip/brotli over HTTP (huge savings).

// 6. Cache parsed results; don't re-parse the same payload.

Herramientas y validadores

Herramientas para trabajar con JSON: validadores en línea (jsonlint.com, jsonschemavalidator.net), herramientas CLI (jq para consultar/formatear, jsonschema para validar), soporte en editores (VS Code y JetBrains tienen validación JSON + esquema integrada) y generadores de código (quicktype genera tipos de TypeScript/Java/Go/etc. a partir de JSON o un esquema).

json
// Online validators:
//   - https://jsonlint.com
//   - https://jsonformatter.org
//   - https://www.jsonschemavalidator.net

// CLI tools:
//   - jq          (filter, query, format JSON on the command line)
//   - jaq         (Rust jq clone, faster)
//   - jsonschema  (Python CLI for schema validation)
//   - ajv         (Node CLI/library for JSON Schema)

// Editor support:
//   - VS Code: built-in JSON + schema validation
//   - JetBrains: built-in JSON + schema support
//   - vim/emacs: plugins available

// Schema tools:
//   - quicktype   (generate types from JSON)
//   - typescript-json-schema
//   - jsonschema2pojo (Java)

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.