https://github.com/telekom/json-filter
JSON filter is a small, lightweight filter-library that allows to evaluate JSON payload against a filter consisting of operators.
https://github.com/telekom/json-filter
filter json
Last synced: about 1 year ago
JSON representation
JSON filter is a small, lightweight filter-library that allows to evaluate JSON payload against a filter consisting of operators.
- Host: GitHub
- URL: https://github.com/telekom/json-filter
- Owner: telekom
- Created: 2024-01-22T10:14:46.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-14T10:12:39.000Z (about 1 year ago)
- Last Synced: 2025-05-05T23:54:01.908Z (about 1 year ago)
- Topics: filter, json
- Language: Java
- Homepage:
- Size: 194 KB
- Stars: 7
- Watchers: 4
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSES/Apache-2.0.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# JSON Filter
[](https://api.reuse.software/info/github.com/telekom/JSON-Filter)
[](https://github.com/telekom/JSON-Filter/issues)
[](https://central.sonatype.com/artifact/de.telekom/json-filter)
## About
JSON filter is a small, lightweight filter-library that allows to evaluate JSON payload against a filter consisting of
operators.
Operators can be defined programmatically or in JSON- or YAML-files.
The evaluation of JSON payloads against a filter results in an EvaluationResult, which indicates why a filter failed.
## Usage
There are two types of operators: comparison- and logical-operators.
### Comparison operators
Comparison-operators are used to compare a JSON path against an expected value.
Comparison-operators consist of three fields, `operator`, `field` and `value`.
`operator` is the operator to be used for the comparison ([available operators](#available-operators)).
`field` is the JSON-path to be evaluated.
`value` is the expected value.
An example can be found below:
```json
{
"": {
"field": "",
"value": ""
}
}
```
### Logic operators
Logical operators are used to combine multiple operators.
This can be used to create complex filter scenarios.
Logical operators also consist of the `operator`-field and a list of
operators ([available operators](#available-operators)).
An example can be found below:
```json
{
"": [
{
"": {
"field": "",
"value": ""
}
},
{
"": {
"field": "",
"value": ""
}
}
]
}
```
### Instantiate filters
A JSON filter always has a root-operator from which the evaluation is started.
A root-operator can be instantiated from a JSON- or YAML-file or manually.
#### Instantiating a root-operator from a JSON- or YAML-file
To convert fields from JSON- or YAML-files to operators one needs to add the `OperatorDeserializer` to the Jackson
`ObjectMapper` as follows:
```java
ObjectMapper om = new ObjectMapper(new YAMLFactory());
SimpleModule m = new SimpleModule();
m.addDeserializer(Operator .class, new OperatorDeserializer());
m.addSerializer(Operator .class, new OperatorSerializer());
om.registerModule(m);
```
Once the `OperatorDeserializer` and the module is registered in the `ObjectMapper` one can use the `Operator` in any
POJO like so:
```java
package foo.bar;
import ...
public class DummyClass {
@JsonProperty
private Operator jsonFilter;
}
```
In the example above `DummyClass` can then be instantiated by calling `ObjectMapper.read(..., DummyClass.class)`.
During the `ObjectMapper.read()` the operator-chain is also validated.
If the operator-chain specified in the JSON- or YAML-file is not valid an `OperatorParsingException` is thrown.
An example of an operator-chain in YAML-format can be found below:
```json
{
"jsonFilter": {
"and": [
{
"eq": {
"field": "$.processing.state",
"value": "IN_PROGRESS"
}
},
{
"or": [
{
"ge": {
"field": "$.total.amount",
"value": 100000
}
},
{
"eq": {
"field": "$.notify.policy",
"value": "ALWAYS"
}
}
]
}
]
}
}
```
#### Instantiating a root-operator manually
To instantiate an operator-chain manually, one has to differentiate between logical- and comparison-operators.
Comparison operators that take a JSON path and an expected value can be instantiated by
calling `ComparisonOperator.instantiate(ComparisonOperatorEnum operator, String jsonPath, T expectedValue)`.
Logical operators that take a list of operators can be instantiated by
calling `LogicOperator.instantiate(LogicOperatorEnum operator, List operatorList)`.
### Evaluate JSON payload against a filter
To evaluate a JSON payload with a certain `Operator` one only needs to call `Operator.evaluate(String json)`
and pass the JSON as a string.
The result of the evaluation is an `EvaluationResult` that indicates if and why the evaluation was successful or not.
## Available operators
| Name | Operator | Type | Description |
|------------------|----------|------------|-----------------------------------------------------------|
| or | `or` | logic | Valid if **at least one** of the child-operators is valid |
| and | `and` | logic | Valid if **all** of the child-operators are valid |
| | | | |
| equal | `eq` | comparison | Valid if `field` == `value`. |
| not equal | `ne` | comparison | Valid if `field` != `value`. |
| regex | `rx` | comparison | Valid if `field` matches regex defined in `value`. |
| less than | `lt` | comparison | Valid if `field` < `value`. |
| less or equal | `le` | comparison | Valid if `field` <= `value`. |
| greater than | `gt` | comparison | Valid if `field` > `value`. |
| greater or equal | `ge` | comparison | Valid if `field` >= `value`. |
| in | `in` | comparison | Valid if `field` is in `value`. |
| not in | `nin` | comparison | Valid if `field` is not in `value`. |
| contains | `ct` | comparison | Valid if `field` contains `value`. |
| not contains | `nct` | comparison | Valid if `field` does not contain `value`. |
## Contributing
### Code of Conduct
This project has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) in version 2.1 as our code of conduct. Please see the details in our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). All contributors must abide by the code of conduct.
By participating in this project, you agree to abide by its [Code of Conduct](./CODE_OF_CONDUCT.md) at all times.
## Licensing
This project follows the [REUSE standard for software licensing](https://reuse.software/).
Each file contains copyright and license information, and license texts can be found in the [./LICENSES](./LICENSES) folder. For more information visit https://reuse.software/.