Free Online Developer Tools - ULID, UUID, NanoID, CUID, Snowflake ID, JWT Decoder, Base64, JSON Formatter & More

Меню инструментов

JSON Patch

Примените JSON Patch по RFC 6902 в браузере. Операции add, remove, replace, move, copy и test, экранирование JSON Pointer и сдвиг индексов массива.

JSON Patch

Apply RFC 6902 JSON Patch operations to transform JSON documents.

Runs locally
JSON
Ln 1, Col 10 B
Empty
JSON
Ln 1, Col 10 B
Empty
JSON
Ln 1, Col 10 B
Empty

Что такое JSON Patch

JSON Patch (RFC 6902) - это список операций, который превращает один JSON-документ в другой. У каждой операции есть op и path. path - это JSON Pointer (RFC 6901): путь от корня, разделенный косыми чертами. Шесть операций: add, remove, replace, move, copy и test.

Список упорядочен. Следующая операция видит документ после предыдущих. test документ не меняет. Он проверяет, что в точке сейчас лежит ожидаемое значение. Так API отклоняет патч, если это поле уже изменил кто-то другой.

Эта страница применяет патч в браузере. Документ и патч не загружаются.

Как указатель выбирает значение

Пустой указатель "" - это весь документ. "/name" - член name. "/tags/0" - первый элемент массива, счет с нуля. "/tags/-" в операции add означает добавить в конец. Знак "~" внутри ключа записывается как "~0", а "/" внутри ключа как "~1". Сначала раскодируется "~1", потом "~0". Так делает и эта страница, поэтому настоящая последовательность "~1" в ключе не ломается.

Ключ a/b - это /a~1b. Ключ c~d - это /c~0d.
{ "op": "add", "path": "/a~1b", "value": 1 }
{ "op": "remove", "path": "/c~0d" }

Патч, который можно проследить

Начните с документа ниже. test проверяет, что name все еще Ada. replace меняет имя. add с "/tags/-" дописывает snowflake, массив становится ["ulid", "uuid", "snowflake"]. add создает address.country. remove по "/tags/0" после этого убирает ulid, потому что индекс относится к массиву на этом шаге. Результат - третий блок.

Документ
{
  "name": "Ada",
  "tags": ["ulid", "uuid"],
  "address": { "city": "Hanoi" }
}
Патч
[
  { "op": "test", "path": "/name", "value": "Ada" },
  { "op": "replace", "path": "/name", "value": "Ada Lovelace" },
  { "op": "add", "path": "/tags/-", "value": "snowflake" },
  { "op": "add", "path": "/address/country", "value": "VN" },
  { "op": "remove", "path": "/tags/0" }
]
Результат
{
  "name": "Ada Lovelace",
  "tags": ["uuid", "snowflake"],
  "address": { "city": "Hanoi", "country": "VN" }
}

move, copy и test

move удаляет значение по from и добавляет его по path. copy добавляет, не удаляя, источник остается. move элемента массива на более поздний индекс того же массива легко сделать неправильно: удаление сдвигает все, что шло после. test сравнивает текущее значение с value. Если они не совпали, страница останавливается с ошибкой и не делает вид, что остаток списка применен. RFC 6902 требует, чтобы весь патч провалился, если провалилась любая операция. Вызывающий код должен считать результат целиком успешным или отсутствующим.

Когда это нужно

  • Вы пишете частичное обновление и хотите увидеть документ после настоящего списка op, а не после мысленного diff.
  • Нужно предусловие. Поставьте test первым, чтобы устаревший клиент не затер уже измененное поле.
  • Вы выбираете между JSON Patch и JSON Merge Patch (RFC 7396). Merge Patch - это один документ: объекты сливаются, массивы заменяются целиком, null удаляет член. Он не умеет дописывать массив и не умеет test.

Ошибки

  • Индексы массива съезжают. Удалить /tags/0 и затем /tags/1 - это не исходные первый и второй элементы. После первого удаления старый второй элемент уже на индексе 0.
  • replace требует, чтобы путь существовал. add создает отсутствующий член объекта, а add с "-" дописывает в конец. replace для нового поля завершится ошибкой.
  • Пути RFC 6902 чувствительны к регистру. На странице есть переключатель Ignore Case, и он включен. Он может спрятать неверный ключ. Выключите его, если нужно поведение спецификации.
  • Strict Path Validation - местная настройка, ее нет в RFC. Включайте, когда отсутствующий промежуточный объект должен быть ошибкой, а не путем, по которому add проходит дальше.
  • Патч нельзя переставлять как diff. move и remove зависят от предыдущих шагов. Если не хотите вести список руками, соберите его из версии до и версии после.

JSON Patch и соседние форматы

ФорматЧто отправляетеЧего он не умеет
JSON Patch (RFC 6902)Упорядоченный список объектов opНичего неявного: каждое изменение - операция
JSON Merge Patch (RFC 7396)Частичный документДописать массив или проверить предусловие. null означает удаление
Просмотр JSON diffДва полных документаОн показывает различие. Это еще не тело запроса, пока вы не превратили его в патч

Вопросы

Что значит /tags/-?

В операции add одиночный символ - в конце указателя дописывает элемент в массив. Это не член с именем "-". В других операциях - не является особым индексом.

Почему remove удалил не тот элемент?

Каждая операция видит документ, оставленный предыдущей. После удаления поздние индексы указывают на другие элементы. Удаляйте большие индексы первыми или соберите патч заново по обновленному документу.

Как назвать ключ, внутри которого есть косая черта?

Его нужно экранировать. / в ключе становится ~1, а ~ в ключе становится ~0. Указатель /a~1b ведет к члену a/b. /c~0d ведет к члену c~d.

Откатывает ли неудачный test предыдущие операции?

На корректном сервере неудачный test отклоняет весь патч, включая операции до него. Не рассчитывайте, что клиент сохранит наполовину примененный документ. Ставьте test там, где предусловие обязано выполняться.

Ignore Case входит в RFC 6902?

Нет. Имена членов JSON Pointer должны совпадать точно. Ignore Case - переключатель этой страницы, и по умолчанию он включен. Выключите его, чтобы соответствовать спецификации.

Купите разработчику кофе для поддержки проекта