https://github.com/mikhail-barg/jsonata.net.native
.Net native implementation of JSONata query and transformation language (http://jsonata.org)
https://github.com/mikhail-barg/jsonata.net.native
jsonata
Last synced: 5 months ago
JSON representation
.Net native implementation of JSONata query and transformation language (http://jsonata.org)
- Host: GitHub
- URL: https://github.com/mikhail-barg/jsonata.net.native
- Owner: mikhail-barg
- License: mit
- Created: 2021-10-03T10:02:37.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2026-01-15T07:04:48.000Z (5 months ago)
- Last Synced: 2026-01-15T12:45:42.460Z (5 months ago)
- Topics: jsonata
- Language: C#
- Homepage:
- Size: 14.1 MB
- Stars: 56
- Watchers: 3
- Forks: 8
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## About
.Net native implementation of [JSONata](http://jsonata.org) query and transformation language.
* Jsonata.Net.Native [](https://www.nuget.org/packages/Jsonata.Net.Native/)
* Jsonata.Net.Native.JsonNet [](https://www.nuget.org/packages/Jsonata.Net.Native.JsonNet/)
* Jsonata.Net.Native.SystemTextJson [](https://www.nuget.org/packages/Jsonata.Net.Native.SystemTextJson/)
This implementation is based on original [jsonata-js](https://github.com/jsonata-js/jsonata) source and also borrows some ideas from [go port](https://github.com/blues/jsonata-go).
## Performance
This implementation is about 100 times faster than [straightforward wrapping](https://github.com/mikhail-barg/jsonata.net.js) of original jsonata.js with Jint JS Engine for C# (the wrapping is published as [jsonata.net.js package](https://www.nuget.org/packages/Jsonata.Net.Js/)).
For measurements code see [src/BenchmarkApp](https://github.com/mikhail-barg/jsonata.net.native/blob/master/src/BenchmarkApp/Program.cs) in this repo.
## [Usage](https://github.com/mikhail-barg/jsonata.net.native/blob/master/src/TestApp/Program.cs)
### Basic
* simple case
```c#
using Jsonata.Net.Native;
...
JsonataQuery query = new JsonataQuery("$.a");
...
string result = query.Eval("{\"a\": \"b\"}");
Debug.Assert(result == "\"b\"");
```
Since version 2.0.0 this package does not depend on JSON.Net, instead it uses a custom implementation of JSON DOM and parser (see [Jsonata.Net.Native.Json](https://github.com/mikhail-barg/jsonata.net.native/tree/master/src/Jsonata.Net.Native/Json) namespace). This change gave us the following benefits:
* Things got faster (see [here](https://github.com/mikhail-barg/jsonata.net.native/pull/4)).
* More Jsonata features wee implemented and are possible to implement in future.
* No external dependencies for the core Jsonata.Net.Native package (for those who don't use Json.Net in their projects).
Still this custom implementation is modelled on Json.Net, so the following code should look familliar
```c#
using Jsonata.Net.Native;
using Jsonata.Net.Native.Json;
...
JToken data = JToken.Parse("{\"a\": \"b\"}");
...
JToken result = query.Eval(data);
Debug.Assert(result.ToFlatString() == "\"b\"");
```
### [JSON.Net](https://www.newtonsoft.com/json)
In case you work with [JSON.Net](https://www.newtonsoft.com/json) you may use a separate binding package `Jsonata.Net.Native.JsonNet` and its single class [`JsonataExtensions`](https://github.com/mikhail-barg/jsonata.net.native/blob/master/src/Jsonata.Net.Native.JsonNet/JsonataExtensions.cs) to:
* convert token hierarchy to and from Json.Net (`ToNewtonsoft()` and `FromNewtonsoft()`, note the overload version with formatting overrides)
* evaluate Jsonata queries via various `EvalNewtonsoft()` overloads
* bind values to `EvaluationEnvironment` (`BindValue()`)
### [System.Text.Json](https://docs.microsoft.com/en-us/dotnet/standard/serialization/system-text-json-overview)
Same goes for when you use [System.Text.Json](https://docs.microsoft.com/en-us/dotnet/standard/serialization/system-text-json-overview).
Separate binding package `Jsonata.Net.Native.SystemTextJson` provides similar [`JsonataExtensions`](https://github.com/mikhail-barg/jsonata.net.native/blob/master/src/Jsonata.Net.Native.SystemTextJson/JsonataExtensions.cs) class with similar wrappers for both `JsonDocument`/`JsonElement` (static DOM) and `JsonNode` (dynamic DOM).
### Querying C# objects
It is also possible to create a JToken tree representation of existing C# object via `Jsonata.Net.Native.Json.JToken.FromObject()` and then query it with JSONata as a regular JSON.
This may come in handy when you want to give your user some way to get and combine data from your program object model.
In case you want to go deeper and get more control over JSON representation of your objects, you may want to use `Jsonata.Net.Native.JsonNet.JsonataExtensions.FromObjectViaNewtonsoft()` and get all fancy stuff that Json.Net has to offer for this.
Since v2.2.0 there's also a (limited) support for converting JTokens back to C# objects via `JToken.ToObject()`.
## C# Features
* `JsonataQuery` objects are immutable and therefore reusable and thread-safe.
* It is possible to provide additional variable bindings via `bindings` arg of `Eval()` call.
* It is possible to provide additional functional bindings via `Eval(JToken data, EvaluationEnvironment environment)` call. See [example](src/TestApp/Program.cs)
* Functionality is same as for [built-in function implementations](src/Jsonata.Net.Native/Eval/BuiltinFunctions.cs)
* You may use a number of [argument attributes](src/Jsonata.Net.Native/Eval/Attributes.cs) to get fancy behavior if needed. Also refer to [built-in function implementations](src/Jsonata.Net.Native/Eval/BuiltinFunctions.cs)
* Error codes are mostly in sync with the [JS implementation](https://github.com/jsonata-js/jsonata/blob/65e854d6bfee1d1413ebff7f1a185834c6c42265/src/jsonata.js#L1919), but some checkup is to be done later (*TODO*).
We also provide an [Exerciser app](https://github.com/mikhail-barg/jsonata.net.native/tree/master/src/JsonataExerciser) with same functionality as in original [JSONata Exerciser](https://try.jsonata.org/):
## Parsing JSON with Jsonata.Net.Native.Json
As mentioned above, modern versions of Jsonata.Net.Native use custom implementation of JSON DOM and parsing. While re-implementation of JSON object model (JToken hierarchy) has been justified by performance and functionality reasons, writing just another JSON parser from scratch in 2022 looked a bit like re-inventing the wheel. On the other hand, forcing some specific external dependency just for the sake of parsing JSON looked even worse. So here you get just another JSON parser available via [`JToken.Parse()`](https://github.com/mikhail-barg/jsonata.net.native/blob/master/src/Jsonata.Net.Native/Json/JToken.cs) method.
This parser is [being checked](https://github.com/mikhail-barg/jsonata.net.native/tree/master/src/Jsonata.Net.Native.JsonParser.TestSuite) over the following test sets:
* [JSONTestSuite](https://github.com/nst/JSONTestSuite) — most prominent collection of corner case checks for JSON Parsers. Out implementation results are:
* **From "accepted" (`y_`) section:** 95 out of 95 tests are passing (100%).
* **From "rejected" (`n_`) section:** 178 out of 188 tests are passing. 2 tests are causing stackoverflow (those are ones contating 10 000 open square braces). And remaining 14 tests are considered "okay" to fail — which is to parse things that are not being expected to be parsed by strict JSON parsers (eg. numbers like `-.123`).
* **From "ambigous" (`i_`) section:** all 35 tests are not causing the parser to crush miserably (and expected parsing results are not specified for those tests).
* [JSON_checker](http://www.json.org/JSON_checker/) — an official but small json.org's parser tests:
* **From "pass" section:** 3 out of 3 tests are passing.
* **From "fail" section:** 28 out of 33 tests are passing, and remaining 5 are consiered "okay" for same reasons as above.
We have implemented a number of relaxations to "strict" parser spec used in test, like allowing trailing commas, or single-quoted strings. These options are configurable wia [`ParseSettings`](https://github.com/mikhail-barg/jsonata.net.native/blob/master/src/Jsonata.Net.Native/Json/ParseSettings.cs) class. All relaxations are enabled by default.
When facing an invalid JSON, the parser would throw a [`JsonParseException`](https://github.com/mikhail-barg/jsonata.net.native/blob/master/src/Jsonata.Net.Native/Json/JsonParseException.cs)
We have put some effort to this parser, but still the main purpose of the package is not parsing JSON by itself, so in case you need more sophisticated parsing features, like comments (or parsing 10 000 open braces) please use some mature parser package like Json.Net or System.Text.Json and convert results to Jsonata.Net.Native.Json.JToken via routines in a binding package.
## Query DOM introspection and query creation via DOM
Since v2.7.0 we provide access to query DOM via `Node` classes in [Jsonata.Net.Native.Dom namespace](https://github.com/mikhail-barg/jsonata.net.native/tree/master/src/Jsonata.Net.Native/Dom).
Currently it is possible to:
* acquire (readonly) DOM representation of an existing query (via `JsonataQuery.GetDom()` call), and inspect it
* construct new DOM hierarchy and then create a query from it (via `JsonataQuery(Node)` ctor)
* check two DOM (sub)trees for equality (via `Node.Equals(Node?)`)
Please note that right now **DOM API is experimental and subject to change in backwards-incompatible way** without changing major release version of a library.
Some examples may be found [here](https://github.com/mikhail-barg/jsonata.net.native/blob/master/src/Jsonata.Net.Native.Tests/DomTests.cs).
Rationale behind this API is [here](https://github.com/mikhail-barg/jsonata.net.native/issues/26) and [here](https://github.com/mikhail-barg/jsonata.net.native/issues/28).
## JSONata language features support
The goal of the project is to implement 100% of latest JSONata version ([1.8.5](https://github.com/jsonata-js/jsonata/releases/tag/v1.8.5) at the moment of writing these words), but it's still work in progress. Here's is a list of features in accordance to [manual](https://docs.jsonata.org/):
* :heavy_check_mark: [Simple Queries](https://docs.jsonata.org/simple) with support to arrays and sequence flattening.
* :heavy_check_mark: [Predicate Queries](https://docs.jsonata.org/predicate), singleton arrays and wildcards.
* :heavy_check_mark: [Functions and Expressions](https://docs.jsonata.org/expressions).
* :heavy_check_mark: [Result Structures](http://docs.jsonata.org/construction).
* :heavy_check_mark: [Query Composition](http://docs.jsonata.org/composition).
* :heavy_check_mark: [Sorting, Grouping and Aggregation](http://docs.jsonata.org/sorting-grouping).
* :white_check_mark: [Processing Model](http://docs.jsonata.org/processing) - Index (`seq#$var`) and Join (`seq@$var`) operators are not yet implemented (*TODO*).
* :white_check_mark: [Functional Programming](http://docs.jsonata.org/programming) - Conditional operator, variables and bindings are implemented, as well as defining custom functions.
Function signatures are parsed but not checked yet (*TODO*). Recursive functions are supported, but additional checks are needed here (*TODO*). Tail call optimization is not supported.
Higher order functions are supported. 'Functions are closures', 'Partial function application' and 'Function chaining' features are supported.
* :white_check_mark: [Regular Expressions](http://docs.jsonata.org/regex) - all is implemented, except for the unusual handling for excessive group indices in [`$replace()`](http://docs.jsonata.org/string-functions#replace) (_If N is greater than the number of captured groups, then it is replaced by the empty string_) which is not supported by .Net [`Regex.Replace()`](https://docs.microsoft.com/en-us/dotnet/api/system.text.regularexpressions.regex.replace?view=net-6.0).
Also `match` object does not yet have `next` property (*TODO*).
* :heavy_check_mark: [Date/Time Processing](http://docs.jsonata.org/date-time) - All functions are implemented.
###### Operators
* :white_check_mark: [Path Operators](http://docs.jsonata.org/path-operators):
* :heavy_check_mark: `.` (Map)
* :heavy_check_mark: `[ ... ]` (Filter)
* :heavy_check_mark: `^( ... )` (Order-by)
* :heavy_check_mark: `{ ... }` (Reduce)
* :heavy_check_mark: `*` (Wildcard)
* :heavy_check_mark: `**` (Descendants)
* :heavy_check_mark: `%` (Parent) - done, expect for [this issue](https://github.com/jsonata-js/jsonata/issues/645)
* :white_check_mark: `#` (Positional variable binding) - (*TODO*)
* :white_check_mark: `@` (Context variable binding) - (*TODO*)
* :heavy_check_mark: [Numeric Operators](http://docs.jsonata.org/numeric-operators) - all, including `..` (Range) operator.
* :heavy_check_mark: [Comparison Operators](http://docs.jsonata.org/comparison-operators) - all, including `in` (Inclusion) operator.
* :heavy_check_mark: [Boolean Operators](http://docs.jsonata.org/boolean-operators).
* :heavy_check_mark: [Other Operators](http://docs.jsonata.org/other-operators):
* :heavy_check_mark: `&` (Concatenation)
* :heavy_check_mark: `?` : (Conditional)
* :heavy_check_mark: `:=` (Variable binding)
* :heavy_check_mark: `~>` (Chain)
* :heavy_check_mark: `... ~> | ... | ... |` (Transform)
###### Function Library
* :heavy_check_mark: [String Functions](http://docs.jsonata.org/string-functions):
* :heavy_check_mark: Implemented: `$string()`, `$length()`, `$substring()`, `$substringBefore()`, `$substringAfter()`, `$uppercase()`, `$lowercase()`, `$trim()`, `$pad()`, `$contains()`, `$split()`, `$join()`, `$match()`, `$replace()`, `$eval()`, `$base64encode()`, `$base64decode()`, `$encodeUrlComponent()`, `$encodeUrl()`, `$decodeUrlComponent()`, `$decodeUrl()`
* :white_check_mark: There's a discrepancy when handling UTF-16 surrogate pairs. For example `$length("\uD834\uDD1E")` would return 2, while in original Jsonata-JS it would return 1.
* :heavy_check_mark: [Numeric Functions](http://docs.jsonata.org/numeric-functions):
* :heavy_check_mark: Implemented: `$number()`, `$abs()`, `$floor()`, `$ceil()`, `$round()`, `$power()`, `sqrt()`, `$random()`, `$formatNumber()`, `$formatBase()`, `$formatInteger()`, `$parseInteger()`
* :white_check_mark: Using C# [custom](https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-numeric-format-strings) and [standard](https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings) format strings for `picture` argument of `$formatNumber()`, `$formatInteger()` and `$parseInteger()` instead of [XPath format](https://docs.jsonata.org/numeric-functions#formatnumber) used in JSonataJS.
* :heavy_check_mark: [Aggregation Functions](http://docs.jsonata.org/aggregation-functions):
* :heavy_check_mark: Implemented: `$sum()`, `$max()`, `$min()`, `$average()`
* :heavy_check_mark: [Boolean Functions](http://docs.jsonata.org/boolean-functions):
* :heavy_check_mark: Implemented: `$boolean()`, `$not()`, `$exists()`
* :heavy_check_mark: [Array Functions](http://docs.jsonata.org/array-functions):
* :heavy_check_mark: Implemented: `$count()`, `$append()`, `$sort()`, `$reverse()`, `$shuffle()`, `$distinct()`, `$zip()`
* :heavy_check_mark: [Object Functions](http://docs.jsonata.org/object-functions):
* :heavy_check_mark: Implemented: `$keys()`, `$lookup()`, `$spread()`, `$merge()`, `$sift()`, `$each()`, `$error()`, `$assert()`, `$type()`
* :heavy_check_mark: [Date/Time functions](http://docs.jsonata.org/date-time-functions):
* :heavy_check_mark: Implemented: `$now()`, `$millis()`, `$fromMillis()`, `$toMillis()`
* :white_check_mark: Using C# [custom](https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings) and [standard](https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings) format strings for `picture` argument instead of [XPath format](https://docs.jsonata.org/date-time-functions#tomillis) used in JSonataJS.
* :heavy_check_mark: [Higher Order Functions](http://docs.jsonata.org/higher-order-functions):
* :heavy_check_mark: Implemented: `$map()`, `$filter()`, `$single()`, `$reduce()`, `$sift()`
Also, need to check all `TODO:` markers in the code (*TODO*).
#### Detailed results for the reference test suite
We [use](https://github.com/mikhail-barg/jsonata.net.native/tree/master/src/Jsonata.Net.Native.TestSuite) the test suite from [original JSONata JS implementation](https://github.com/jsonata-js/jsonata/blob/master/test/test-suite/TESTSUITE.md) to check consistency and completeness of the port.
Current test results for the latest test run are:
* 
[Full](https://github.com/mikhail-barg/jsonata.net.native/blob/master/src/Jsonata.Net.Native.TestSuite/TestReport/Jsonata.Net.Native.TestSuite.xml) and [brief](https://github.com/mikhail-barg/jsonata.net.native/blob/master/src/Jsonata.Net.Native.TestSuite/TestReport/extract.txt) test reports are also in the repo.
Below are current states of each test group in the suite:
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 