Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Referencias de grafo JSON y escape de rutas

Conserva objetos compartidos y ciclos en texto JSON mediante marcadores `$ref` y rutas que distinguen los caracteres de las claves de los separadores.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

Application-defined JSON graph marker: {"$ref":"<path>"}
Root path: "". Child path: parentPath + "/" + escapeToken(keyOrIndex).
escapeToken(token): replace ~ with ~0, then / with ~1.
To read a path as segments, treat "" as zero segments. For any other path, require a leading /, remove exactly that first /, then split the remainder at /, keeping empty segments. The path / has one empty segment. In each segment, replace ~1 with /, then ~0 with ~.

El JSON ordinario representa un árbol de valores, no la identidad de los objetos. De forma predeterminada, JSON.stringify() escribe un objeto compartido sin ciclos por separado en cada aparición. JSON.parse() crea objetos distintos a partir de esas copias. Si la serialización encuentra un ciclo, JSON.stringify() lanza un TypeError.

En esta convención de la aplicación, un WeakMap guarda la primera ruta de un objeto antes de visitar sus descendientes. Al volver a encontrar el mismo objeto, el codificador emite {"$ref":"<path>"}. Este objeto con un único campo de tipo cadena se reserva para referencias; JSON.parse() no las resuelve por sí solo.

En una ruta de estilo JSON Pointer, "" indica la raíz y / indica su propiedad de clave vacía. Cada segmento es una clave de objeto o un índice de array que empieza en cero. Antes de unir los segmentos con /, sustituye ~ por ~0 y después / por ~1. La clave a/~1 da /a~1~01. Al leer, interpreta "" como una ruta sin segmentos. Toda ruta no vacía debe empezar por /: quita solo ese primer / y separa el resto por /, conservando los segmentos vacíos. Así, la ruta / tiene un único segmento vacío. En cada segmento, sustituye ~1 por / y después ~0 por ~. Esto no es el escape de cadenas JSON ni la codificación porcentual de URI.

Tras analizar el JSON, indexa primero los objetos y arrays reales y luego sustituye los marcadores por sus destinos. Así también funcionan las referencias a destinos que aparecen más adelante. Si los datos no son de confianza, valida el formato, limita el tamaño y la profundidad, y rechaza rutas inválidas y destinos inexistentes. No uses eval() ni recorras cadenas de prototipos.

Si necesitas una copia en vez de texto, structuredClone() conserva los ciclos y las referencias compartidas para los valores admitidos. Es una API de la plataforma web, no un método de JSON; su disponibilidad depende del entorno de ejecución.

Ejemplos

{
  const childPath = (path, key) =>
    path + '/' + String(key).replace(/~/g, '~0').replace(/\//g, '~1');

  const shared = { count: 1 };
  const graph = { 'a/~1': shared, alias: shared };
  graph.self = graph;

  const seen = new WeakMap();
  function encode(value, path = '') {
    if (value === null || typeof value !== 'object') return value;
    if (seen.has(value)) return { $ref: seen.get(value) };
    seen.set(value, path);
    if (Array.isArray(value)) {
      return value.map((item, index) => encode(item, childPath(path, index)));
    }
    return Object.fromEntries(Object.entries(value).map(([key, item]) =>
      [key, encode(item, childPath(path, key))]));
  }

  const text = JSON.stringify(encode(graph));
  const restored = JSON.parse(text);
  const nodes = new Map();
  const links = [];

  function index(node, path = '') {
    nodes.set(path, node);
    for (const [key, item] of Object.entries(node)) {
      if (item === null || typeof item !== 'object') continue;
      const keys = Object.keys(item);
      if (!Array.isArray(item) && keys.length === 1 && keys[0] === '$ref' &&
          typeof item.$ref === 'string') {
        links.push([node, key, item.$ref]);
      } else {
        index(item, childPath(path, key));
      }
    }
  }

  index(restored);
  for (const [owner, key, path] of links) {
    if (!nodes.has(path)) throw new Error('Invalid reference path');
    owner[key] = nodes.get(path);
  }

  console.log(text);
  console.log(restored.alias === restored['a/~1']);
  console.log(restored.self === restored);
}

Resultado

{"a/~1":{"count":1},"alias":{"$ref":"/a~1~01"},"self":{"$ref":""}}
true
true

El ejemplo utiliza datos de confianza: objetos simples, arrays sin huecos y valores primitivos representables en JSON. El decodificador compara las rutas escapadas completas en un `Map`, así que no necesita deshacer el escape de los segmentos. Los dos resultados `true` confirman que se restauraron la referencia compartida y el ciclo.

Lecciones relacionadas

  • JavaScript · Lección 17 · Avanzado · Versión: 4

Fuentes