jsonpointer

README

jsonpointer

---

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

Status

API is stable.

Import this library in your project

go get github.com/go-openapi/jsonpointer

Basic usage

See examples

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

  ...

	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.
	}

  ...

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

The 4.Evaluation part of the previous reference, starting with 'If the currently referenced value is a JSON array, the reference token MUST contain either...' is not implemented.

That is because our implementation of the JSON pointer only supports explicit references to array elements: the provision in the spec to resolve non-existent members as "the last element in the array", using the special trailing character "-" is not implemented.

Documentation

Overview

Package jsonpointer provides a golang implementation for json pointers.

Index

• Constants
• func Escape(token string) string
• func GetForToken(document any, decodedToken string) (any, reflect.Kind, error)
• func SetForToken(document any, decodedToken string, value any) (any, error)
• func Unescape(token string) string
• type JSONPointable
• type JSONSetable
• type Pointer
  • func New(jsonPointerString string) (Pointer, error)
  • func (p *Pointer) DecodedTokens() []string
  • func (p *Pointer) Get(document any) (any, reflect.Kind, error)
  • func (p *Pointer) IsEmpty() bool
  • func (p *Pointer) Offset(document string) (int64, error)
  • func (p *Pointer) Set(document any, value any) (any, error)
  • func (p *Pointer) String() string

Examples

• Pointer.Get
• Pointer.Set

Constants

const (
	// ErrPointer is an error raised by the jsonpointer package
	ErrPointer pointerError = "JSON pointer error"

	// ErrInvalidStart states that a JSON pointer must start with a separator ("/")
	ErrInvalidStart pointerError = `JSON pointer must be empty or start with a "` + pointerSeparator

	// ErrUnsupportedValueType indicates that a value of the wrong type is being set
	ErrUnsupportedValueType pointerError = "only structs, pointers, maps and slices are supported for setting values"
)

Functions

func Escape

func Escape(token string) string

Escape escapes a pointer reference token string

func GetForToken

func GetForToken(document any, decodedToken string) (any, reflect.Kind, error)

GetForToken gets a value for a json pointer token 1 level deep

func SetForToken

func SetForToken(document any, decodedToken string, value any) (any, error)

SetForToken gets a value for a json pointer token 1 level deep

func Unescape

func Unescape(token string) string

Unescape unescapes a json pointer reference token string to the original representation

Types

type JSONPointable

type JSONPointable interface {
	JSONLookup(key string) (any, error)
}

JSONPointable is an interface for structs to implement when they need to customize the json pointer process

type JSONSetable

type JSONSetable interface {
	JSONSet(key string, value any) error
}

JSONSetable is an interface for structs to implement when they need to customize the json pointer process

type Pointer

type Pointer struct {
	// contains filtered or unexported fields
}

Pointer is a representation of a json pointer

func New

func New(jsonPointerString string) (Pointer, error)

New creates a new json pointer for the given string

func (*Pointer) DecodedTokens

func (p *Pointer) DecodedTokens() []string

DecodedTokens returns the decoded tokens of this JSON pointer

func (*Pointer) Get

func (p *Pointer) Get(document any) (any, reflect.Kind, error)

Get uses the pointer to retrieve a value from a JSON document

Example

var doc exampleDocument

if err := json.Unmarshal(testDocumentJSONBytes, &doc); err != nil { // populates doc
	panic(err)
}

pointer, err := New("/foo/1")
if err != nil {
	panic(err)
}

value, kind, err := pointer.Get(doc)
if err != nil {
	panic(err)
}

fmt.Printf(
	"value: %q\nkind: %v\n",
	value, kind,
)

Output:

value: "baz"
kind: string

func (*Pointer) IsEmpty

func (p *Pointer) IsEmpty() bool

IsEmpty returns true if this is an empty json pointer.

This indicates that it points to the root document.

func (*Pointer) Offset

func (p *Pointer) Offset(document string) (int64, error)

func (*Pointer) Set

func (p *Pointer) Set(document any, value any) (any, error)

Set uses the pointer to set a value from a JSON document

Example

var doc exampleDocument

if err := json.Unmarshal(testDocumentJSONBytes, &doc); err != nil { // populates doc
	panic(err)
}

pointer, err := New("/foo/1")
if err != nil {
	panic(err)
}

result, err := pointer.Set(&doc, "hey my")
if err != nil {
	panic(err)
}

fmt.Printf("result: %#v\n", result)
fmt.Printf("doc: %#v\n", doc)

Output:

result: &jsonpointer.exampleDocument{Foo:[]string{"bar", "hey my"}}
doc: jsonpointer.exampleDocument{Foo:[]string{"bar", "hey my"}}

func (*Pointer) String

func (p *Pointer) String() string

String representation of a pointer