Release v2.2.3

Release v2.2.3

Highlights: the jsonata/jsonatapy CLI

This release ships the command-line interface for both packages for the first
time — a jq-shaped tool where a single JSONata expression can filter,
aggregate, and reshape data that would otherwise need several piped jq
filters, with path syntax that will look familiar if you've used JSONPath.

• jsonata (Rust binary, from jsonata-core) and jsonatapy (Python
  console script, from pip install jsonatapy) share an identical
  flag/exit-code contract — -c/--compact, -r/--raw-output,
  -n/--null-input, -f/--from-file, --arg/--argjson bindings.
  See the new CLI Reference.
• Prebuilt jsonata binaries are attached to this release for Linux
  (x86_64/aarch64), Windows (x86_64), and macOS (aarch64) — download and run,
  no Rust toolchain required. (Or cargo install jsonata-core --features cli.)
• jsonatapy mcp runs an MCP server
  exposing JSONata evaluation as tools for AI agents (pip install 'jsonatapy[mcp]').
• Library addition: evaluate_json_or_none()'s json_str parameter now
  accepts None, binding the top-level context ($) to a true JSONata
  Undefined — which is what -n/--null-input uses under the hood so $
  behaves identically across both CLIs.

Changes

• Merge pull request #69 from txjmb/ci/gate-release-on-cli-binaries (cd7d2eb)
• ci(release): gate registry publishes on CLI binary build; version archive names (6567728)
• Merge pull request #68 from txjmb/fix/cli-null-input-parity (a36d67f)
• docs: add CLI reference; changelog entries for the -n parity fix (d3db633)
• fix(cli): -n binds $ to true Undefined, not null (638f556)
• Update README.md (5b7952d)
• Merge pull request #67 from txjmb/worktree-python-cli-phase2 (c50c504)
• fix: reject NaN/Infinity/overflow in --argjson values (exit 2) (f3538cb)
• fix: address three cross-task findings from whole-branch final review (f69218f)
• feat(pycli): add explain tool with curated JSONata reference content (22acf0b)
• fix(pycli): set run_in_thread=False on MCP tools to avoid PyO3 unsendable drops (39b0f12)
• feat(pycli): add FastMCP server (evaluate/validate/evaluate_batch) and jsonatapy mcp dispatch (f8f61d6)
• test(pycli): run the shared study/cli_fixtures.json suite against the Python CLI (5559679)
• test(pycli): close out exit-code contract coverage; document null-context divergence (2e0c90f)
• docs(plans): fix Task 7's null-context pinning expression (75cd703)
• feat(pycli): add --arg/--argjson bindings and code-preserving error formatting (d4cbe96)
• feat(pycli): add -c/--compact and -r/--raw-output flags (c808e32)
• feat(pycli): evaluate expressions against stdin/file JSON input via evaluate_json_or_none (6687f1e)
• chore: regenerate uv.lock for fastmcp/pytest-asyncio optional-dependency resolution (7bef8a0)
• feat(py-api): add evaluate_json_or_none to distinguish Undefined from null (66fd48d)
• feat(pycli): add resolve.py, the single source of truth for input/expression resolution (c81ec96)
• feat(pycli): scaffold jsonatapy console script with --version/--help (511f4d7)
• docs(plans): add Phase 2 implementation plan (Python CLI + FastMCP server) (1beeb20)
• Merge pull request #66 from txjmb/worktree-rust-cli-phase1 (4cbc1cc)
• docs(specs): drop the unverified position field from validate's MCP tool signature (1085206)
• docs(specs): decouple Java/.NET binding phases from the agentic study gate (b92b70e)
• fix(cli): validate --arg/--argjson before reading input or parsing expression (4455f6f)
• ci(release): build and publish jsonata CLI binaries (8f24ef6)
• fix(cli): correct two fixture cases per review (eb9dd45)
• docs(cli): add shared CLI spec + fixture suite for Phase 2 parity (ea7ba65)
• test(cli): close out exit-code contract coverage (a25d365)
• feat(cli): add --arg/--argjson bindings; extract shared error message accessors (14d59ca)
• feat(cli): add -f/--from-file expression source (6c15201)
• feat(cli): add -n/--null-input and the positional-argument resolver (7b24bda)
• feat(cli): add -c/--compact and -r/--raw-output flags (1dfe6b2)
• feat(cli): evaluate expressions against stdin/file JSON input (55ca9bf)
• fix(cli): apply cargo fmt; gate cli_test.rs behind the cli feature (f22fb92)
• feat(cli): scaffold jsonata binary with --version/--help (683ff44)
• docs(plans): extract shared error accessors instead of duplicating in CLI (fc717fc)
• docs: add Phase 1 CLI implementation plan; require C/C++ shared-lib docs (f805ee6)
• docs(specs): correct CLI error-format claim against actual error types (2e0d540)
• docs(specs): design multi-language surface, agentic CLI, and jq study (f17b3b1)
• docs(benchmarks): update performance.md for v2.2.2 (1683cbf)

Test Suite Compatibility

See the README for the current
reference-suite pass count -- this changelog no longer hardcodes a number here, since a
stale hardcoded count is exactly the kind of bug this project has previously shipped
and had to correct.

Installation

pip install jsonatapy==2.2.3

Verification

import jsonatapy
print(jsonatapy.__version__)  # Should print: 2.2.3