json_path_plus #

A Dart port of JSONPath-Plus — a full-featured JSONPath query engine with filter expressions, type operators, array slices, and safe expression evaluation.

Features #

• Basic path syntax: dot notation, bracket notation, wildcards, recursive descent (..)
• Filter expressions: [?(@.price > 10)] with @property, @parent, @root, @path
• Type operators: @string(), @number(), @boolean(), @integer(), @null(), @array(), @object(), @scalar(), @other()
• ~ property-name operator: returns the key name instead of value
• ^ parent selector: returns the parent of the matched node
• Array slices: Python-style [start:end:step]
• Dynamic properties: [(1+2)] evaluates to index 3
• Comma-separated keys: [0,1] selects multiple indices
• Backtick-escaped properties: `0` for literal property lookup
• Multiple result types: value, path, pointer, parent, parentProperty, all
• Safe expression evaluator: No dart:mirrors, no eval(), no external dependencies

Getting started #

Install #

Add to your pubspec.yaml:

dependencies:
  json_path_plus: ^1.0.0

Then run:

dart pub get

Requirements #

• Dart SDK 3.0+ (sound null safety)
• Zero external runtime dependencies
• Flutter-compatible (no dart:mirrors)

Usage #

Basic queries #

import 'package:json_path_plus/json_path_plus.dart';

final data = {
  'store': {
    'book': [
      {'title': 'Sayings of the Century', 'price': 8.95},
      {'title': 'Moby Dick', 'price': 12.99},
      {'title': 'The Lord of the Rings', 'price': 22.99},
    ],
  },
};

// Simple query — returns all titles
final titles = JSONPath.query(r'$.store.book[*].title', data);
print(titles); // ['Sayings of the Century', 'Moby Dick', 'The Lord of the Rings']

// Filter: books over $10
final expensive = JSONPath.query(r'$.store.book[?(@.price > 10)].title', data);
print(expensive); // ['Moby Dick', 'The Lord of the Rings']

// With full options — get paths instead of values
final result = JSONPath.evaluate(JsonPathOptions(
  path: r'$..book[?(@.price > 10)]',
  json: data,
  resultType: 'path',
));
print(result); // ["$['store']['book'][1]", "$['store']['book'][2]"]

Walgreens-style @property filter #

Match keys dynamically using @property in filter expressions:

final data = {
  'productInfo': {
    'filmStripUrl': [
      {'stripUrl1': '...', 'zoomImageUrl1': '//pics.example.com/image1.jpg'},
      {'stripUrl2': '...', 'zoomImageUrl2': '//pics.example.com/image2.jpg'},
    ],
  },
};

final zoomUrls = JSONPath.evaluate(JsonPathOptions(
  path: r'$.productInfo.filmStripUrl[*][?(@property.indexOf("zoomImageUrl") === 0)]',
  json: data,
));
print(zoomUrls); // ['//pics.example.com/image1.jpg', '//pics.example.com/image2.jpg']

Array slice #

final sliced = JSONPath.query(r'$[1:4:2]', [0, 1, 2, 3, 4, 5]);
print(sliced); // [1, 3]

Type operator filter #

final strings = JSONPath.query(
  r'$[?(@string())]',
  ['hello', 42, true, null, 'world'],
);
print(strings); // ['hello', 'world']

API #

JSONPath.evaluate(options) #

The main evaluation entry point. Accepts either a JsonPathOptions object or positional arguments.

static dynamic evaluate(
  Object? pathOrOpts, [
  Object? json,
  void Function(Object?, String, JsonPathMatch)? callback,
  Object? Function(Object?, List<String>, Object?, String?)? otherTypeCallback,
])

JSONPath.query(path, json, {wrap}) #

Shorthand for value-only queries. Always returns List<Object?>.

static List<Object?> query(String path, Object json, {bool wrap = true})

JSONPath.toPathArray(expr) / toPathString(path) / toPointer(path) #

Convert between path representations:

JSONPath.toPathArray(r"$['store']['book'][0]['title']");
// → ['$', 'store', 'book', '0', 'title']

JSONPath.toPathString(['$', 'store', 'book', '0', 'title']);
// → "$['store']['book'][0]['title']"

JSONPath.toPointer(['$', 'store', 'book', '0', 'title']);
// → '/store/book/0/title'

JsonPathOptions #

JsonPathMatch #

class JsonPathMatch {
  final Object? value;      // The matched value
  final String path;         // The path string
  final List<String>? paths; // Path components
  final Object? parent;      // Parent object
  final String? property;    // Property name
  Object? pointer;           // JSON Pointer
}

SafeEval #

The safe expression evaluator for filter conditions. Supports arithmetic, comparison, logical operators, and string concatenation — without dart:mirrors or eval().

final result = SafeEval.evaluate('1 + 2 * 3 > 5 && "hello" + " world"');
// → true

Constraints #

• Zero external runtime dependencies (only dart:core, dart:math, dart:convert)
• Sound null safety (Dart 3.x, SDK >=3.0.0 <4.0.0)
• No dart:mirrors (Flutter-compatible)
• No eval() or Function.apply() — uses a custom expression parser

Similar packages #

• json_path — Another JSONPath implementation for Dart with a different feature set
• json_path_plus — This package, a Dart port of JSONPath-Plus with extended operators
• json5_plus — JSON5 parser (by the same team)
• zikzak_json — Best-effort JSON parser with simdjson fallback (by the same team)

Powered by ZikZak AI #

json_path_plus is developed by ZikZak AI to serve as the JSONPath query engine for high-throughput data extraction workloads.

• 🌐 zuzu.dev
• 🐙 GitHub
• 🐛 Issue Tracker

Sponsors #

Thanks to ZikZak AI for sponsoring this project!

ZikZak AI is an AI-Powered Price Comparison app that you scan barcodes, and discover amazing savings instantly. Your personal shopping assistant that never sleeps.

Licensed under the MIT License.