jsonpointer

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

Announcements

• 2026-06-29 : reinsourced external dependency to swag (v0.24.0)
• module github.com/go-openapi/swag/jsonname is source directly here, so we no longer have any external dependency

• jsonname was never really used by any other package, so it makes sense to deprecate it away from the swag family and retrofit its functionality here. jsonpointer no longer get external dependencies, besides test dependencies.

• 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

Status

API is stable and feature-complete.

The project continues to receive regular updates, bug fixes and hygiene maintenance (CI, linting, etc).

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