jsonata

README

JSONata in Go

Package jsonata is a query and transformation language for JSON. It's a Go port of the JavaScript library JSONata.

It currently has feature parity with jsonata-js 1.5.4. As well as a most of the functions added in newer versions. You can see potentially missing functions by looking at the jsonata-js changelog.

Install

go get github.com/jsonata-go/jsonata

Version Management

This library provides a unified interface for managing multiple versions of JSONata implementations, similar to how the JavaScript JSONata Exerciser allows users to select different versions.

Version Management API

Core Types

• JSONataInstance: Interface representing a specific JSONata version
• Expression: Interface for compiled JSONata expressions

Main Functions

• AvailableVersions() []string: Returns sorted list of available versions
• Open(version string) (JSONataInstance, error): Opens a specific version
• OpenLatest() (JSONataInstance, error): Opens the latest version
• LatestVersion() string: Returns the latest version string

Versioned Usage

import (
	"fmt"
	"log"

	"github.com/jsonata-go/jsonata"
)

const jsonString = `
    {
        "orders": [
            {"price": 10, "quantity": 3},
            {"price": 0.5, "quantity": 10},
            {"price": 100, "quantity": 1}
        ]
    }
`

func main() {
	// Open a specific version
	instance, err := jsonata.Open("v2.0.6")
	if err != nil {
		log.Fatal(err)
	}

	// Create expression.
	e, err := instance.Compile("$sum(orders.(price*quantity))", false)
	if err != nil {
		log.Fatal(err)
	}

	// Evaluate.
	resultJson, err := e.Evaluate([]byte(jsonString), nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(resultJson))
	// Output: 135
}

Direct Usage

import (
	"fmt"
	"log"

	jsonata "github.com/jsonata-go/jsonata/v206"
)

const jsonString = `
    {
        "orders": [
            {"price": 10, "quantity": 3},
            {"price": 0.5, "quantity": 10},
            {"price": 100, "quantity": 1}
        ]
    }
`

func main() {
	// Create expression.
	e, err := jsonata.Compile("$sum(orders.(price*quantity))", false)
	if err != nil {
		log.Fatal(err)
	}

	// Evaluate.
	resultJson, err := e.Evaluate([]byte(jsonString), nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(resultJson))
	// Output: 135
}

API Documentation

For detailed API documentation of the v206 implementation, including all available functions, methods, error handling, and security best practices, see the v206 API Documentation.

Contributing

We love issues, fixes, and pull requests from everyone. Please run the unit-tests, vet, and staticcheck prior to submitting your PR. By participating in this project, you agree to abide by the Blues Inc code of conduct.

For details on contributions we accept and the process for contributing, see our contribution guide.

Documentation

Overview

Package jsonata provides a version management system for multiple JSONata implementations

Index

• func AvailableVersions() []string
• func LatestVersion() string
• func RegisterVersion(version string, factory func() JSONataInstance)
• type Expression
• type JSONataInstance
  • func Open(version string) (JSONataInstance, error)
  • func OpenLatest() (JSONataInstance, error)

Functions

func AvailableVersions

func AvailableVersions() []string

AvailableVersions returns a sorted list of available JSONata versions

func LatestVersion

func LatestVersion() string

LatestVersion returns the latest available version string

func RegisterVersion

func RegisterVersion(version string, factory func() JSONataInstance)

RegisterVersion registers a JSONata version implementation

Types

type Expression

type Expression interface {
	// Evaluate evaluates the expression against JSON input with optional bindings
	Evaluate(inputJSON []byte, bindings map[string]interface{}) ([]byte, error)

	// SetMaxDepth sets the maximum recursion depth
	SetMaxDepth(maxDepth int)

	// SetMaxTime sets the maximum execution time in milliseconds
	SetMaxTime(maxMs int)

	// SetMaxRange sets the maximum range size
	SetMaxRange(maxRange int)

	// Assign assigns a value to a variable in the expression's environment
	Assign(name string, value interface{})

	// RegisterFunction registers a custom function
	RegisterFunction(name string, implementation interface{}, signature string) error

	// AST returns the abstract syntax tree of the expression
	AST() interface{}

	// Errors returns any parser errors (for recovery mode)
	Errors() []error
}

Expression represents a compiled JSONata expression that can be evaluated

type JSONataInstance

type JSONataInstance interface {
	// Version returns the version string of this JSONata instance
	Version() string

	// Compile compiles a JSONata expression string into an executable Expression
	Compile(expr string, recoveryMode bool) (Expression, error)

	// Parse parses a JSONata expression into an AST
	Parse(expr string) (interface{}, error)

	// ParseWithRecovery parses with error recovery enabled
	ParseWithRecovery(expr string) (interface{}, error)

	// RegisterGlobalFunction registers a custom function globally for all expressions
	RegisterGlobalFunction(name string, implementation interface{}, signature string) error

	// SetDefaultMaxDepth sets the global default maximum recursion depth for all new expressions
	SetDefaultMaxDepth(maxDepth int)

	// SetDefaultMaxTime sets the global default maximum execution time for all new expressions (in milliseconds)
	SetDefaultMaxTime(maxMs int)

	// SetDefaultMaxRange sets the global default maximum size for range expressions for all new expressions
	SetDefaultMaxRange(maxRange int)

	// Does this JSON contain the special undefined value?
	IsUndefined(value []byte) bool

	// Make a JSONata error (generally from a user-defined function)
	MakeError(code string, message string) error
}

JSONataInstance represents a specific version of JSONata with its exported APIs

func Open

func Open(version string) (JSONataInstance, error)

Open returns a JSONata instance for the specified version

func OpenLatest

func OpenLatest() (JSONataInstance, error)

OpenLatest returns a JSONata instance for the latest available version