{"id":20793834,"url":"https://github.com/telekom/json-filter","last_synced_at":"2025-05-05T23:54:07.969Z","repository":{"id":218948405,"uuid":"746592299","full_name":"telekom/JSON-Filter","owner":"telekom","description":"JSON filter is a small, lightweight filter-library that allows to evaluate JSON payload against a filter consisting of operators.","archived":false,"fork":false,"pushed_at":"2025-04-14T10:12:39.000Z","size":199,"stargazers_count":7,"open_issues_count":5,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-05T23:54:01.908Z","etag":null,"topics":["filter","json"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/telekom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/Apache-2.0.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-22T10:14:46.000Z","updated_at":"2025-01-17T13:30:05.000Z","dependencies_parsed_at":"2024-01-24T17:30:21.638Z","dependency_job_id":"d2a3b8ef-bc97-4afe-a9d8-96ed4875908d","html_url":"https://github.com/telekom/JSON-Filter","commit_stats":null,"previous_names":["telekom/json-filter"],"tags_count":5,"template":false,"template_full_name":"telekom/reuse-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telekom%2FJSON-Filter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telekom%2FJSON-Filter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telekom%2FJSON-Filter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telekom%2FJSON-Filter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/telekom","download_url":"https://codeload.github.com/telekom/JSON-Filter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252596396,"owners_count":21773844,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filter","json"],"created_at":"2024-11-17T16:11:58.705Z","updated_at":"2025-05-05T23:54:07.958Z","avatar_url":"https://github.com/telekom.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2023 Deutsche Telekom AG\n\nSPDX-License-Identifier: CC0-1.0    \n--\u003e\n\n# JSON Filter \u003c!-- omit in toc --\u003e\n[![REUSE status](https://api.reuse.software/badge/github.com/telekom/JSON-Filter)](https://api.reuse.software/info/github.com/telekom/JSON-Filter)\n[![Issues](https://img.shields.io/github/issues/telekom/JSON-Filter?style=flat)](https://github.com/telekom/JSON-Filter/issues)\n[![Maven Central Version](https://img.shields.io/maven-central/v/de.telekom/json-filter)](https://central.sonatype.com/artifact/de.telekom/json-filter)\n\n\n## About\n\nJSON filter is a small, lightweight filter-library that allows to evaluate JSON payload against a filter consisting of\noperators.\nOperators can be defined programmatically or in JSON- or YAML-files.\nThe evaluation of JSON payloads against a filter results in an EvaluationResult, which indicates why a filter failed.\n\n## Usage\n\nThere are two types of operators: comparison- and logical-operators.\n\n### Comparison operators\n\nComparison-operators are used to compare a JSON path against an expected value.\nComparison-operators consist of three fields, `operator`, `field` and `value`.\n\n`operator` is the operator to be used for the comparison ([available operators](#available-operators)).  \n`field` is the JSON-path to be evaluated.  \n`value` is the expected value.  \nAn example can be found below:\n\n```json\n{\n  \"\u003ccomparison operator\u003e\": {\n    \"field\": \"\u003cJSON-path\u003e\",\n    \"value\": \"\u003cexpected value\u003e\"\n  }\n}\n```\n\n### Logic operators\n\nLogical operators are used to combine multiple operators.\nThis can be used to create complex filter scenarios.\nLogical operators also consist of the `operator`-field and a list of\noperators ([available operators](#available-operators)).  \nAn example can be found below:\n\n```json\n{\n  \"\u003clogic operator\u003e\": [\n    {\n      \"\u003ccomparison operator\u003e\": {\n        \"field\": \"\u003cJSON-path\u003e\",\n        \"value\": \"\u003cexpected value\u003e\"\n      }\n    },\n    {\n      \"\u003ccomparison operator\u003e\": {\n        \"field\": \"\u003cJSON-path\u003e\",\n        \"value\": \"\u003cexpected value\u003e\"\n      }\n    }\n  ]\n}\n```\n\n### Instantiate filters\n\nA JSON filter always has a root-operator from which the evaluation is started.\nA root-operator can be instantiated from a JSON- or YAML-file or manually.\n\n#### Instantiating a root-operator from a JSON- or YAML-file\n\nTo convert fields from JSON- or YAML-files to operators one needs to add the `OperatorDeserializer` to the Jackson\n`ObjectMapper` as follows:\n\n```java\nObjectMapper om = new ObjectMapper(new YAMLFactory());\n\nSimpleModule m = new SimpleModule();\nm.addDeserializer(Operator .class, new OperatorDeserializer());\nm.addSerializer(Operator .class, new OperatorSerializer());\n\nom.registerModule(m);\n```\n\nOnce the `OperatorDeserializer` and the module is registered in the `ObjectMapper` one can use the `Operator` in any\nPOJO like so:\n\n```java\npackage foo.bar;\n\nimport ...\n\npublic class DummyClass {\n    @JsonProperty\n    private Operator jsonFilter;\n}\n```\n\nIn the example above `DummyClass` can then be instantiated by calling `ObjectMapper.read(..., DummyClass.class)`.\n\nDuring the `ObjectMapper.read()` the operator-chain is also validated.\nIf the operator-chain specified in the JSON- or YAML-file is not valid an `OperatorParsingException` is thrown.\n\nAn example of an operator-chain in YAML-format can be found below:\n\n```json\n{\n  \"jsonFilter\": {\n    \"and\": [\n      {\n        \"eq\": {\n          \"field\": \"$.processing.state\",\n          \"value\": \"IN_PROGRESS\"\n        }\n      },\n      {\n        \"or\": [\n          {\n            \"ge\": {\n              \"field\": \"$.total.amount\",\n              \"value\": 100000\n            }\n          },\n          {\n            \"eq\": {\n              \"field\": \"$.notify.policy\",\n              \"value\": \"ALWAYS\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n#### Instantiating a root-operator manually\n\nTo instantiate an operator-chain manually, one has to differentiate between logical- and comparison-operators.\nComparison operators that take a JSON path and an expected value can be instantiated by\ncalling `ComparisonOperator.instantiate(ComparisonOperatorEnum operator, String jsonPath, T expectedValue)`.  \nLogical operators that take a list of operators can be instantiated by\ncalling `LogicOperator.instantiate(LogicOperatorEnum operator, List\u003cOperator\u003e operatorList)`.\n\n### Evaluate JSON payload against a filter\n\nTo evaluate a JSON payload with a certain `Operator` one only needs to call `Operator.evaluate(String json)`\nand pass the JSON as a string.\n\nThe result of the evaluation is an `EvaluationResult` that indicates if and why the evaluation was successful or not.\n\n## Available operators\n\n| Name             | Operator | Type       | Description                                               |\n|------------------|----------|------------|-----------------------------------------------------------|\n| or               | `or`     | logic      | Valid if **at least one** of the child-operators is valid |\n| and              | `and`    | logic      | Valid if **all** of the child-operators are valid         |\n|                  |          |            |                                                           |\n| equal            | `eq`     | comparison | Valid if `field` == `value`.                              |\n| not equal        | `ne`     | comparison | Valid if `field` != `value`.                              |\n| regex            | `rx`     | comparison | Valid if `field` matches regex defined in `value`.        |\n| less than        | `lt`     | comparison | Valid if `field` \u003c `value`.                               |\n| less or equal    | `le`     | comparison | Valid if `field` \u003c= `value`.                              |\n| greater than     | `gt`     | comparison | Valid if `field` \u003e  `value`.                              |\n| greater or equal | `ge`     | comparison | Valid if `field` \u003e= `value`.                              |\n| in               | `in`     | comparison | Valid if `field` is in `value`.                           |\n| not in           | `nin`    | comparison | Valid if `field` is not in `value`.                       |\n| contains         | `ct`     | comparison | Valid if `field` contains `value`.                        |\n| not contains     | `nct`    | comparison | Valid if `field` does not contain `value`.                |\n\n## Contributing\n\n### Code of Conduct\n\nThis 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.\n\nBy participating in this project, you agree to abide by its [Code of Conduct](./CODE_OF_CONDUCT.md) at all times.\n\n## Licensing\n\nThis project follows the [REUSE standard for software licensing](https://reuse.software/).\nEach file contains copyright and license information, and license texts can be found in the [./LICENSES](./LICENSES) folder. For more information visit https://reuse.software/.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelekom%2Fjson-filter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelekom%2Fjson-filter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelekom%2Fjson-filter/lists"}