JSON Patch: aplica operaciones RFC 6902 paso a paso

Qué es JSON Patch

JSON Patch es un formato pequeño para describir cambios sobre un documento JSON en lugar de mandarlo entero. Un parche es un array de operaciones, y cada una dice qué hacer y dónde: add, remove, replace, move, copy y test. El RFC 6902 define las seis en unas ocho páginas, y cada ubicación se escribe como un puntero JSON, el formato hermano que nombra exactamente un sitio dentro de un documento.

Existe porque mandar un documento entero para cambiar un campo es un derroche y además es ambiguo: dos clientes haciendo eso se pisan el uno al otro sin enterarse. Un parche dice qué cambió, lo que ocupa menos y es lo bastante específico como para rechazarlo si el documento ya no es el que era. Para eso está la sexta operación: test no cambia nada, afirma, y un parche que empieza con un test es un cambio que se niega a aplicarse sobre el documento equivocado.

Esta página ejecuta un parche contra un documento y enseña el resultado tras cada operación, no solo al final. Y eso importa más de lo que parece, por lo que cuenta la sección siguiente a la siguiente.

Cómo se usa

1. Pega el documento. Nunca se modifica sobre el original: cada operación trabaja sobre una copia, así que tu documento queda intacto haga lo que haga el parche.
2. Pega el parche. Un array de operaciones. Los botones de ejemplo cargan cinco casos: un test que falla a mitad, una inserción en un array, un test usado como salvaguarda, un move que la norma prohíbe y un índice más allá del final de un array.
3. Lee la traza. Cada fila es una operación, y puedes desplegar cualquiera para ver el documento entero tal y como estaba en ese momento. Un fallo nombra la regla concreta en vez de no decir nada.

Un parche JSON no es atómico, y la norma no dice que lo sea

Todo el mundo sabe que un parche fallido deja el documento intacto. Es lo primero que te cuentan del formato, y no es lo que dice el RFC 6902.

La sección 5 dice que, ante un fallo, la evaluación debería detenerse y la aplicación del parche entero no debe darse por buena. Léelo con atención: es una afirmación sobre el veredicto, sobre si el parche cuenta como aplicado. No dice nada de deshacer las operaciones que ya se ejecutaron. La atomicidad que todo el mundo cita llega una frase después y desde otro sitio: una nota que dice que el método HTTP PATCH es atómico, según otro documento, el que define ese método.

Así que la garantía es del transporte, no del formato. Manda un parche por HTTP PATCH y el servidor está obligado a aplicarlo entero o nada. Pásale el mismo parche a una biblioteca dentro de tu proceso y si te quedas con un objeto a medio modificar es asunto de esa biblioteca, no algo que la norma resuelva por ti. El ejemplo que trae la propia norma es un parche de dos operaciones cuyo test falla el segundo, y dice que el documento acaba sin cambios: porque está describiendo el caso HTTP.

Por eso esta herramienta enseña todos los estados intermedios. Cuando un parche falla aquí, descarta el resultado y te lo dice, lo cual es una decisión y no una regla; y te enseña en qué se había convertido ya el documento, que es justo lo que te oculta una herramienta que solo imprime la respuesta final.

Tres reglas que sorprenden

Añadir a un array inserta, no sobrescribe. Apunta add al índice uno de un array de tres elementos y te quedan cuatro, con todo lo que había del uno en adelante desplazado a la derecha. Si querías sobrescribir, eso es replace. El índice puede ser igual a la longitud, lo que añade al final, pero cualquier cosa más allá es un error y no una escritura dispersa; y la sintaxis de punteros tiene un guion que significa después del último elemento, que dice añade al final mucho más claro que un número.

La misma operación esconde otra trampa más callada. Añadir un array como valor lo mete entero como un solo elemento, así que una lista de uno más un array de dos se convierte en una lista de dos, el segundo de los cuales es a su vez una lista. La norma lo incluye como ejemplo aparte, lo que suele ser señal de que la gente esperaba lo otro.

Move trae una regla sin equivalente entre las demás operaciones: el origen no puede ser prefijo propio del destino o, en palabras de la propia norma, una ubicación no puede moverse dentro de uno de sus hijos. Es obvio en cuanto se dice y facilísimo de escribir sin querer cuando las rutas son largas.

Y test compara tipos además de valores. El número diez y la cadena diez son distintos, y un test que enfrente uno con otro falla. Es el comportamiento que quieres de una precondición, pero pilla a quien viene de un formulario o de una cadena de consulta, donde todo llegó como texto.

Limitaciones honestas

Esto aplica parches; no los genera. Producir el parche mínimo entre dos documentos es otro problema, con varias respuestas defendibles, y la norma no define ninguna.

Hay un ejemplo de la norma que esta herramienta no puede ejecutar, y conviene saber por qué. Es un parche cuyo objeto de operación contiene el mismo miembro dos veces —op aparece como add y como remove— y la norma señala que JSON solo dice que los nombres de miembro deberían ser únicos, sin ningún tratamiento estándar para los duplicados. Cualquier analizador de JavaScript lo resuelve en silencio quedándose con el último, de modo que el defecto que el ejemplo quiere describir se destruye antes de que un motor de parches vea el documento. Es una propiedad del analizador, no del formato, y ninguna implementación que reciba JSON ya analizado puede detectarlo.

Por último, esta herramienta descarta el resultado cuando falla cualquier operación. Es deliberado y es lo más seguro por defecto, pero es una decisión que ha tomado esta página, no algo que imponga el formato, y por eso el documento a medias se enseña al lado en vez de tirarse a la basura sin decir nada.

¿Por qué es gratis?

Recorrer un documento y aplicar un puñado de operaciones son unos cientos de líneas de manejo de cadenas y arrays, y tu navegador lo hace mientras escribes. Ningún servidor ve tu JSON, así que no hay nada que medir ni ninguna cuenta que crear.

No se sube nada. Lo que pegues se queda en esta pestaña.