Что такое 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" в ключе не ломается.
{ "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 - переключатель этой страницы, и по умолчанию он включен. Выключите его, чтобы соответствовать спецификации.