jsonpointer

An implementation of JSON Pointer for golang, which supports go struct.

Announcements

• 2026-04-15 : added support for trailing “-” for arrays (v0.23.0)

  • this brings full support of RFC6901
  • this is supported for types relying on the reflection-based implemented
  • API semantics remain essentially unaltered. Exception: Pointer.Set(document any,value any) (document any, err error) can only perform a best-effort to mutate the input document in place. In the case of adding elements to an array with a trailing “-”, either pass a mutable array (*[]T) as the input document, or use the returned updated document instead.
  • types that implement the JSONSetable interface may not implement the mutation implied by the trailing “-”

• 2026-04-15 : added support for optional alternate JSON name providers

  • for struct support the defaults might not suit all situations: there are known limitations when it comes to handle untagged fields or embedded types.
  • the default name provider in use is not fully aligned with go JSON stdlib
  • exposed an option (or global setting) to change the provider that resolves a struct into json keys
  • the default behavior is not altered
  • a new alternate name provider is added (imported from go-openapi/swag/jsonname), aligned with JSON stdlib behavior

Status

API is stable and feature-complete.

Import this library in your project

go get github.com/go-openapi/jsonpointer

Basic usage

See also some examples

Retrieving a value

  import (
    "github.com/go-openapi/jsonpointer"
  )


  var doc any

  ...

	pointer, err := jsonpointer.New("/foo/1")
	if err != nil {
		... // error: e.g. invalid JSON pointer specification
	}

	value, kind, err := pointer.Get(doc)
	if err != nil {
		... // error: e.g. key not found, index out of bounds, etc.
	}

  ...

Setting a value

  ...
  var doc any
  ...
	pointer, err := jsonpointer.New("/foo/1")
	if err != nil {
		... // error: e.g. invalid JSON pointer specification
  }

	doc, err = p.Set(doc, "value")
	if err != nil {
		... // error: e.g. key not found, index out of bounds, etc.
	}

Change log

See https://github.com/go-openapi/jsonpointer/releases

References

https://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07

also known as RFC6901.

Licensing

This library ships under the SPDX-License-Identifier: Apache-2.0.

See the license NOTICE, which recalls the licensing terms of all the pieces of software on top of which it has been built.

Limitations

• RFC6901 is now fully supported, including trailing “-” semantics for arrays (for Set operations).
• Default behavior: JSON name detection in go structs
  • Unlike go standard marshaling, untagged fields do not default to the go field name and are ignored.
  • anonymous fields are not traversed if untagged
  • the above limitations may be overcome by calling UseGoNameProvider() at initialization time.
  • alternatively, users may inject the desired custom behavior for naming fields as an option.

Other documentation

• All-time contributors
• Contributing guidelines
• Maintainers documentation
• Code style

Cutting a new release

Maintainers can cut a new release by either:

• running this workflow
• or pushing a semver tag
  • signed tags are preferred
  • The tag message is prepended to release notes