JSON Logic to SQL Transpiler

A Go library that converts JSON Logic expressions into SQL. This library provides a clean, type-safe API for transforming JSON Logic rules into SQL WHERE clauses or standalone conditions, with support for multiple SQL dialects.

Features

• Complete JSON Logic Support: Implements all core JSON Logic operators
• SQL Dialect Support: Target BigQuery, Spanner, PostgreSQL, DuckDB, or ClickHouse
• Parameterized Queries: Generate SQL with bind placeholders (@p1, $1) and separate parameter values for safe execution
• Custom Operators: Extensible registry pattern for custom SQL functions
• Schema Validation: Optional field schema for strict column validation
• Structured Errors: Error codes and JSONPath locations for debugging
• Regression Matrices: Cross-dialect schema-aware/schema-less matrix tests for nested built-in and custom operator flows
• Array Scope Safety: Nested array operators keep inner/outer element aliases distinct where required
• Library & CLI: Both programmatic API and interactive REPL

Quick Start

go get github.com/h22rana/jsonlogic2sql@latest

Inline SQL

package main

import (
    "fmt"
    "github.com/h22rana/jsonlogic2sql"
)

func main() {
    sql, err := jsonlogic2sql.Transpile(
        jsonlogic2sql.DialectBigQuery,
        `{">": [{"var": "amount"}, 1000]}`,
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(sql) // Output: WHERE amount > 1000
}

Parameterized Queries

package main

import (
    "fmt"
    "github.com/h22rana/jsonlogic2sql"
)

func main() {
    sql, params, err := jsonlogic2sql.TranspileParameterized(
        jsonlogic2sql.DialectBigQuery,
        `{"and": [{"==": [{"var": "status"}, "active"]}, {">": [{"var": "amount"}, 1000]}]}`,
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(sql)    // Output: WHERE (status = @p1 AND amount > @p2)
    fmt.Println(params) // Output: [{p1 active} {p2 1000}]
}

Supported Operators

Category	Operators
Data Access	var, missing, missing_some
Comparison	==, ===, !=, !==, >, >=, <, <=
Logical	and, or, !, !!, if
Numeric	+, -, *, /, %, max, min
Array	in, map, filter, reduce, all, some, none, merge
String	in, cat, substr

Supported Dialects

Dialect	Constant
Google BigQuery	DialectBigQuery
Google Cloud Spanner	DialectSpanner
PostgreSQL	DialectPostgreSQL
DuckDB	DialectDuckDB
ClickHouse	DialectClickHouse

Documentation

• Getting Started - Installation and basic usage
• Parameterized Queries - Bind-parameter output for safe SQL execution
• Operators - All supported operators with examples
• SQL Dialects - Dialect-specific SQL generation
• Custom Operators - Extend with your own operators
• Schema Validation - Field validation and type checking
• Examples - Comprehensive examples
• API Reference - Full API documentation
• Error Handling - Error codes and programmatic handling
• Development - Contributing and development guide
• REPL - Interactive testing tool
• WASM Playground - Browser-based demo via WebAssembly

Important Notes

Semantic Correctness Assumption: This library assumes that the input JSONLogic is semantically correct. The transpiler generates SQL that directly corresponds to the JSONLogic structure without validating the logical correctness of the expressions.

SQL Injection: This library includes hardening measures against SQL injection - identifier names are validated against a whitelist pattern, string literals are escaped, and numeric string operands are safely coerced. For maximum safety, use the parameterized query API which generates SQL with bind placeholders instead of inlined literals.

in Operator Inference: Without a schema, in uses heuristics to infer string containment vs array membership. For deterministic behavior (especially with complex expressions), prefer schema-aware mode.

Interactive REPL

make run

[BigQuery] jsonlogic> {">": [{"var": "amount"}, 1000]}
SQL: WHERE amount > 1000

[BigQuery] jsonlogic> :params
Parameterized mode: ON (output uses bind placeholders)

[BigQuery] jsonlogic> {"==": [{"var": "status"}, "active"]}
SQL:    WHERE status = @p1
Params: [{p1: "active"}]

[BigQuery] jsonlogic> :dialect
Select dialect: PostgreSQL

[PostgreSQL] jsonlogic> {"merge": [{"var": "a"}, {"var": "b"}]}
SQL: WHERE (a || b)

Development

make test       # Run all tests (including cross-dialect matrix suites)
make bench      # Run benchmarks
make build      # Build REPL binary
make build/wasm # Build WASM binary for browser playground
make lint       # Run linter
make run        # Run REPL

License

This project is licensed under the MIT License - see the LICENSE file for details.