jsonpath

Documentation

Overview

Package jsonpath provides a minimal JSONPath implementation for OpenAPI Overlay support.

This package implements a subset of RFC 9535 JSONPath sufficient for OpenAPI Overlay v1.0.0 specification requirements. It supports path navigation, wildcards, recursive descent, and filter expressions without external dependencies.

Supported syntax:

• $ (root)
• .field or ['field'] (child access)
• .* (wildcard - all children)
• .. (recursive descent - search all descendants)
• ..field (recursive descent for specific field)
• [0] (array index)
• [?@.field==value] (filter with comparison)
• [?@.a==1 && @.b==2] (compound filter with AND)
• [?@.a==1 || @.b==2] (compound filter with OR)

Not supported (planned for future):

• [start:end:step] (array slicing)
• Filter functions like length(), count()

Index

• type ChildSegment
• type FilterExpr
  • func (f *FilterExpr) String() string
• type FilterSegment
• type IndexSegment
• type Path
  • func Parse(expr string) (*Path, error)
  • func (p *Path) Get(doc any) []any
  • func (p *Path) Modify(doc any, fn func(any) any) error
  • func (p *Path) Remove(doc any) (any, error)
  • func (p *Path) Set(doc any, value any) error
  • func (p *Path) String() string
• type RecursiveSegment
• type RootSegment
• type Segment
• type WildcardSegment

Types

type ChildSegment

type ChildSegment struct {
	Key string
}

ChildSegment represents a child property selector (.field or ['field']).

type FilterExpr

type FilterExpr struct {
	// For simple conditions: @.field op value
	Field    string // Field path after @ (e.g., "name" for @.name)
	Operator string // ==, !=, <, >, <=, >=
	Value    any    // The comparison value (string, number, bool, nil)

	// For compound expressions: left && right or left || right
	Left    *FilterExpr // Left operand (nil for simple conditions)
	Right   *FilterExpr // Right operand (nil for simple conditions)
	LogicOp string      // "&&" or "||" (empty for simple conditions)
}

FilterExpr represents a filter expression that can be a simple condition or a compound expression using && or ||.

func (*FilterExpr) String

func (f *FilterExpr) String() string

String returns a string representation of the filter expression.

type FilterSegment

type FilterSegment struct {
	Expr *FilterExpr
}

FilterSegment represents a filter selector ([?expr]).

type IndexSegment

type IndexSegment struct {
	Index int
}

IndexSegment represents an array index selector ([n]).

type Path

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

Path represents a parsed JSONPath expression.

func Parse

func Parse(expr string) (*Path, error)

Parse parses a JSONPath expression string into a Path.

Examples:

Parse("$.info")                    // Navigate to info object
Parse("$.paths['/users'].get")    // Navigate to specific operation
Parse("$.paths.*.get")            // All GET operations
Parse("$.paths.*[?@.x-internal==true]")  // Filter by extension

func (*Path) Get

func (p *Path) Get(doc any) []any

Get evaluates the path against the document and returns all matching values.

The document should be a map[string]any or []any structure (typically from JSON/YAML unmarshaling). Returns an empty slice if no matches are found.

func (*Path) Modify

func (p *Path) Modify(doc any, fn func(any) any) error

Modify applies a transformation function to all matching nodes.

The function receives each matched value and should return the new value. The document is modified in place.

func (*Path) Remove

func (p *Path) Remove(doc any) (any, error)

Remove removes all matching nodes from the document.

Returns the modified document. For maps, matching keys are deleted. For arrays, matching indices are removed (with index shift).

func (*Path) Set

func (p *Path) Set(doc any, value any) error

Set sets the value at all matching locations in the document.

Returns an error if no matches are found or if the path cannot be traversed. The document is modified in place.

func (*Path) String

func (p *Path) String() string

String returns the original JSONPath expression.

type RecursiveSegment

type RecursiveSegment struct {
	// Child is the segment to match at any depth.
	// For $..name, Child is ChildSegment{Key: "name"}
	// For $.., Child is nil (match all descendants)
	Child Segment
}

RecursiveSegment represents recursive descent (..). It searches all descendants for matching children.

type RootSegment

type RootSegment struct{}

RootSegment represents the root selector ($).

type Segment

type Segment interface {
	// contains filtered or unexported methods
}

Segment represents a single segment in a JSONPath expression.

type WildcardSegment

type WildcardSegment struct{}

WildcardSegment represents a wildcard selector (.*).