Improve JsonPointer navigation and add JsonPointerGlob #291
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Navigation of the document was done with JsonPointer tokens. Which was a list of Strings. Instead this has been refactored to use a `JsonPointer` class.
`JsonPointer`doesn't allow wildcards in the pointer. That is not an issue for `JsonPointer`'s in a schema. However, if we want to navigate a KsonValue using more expressive pointers we can't. Options to deal with this would be using `JsonPath`, `JmsePath`. However, before we commit to that I'd propose we use a simple improvement of `JsonPointer`, namely `JsonPointerPlus`. It adds the possibility to use wildcards `*`, and glob matching for a property key (only with ? (matching a single character) and * (matching all characters)).
JsonPointerPlus can now be used to navigate `KsonValues`'s!
We want to create our own JsonPointer language which extends the JsonPointer language from RFC 6901 with glob pattern matching. The name JsonPointerGlob captures that intention better.
used `*` spelled out before because it gave issues with kotlin documentation. By escaping one of the `**` we don't run into this anymore
literal tokens in JsonPointerGlob need to be escaped
dmarcotte
reviewed
Jan 14, 2026
Contributor
dmarcotte
left a comment
dmarcotte
left a comment
There was a problem hiding this comment.
I love this @holodorum! Added a few comments, but the headline is: this is fantastic.
src/commonMain/kotlin/org/kson/value/navigation/KsonValueNavigation.kt
Outdated
Show resolved
Hide resolved
src/commonMain/kotlin/org/kson/value/navigation/json_pointer/JsonPointerGlobParser.kt
Outdated
Show resolved
Hide resolved
| } | ||
|
|
||
| // RecursiveDescent already handled remaining tokens, so we're done | ||
| return nextNodes |
Contributor
There was a problem hiding this comment.
This early return looks like it may surprise us in the future... could this be refactored so we either always return the result of the when or only return after we exit it? I'm worried this non-trivial, but not-like-the-others early return will be the root cause of some future bug as this code evolves.
Collaborator
Author
There was a problem hiding this comment.
Gotcha, what do you think of the refactor in c57bee4?
The doc contained an ambiguity where we escaped `/**` with `/\*\*` to prevent starting a new commnet block. However, that's also the way one would escape the asterisk in `JsonPointerGlob`.
the recursive descent was returned early which might surprise us in the future as @dmarcotte pointed out. This refactor makes it more explicit that `RecursiveDescent` tokens are handled differently from the other tokens.
Even though the language of `JsonPointerGlob` seems sensible and intuitive it could well be that we need to update and tweak it a bit. To signal that I've added an Experimental-annotation we opt-in to.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR improves handling of
JsonPointer. Instead of just passing a list of strings we use aJsonPointerclass.JsonPointeralways points to a single value in the document. However, it is useful to point to multiple values with a single 'query' or pointer string. The existing languages that allow for this, for examplejqorJMESPathseem overkill for what we want. We want a simple intuitive syntax. I came up withJsonPointerGlobwhich is a combination ofJsonPointerwith glob like features.JsonPointerGlob extends RFC 6901 JSON Pointer with:
*matches any single key or array index**matches zero or more levels*or**) is treated as a patternExamples:
JsonPointerGlob("")for root documentJsonPointerGlob("/users/*/email")for email of any user (wildcard, use*)JsonPointerGlob("/users/**/email")for all emails at any depth under users (recursive, use**)JsonPointerGlob("/**/email")for all emails anywhere in document (recursive)JsonPointerGlob("/users/*admin*/role")for role of users with "admin" in name (pattern)Recursive descent behavior: