jsonpointer

JSON Pointer

A read-only JSON Pointer (RFC 6901) library for Go that traverses maps, slices, arrays, structs, and pointers with explicit errors

Features

• RFC 6901 semantics: Parse, format, escape, unescape, and validate JSON Pointer strings with the expected token rules
• Go-native traversal: Read map[string]any, slices, arrays, structs, and pointers without converting everything to generic JSON first
• Explicit errors: Distinguish missing keys, missing struct fields, invalid indexes, nil pointers, and generic traversal failures
• Small API: Learn Get, Find, GetByPointer, FindByPointer, and a handful of path helpers
• Fast common paths: Optimize map[string]any and []any reads while keeping reflective fallbacks for typed Go values
• Benchmarked and tested: Includes package tests, executable examples, fuzz tests, and benchmark comparisons

Installation

go get github.com/kaptinlin/jsonpointer

Requires Go 1.26+.

Quick Start

package main

import (
	"fmt"
	"log"

	"github.com/kaptinlin/jsonpointer"
)

func main() {
	doc := map[string]any{
		"users": []any{
			map[string]any{"name": "Alice"},
		},
	}

	name, err := jsonpointer.GetByPointer(doc, "/users/0/name")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(name)
}

Core APIs

GetByPointer and FindByPointer do not call Validate automatically. If you need strict pointer syntax checks before traversal, call Validate explicitly.

Reference Results

Find and FindByPointer return a Reference:

Use IsArrayReference and IsObjectReference when you need to inspect the returned parent context.

Examples

Read by path tokens

doc := map[string]any{
	"users": []any{
		map[string]any{"name": "Alice"},
	},
}

name, err := jsonpointer.Get(doc, "users", "0", "name")
if err != nil {
	log.Fatal(err)
}
fmt.Println(name)

Read by pointer string

doc := map[string]any{
	"foo/bar": map[string]any{
		"tilde~key": "ready",
	},
}

ref, err := jsonpointer.FindByPointer(doc, "/foo~1bar/tilde~0key")
if err != nil {
	log.Fatal(err)
}
fmt.Println(ref.Val)
fmt.Println(ref.Key)

Traverse structs and pointers

type User struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}

user := &User{Name: "Alice", Email: "alice@example.com"}
email, err := jsonpointer.Get(user, "email")
if err != nil {
	log.Fatal(err)
}
fmt.Println(email)

Work with path utilities

path := jsonpointer.Parse("/foo~1bar/tilde~0key")
fmt.Println(path)
fmt.Println(jsonpointer.Format(path...))
fmt.Println(jsonpointer.Validate("/foo~1bar/tilde~0key") == nil)

The examples in this README are mirrored in example_test.go so go test checks they stay correct.

Error Handling

Common sentinel errors include:

• ErrKeyNotFound
• ErrFieldNotFound
• ErrInvalidIndex
• ErrIndexOutOfBounds
• ErrNilPointer
• ErrNotFound
• ErrPointerInvalid
• ErrPointerTooLong
• ErrPathTooLong

Use errors.Is when checking traversal and validation failures.

Performance

The package optimizes common map[string]any and []any reads and falls back to reflection for typed Go values. See benchmarks/README.md for comparison data and benchmark coverage.

Run benchmarks with:

task bench

Development

task test          # Run package tests with the race detector
task lint          # Run golangci-lint and tidy checks
task markdownlint  # Lint Markdown files
task yamllint      # Lint YAML files
task bench         # Run benchmarks

Run the demo program with:

go run ./examples

For development workflow and package contracts, see AGENTS.md and SPECS/.

Contributing

Contributions are welcome. Keep README.md, example_test.go, and the relevant SPECS/ documents aligned when public behavior changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.