Skip to content

Implement RFC 6901 JSON Pointer as json-java21-jsonpointer module#149

Draft
simbo1905 with Copilot wants to merge 2 commits into
mainfrom
copilot/implement-rfc-6901-json-pointer
Draft

Implement RFC 6901 JSON Pointer as json-java21-jsonpointer module#149
simbo1905 with Copilot wants to merge 2 commits into
mainfrom
copilot/implement-rfc-6901-json-pointer

Conversation

Copilot AI commented Jul 9, 2026

Copy link
Copy Markdown
Contributor

Adds a new json-java21-jsonpointer module implementing RFC 6901 JSON Pointer — the exact-address path syntax used by JSON Patch. Single runtime dependency: sibling json-java21.

What changed

New module: json-java21-jsonpointer

  • JsonPointerparse(), resolve(), exists(), tokens(), toString()
  • JsonPointerSyntaxException — malformed pointer (no leading /, invalid ~ escape)
  • JsonPointerResolutionException — pointer valid but target absent (missing key, OOB index, non-numeric array token, traversal into primitive)
  • JsonPointerLoggingConfig — standard JUL logging base for tests, matching sibling modules

RFC 6901 §5 example table — all 12 entries covered:

JsonValue doc = Json.parse("""
    {"foo":["bar","baz"],"":0,"a/b":1,"m~n":8}
    """);

JsonPointer.parse("").resolve(doc);       // whole document
JsonPointer.parse("/foo/0").resolve(doc); // "bar"
JsonPointer.parse("/").resolve(doc);      // 0  (empty-string key)
JsonPointer.parse("/a~1b").resolve(doc);  // 1  (~1 decodes to /)
JsonPointer.parse("/m~0n").resolve(doc);  // 8  (~0 decodes to ~)

// Escape ordering: ~01 → ~1 (not /)
JsonPointer.parse("/foo").exists(doc);    // true
JsonPointer.parse("/missing").exists(doc); // false

Key behaviours:

  • Escape decoding order mandated by RFC: ~1→/ first, ~0→~ second (so ~01~1)
  • - token correctly not resolvable under RFC 6901 (RFC 6902 append sentinel only)
  • Leading-zero array indices ("01") rejected per RFC 6901 §4
  • parse(p).toString() always round-trips

Module structure mirrors json-java21-jsonpath and json-java21-jtd exactly — same pom.xml shape, compiler flags (-Xlint:all -Werror), package convention, and doc style (JEP 467 ///).

Why this change is needed

JSON Pointer is the path/address syntax used by JSON Patch (RFC 6902) and needed as a foundation for future patch support. It is also useful standalone for navigating JSON documents by exact address.

How were these changes tested

51 unit tests covering: all RFC §5 example table entries, escape ordering edge cases, tokens() / exists() / toString() accessors, syntax rejection, resolution failures (missing key, OOB, non-numeric token, primitive traversal, - token, leading-zero index), and nested document resolution via parameterized cases.

Checklist

  • Code builds / passes tests
  • New tests added if needed
  • Update to use CODING_STYLE_LLM.md convensions
  • Documentation updated if needed
  • AGENTS.md updated if appropriate

Copilot AI added 2 commits July 9, 2026 16:06
Add a new Maven module json-java21-jsonpointer that implements RFC 6901
JSON Pointer.  It depends only on the sibling json-java21 library.

Public API:
  JsonPointer.parse(String)       – validates syntax, returns JsonPointer
  JsonPointer.resolve(JsonValue)  – resolves or throws JsonPointerResolutionException
  JsonPointer.exists(JsonValue)   – returns boolean
  JsonPointer.tokens()            – decoded reference token list
  JsonPointer.toString()          – canonical pointer string (round-trips)

  JsonPointerSyntaxException      – bad pointer syntax
  JsonPointerResolutionException  – pointer cannot be resolved against a document

All 12 RFC 6901 §5 example table entries pass.  51 unit tests pass.
Compiler configured with -Xlint:all -Werror; zero warnings.

To verify:
  mvn -pl json-java21-jsonpointer -am -Djava.util.logging.ConsoleHandler.level=INFO test
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants