JSON Patch

`/` is a weird choice of delimiter for JSON.

Since JSON is a subset of JS, I would have expected `.` to be the delimiter. That jives with how people think of JSON structures in code. (Python does require bracket syntax for traversing JSON, but even pandas uses dots when you generate a dataframe from JSON.)

When I see `/`, I think:

- "This spec must have been written by backend people," and

- "I wonder if there's some relative/absolute path ambiguity they're trying to solve by making all the paths URLs."

this was one of the biggest learning curves / adjustments tbh but once I got over that it's surprisingly powerful.

It tackles like 80% of cases

Extending the 80/20 analogy, how much additional efforts does the last 20% take here? The format seems efficient enough, but I'm wondering about the complexity trade-offs one can expect.

Maybe we're talking about different things, but resources in REST are identified by their URL and URLs use '/' to separate elements in the path.

It sort of is like a URL here's some more examples with both relative and absolute queries https://opis.io/json-schema/2.x/pointers.html

Yeah, but nobody ever looked at

    {
      "a": {
        "b": {
          "c": []
        }
      }
    }

and thought "I need the list at /a/b/c"

If you've ever done XPath you do!

Anecdotal, I did and I do. It's no different than a path on a filesystem.

Seems like a reasonable thing to me.

    {
      "makes": {
        "toyota": {
          "models: [ ... ]
        }
      }
    }

"I need all the models of Toyota cars."

Or

"Toyota came out with a new Camry, I need to update the Camry object within Toyota's models."

Yeah, but that's makes.toyota.models, not /makes/toyota/models.

The point is that this is a data structure and not a web server. It's using a convention from one domain in a different one. Relatively minor in the scope of possible quibbles, but it's just one more thing to remember/one more trivial mistake to make. I'm sure much collective time will be lost to many people using dots where the spec says to use slashes, and not realizing it because it looks right in every other context with dots. Dots also makes copy/pasting easier, because you wouldn't have to migrate the format after pasting.

Yeah, wrote my own XPath-like extension methods to manipulate JSON just like that. Felt very natural and makes it quite easy to generate and process JSON for the cases serialization/deserialization isn't the best option.

Oh I see what you mean. I misunderstood, I also don't like slash as a separator.

JSON is derived from JavaScript, it is not a strict subset.

The most glaring issue is JSON number type versus JavaScript float. This causes issues in both directions whereby people consistently believe JSON can't represent numbers outside the float range and in addition JSON has no way to represent NaN.

Is there any legal JSON that's not legal JavaScript?

If not, it's fair to say it's a subset.

But it's different than object notation in JS, and considering JSON stands for JavaScript Object Notation, I think dot notation would have been more appropriate for JSON Pointer (and by extension JSON Path). As a bit of a rebel myself, I use dot notation when describing a location in a JSON document, unless I'm forced to use the slash for something like JSON Pointer.

It is a subset as of JavaScript edition ES2019, when JavaScript strings are now allowed to contain U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR. Prior to ES2019, that was the only known example of legal JSON that was not legal JavaScript

JavaScript used to forbid U+2028 line separator and U+2029 paragraph separator in string literals, but JavaScript now allows them for compatibility with JSON.

The remaining wrinkle is different handling of "__proto__"

I agree "." would make more sense than "/".

I actually think an array would be better, ["foo","bar"] for "foo.bar". How many many bugs are introduced by people not escaping properly? It's more verbose, but judging by the rest of the standard, they don't seem to be emphasizing brevity.

You're not the only one who thinks that!

JSON Patch uses JSON Pointer (RFC 6901) to address elements, but another method from (very) roughly same time is JSON Path [0] (RFC 9535) and here's one of my favorite mnemonics:

- JSON Path uses "points" between elements

- JSON Pointer uses "path separators" between elements

[0] https://en.wikipedia.org/wiki/JSONPath

It quickly gets convoluted since Camry has been produced for more than 30 years with regular model refreshes throughout the years, e.g. 1997, 2003, 2025 etc. JSON Pointer quickly falls short since we now require a selection expression to figure out which year model we need to update in the array of models: «makes.toyota.models[?year == `2025`]» (using JMESPath).

Both, JSONPath or JMESPath, support query expressions whereas JSON Pointer does not.

I would have expected paths to be an array of string/number (e.g. ["persons", 3, "name"]) because keys can be any string.

Such a document may not be wise, but how would you update something like:

    { "charCounts": { "/": 1234, "a": 100, ".": 99 } }

Yeah, it sucks. It was borrowed from XPath. And it's not appropriate for JSON.

https://en.wikipedia.org/wiki/XPath

and json path is supported in Postgres as a way to query json documents. It’s surprisingly full featured!

Not only that; both a dot (“.”) and a forward slash (“/”) are allowed to be used in/as a JSON property name.

An array of keys alleviates this issue entirely because any string element of the array can be used as a JSON object property name too.

> The point is that this is a data structure and not a web server.

URIs are not only used on web servers though, they're all over the place, probably most notable your filesystem is using `/` as a path separator, so it wouldn't be completely out of place to use it as a path separator elsewhere.

Definitely agree on the array. They were smart enough to use JSON for the patch format so that people didn't have to write custom parsers but then used a selector syntax that requires a custom parser (and serializer). It seems like an obvious unforced error.

When convertcsv.com converts JSON to CSV, it uses the / separator to store the structure in the column headings. Probably could use an option for . too.

Also the escaping uses "~" as the escape character, and it escapes "~" and "/" as "~0" and "~1" instead of "~~" and "~/". This whole spec feels like it was written by aliens.

You would need to somehow differentiate between absolute and relative paths, though.

That I really don't like, it doesn't make any sense. "/" as a path delimiter feels totally ok though. I mean, it's path, after all. Also, I'd expect "." to be a part of a key much more often, than "/". And also it really doesn't matter what delimiter you use.

it's really good for re-organizing schemas from for example Notion collections to a simple flat CSV / Google Sheets schema and Airtable

It's really bad at creating deeply nested schemas though, (eg from CSV -> Notion you'll get trouble). It's also limited in things like renaming keys, splitting values into multiple keys (eg a csv string into an array) and those sorts of things