{"id":50896428,"url":"https://github.com/thekitchencoder/jspec","last_synced_at":"2026-06-16T00:35:05.823Z","repository":{"id":324222256,"uuid":"1096385742","full_name":"thekitchencoder/jspec","owner":"thekitchencoder","description":"Lightweight Java library for evaluating business criteria against JSON/YAML using MongoDB-style operators","archived":false,"fork":false,"pushed_at":"2026-06-03T23:00:39.000Z","size":651,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T02:04:00.871Z","etag":null,"topics":["business-rules","criteria","evaluation","java-21","json","mongodb","specification","yaml"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thekitchencoder.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-14T10:52:09.000Z","updated_at":"2026-06-03T23:00:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"b3509588-8e92-4cdc-86b4-40bb57938905","html_url":"https://github.com/thekitchencoder/jspec","commit_stats":null,"previous_names":["thekitchencoder/json-rules","thekitchencoder/jspec"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/thekitchencoder/jspec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thekitchencoder%2Fjspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thekitchencoder%2Fjspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thekitchencoder%2Fjspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thekitchencoder%2Fjspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thekitchencoder","download_url":"https://codeload.github.com/thekitchencoder/jspec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thekitchencoder%2Fjspec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34386320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["business-rules","criteria","evaluation","java-21","json","mongodb","specification","yaml"],"created_at":"2026-06-16T00:35:05.067Z","updated_at":"2026-06-16T00:35:05.816Z","avatar_url":"https://github.com/thekitchencoder.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSPEC\n\n[![Maven Central](https://img.shields.io/maven-central/v/uk.codery/jspec.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22uk.codery%22%20AND%20a:%22jspec%22)\n[![Build and Test](https://github.com/thekitchencoder/jspec/actions/workflows/build.yml/badge.svg)](https://github.com/thekitchencoder/jspec/actions/workflows/build.yml)\n[![codecov](https://codecov.io/gh/thekitchencoder/jspec/branch/main/graph/badge.svg)](https://codecov.io/gh/thekitchencoder/jspec)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fthekitchencoder%2Fjspec.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fthekitchencoder%2Fjspec?ref=badge_shield)\n[![Java](https://img.shields.io/badge/Java-21+-blue.svg)](https://openjdk.org/projects/jdk/21/)\n[![Javadoc](https://javadoc.io/badge2/uk.codery/jspec/javadoc.svg)](https://javadoc.io/doc/uk.codery/jspec)\n\nJSPEC (JSON Specification Evaluator) is a lightweight, Spring-independent Java library for evaluating business criteria against JSON/YAML documents with MongoDB-style operators.\n\n## Features\n\n- **23 query operators** – Comparison, collection, advanced, string, date/range, and logical (`$and`/`$or`/`$not`) checks, using familiar MongoDB-style query syntax.\n- **Tri-state evaluation** – Every criterion reports `MATCHED`, `NOT_MATCHED`, or `UNDETERMINED` for precise diagnostics.\n- **Graceful error handling** – Bad data, unknown operators, or type mismatches never halt the evaluation pipeline.\n- **Thread-safe by design** – Immutable records and parallel execution make large specifications fast and safe.\n- **Deep document navigation** – Dot notation walks arbitrarily nested JSON/YAML payloads.\n- **Zero framework dependencies** – Works in plain Java applications or alongside Spring.\n- **Java 21 foundation** – Modern records, switch expressions, and immutable collections throughout.\n- **Context-document references** – `$contextPath` operand sentinel lets one specification be scored against many context documents.\n\n## Quick Start\n\n### Installation\n\nAdd the dependency to your `pom.xml`:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003euk.codery\u003c/groupId\u003e\n    \u003cartifactId\u003ejspec\u003c/artifactId\u003e\n    \u003cversion\u003e0.5.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Basic Usage\n\n1. **Define a `Specification`** containing your criteria. You can write it as YAML/JSON or construct it programmatically. Each entry is auto-typed: a `query` map becomes a `QueryCriterion`, a `junction` block becomes a `CompositeCriterion`, and `ref` entries reference previously defined criteria (so they only evaluate once).\n\n    ```yaml\n    # specification.yaml\n    id: order-validation\n    criteria:\n      - id: minimum-order\n        query:\n          order.total:\n            $gte: 25.00\n      - id: customer-verified\n        query:\n          customer.verified: true\n      - id: express-shipping-eligible\n        junction: AND\n        criteria:\n          - ref: minimum-order\n          - ref: customer-verified\n    ```\n\n2. **Instantiate the evaluator** and inspect the tri-state results.\n\n    ```java\n    import com.fasterxml.jackson.databind.ObjectMapper;\n    import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;\n    import java.io.File;\n    import java.util.Map;\n    import uk.codery.jspec.evaluator.SpecificationEvaluator;\n    import uk.codery.jspec.model.Specification;\n    import uk.codery.jspec.result.EvaluationOutcome;\n\n    ObjectMapper mapper = new ObjectMapper(new YAMLFactory());\n    Specification spec = mapper.readValue(new File(\"specification.yaml\"), Specification.class);\n\n    SpecificationEvaluator evaluator = new SpecificationEvaluator(spec);\n\n    Map\u003cString, Object\u003e document = Map.of(\n        \"order\", Map.of(\"total\", 50.00),\n        \"customer\", Map.of(\"verified\", true)\n    );\n\n    EvaluationOutcome outcome = evaluator.evaluate(document);\n\n    System.out.println(\"Summary: \" + outcome.summary());\n    outcome.results().forEach(result -\u003e\n        System.out.printf(\" - %s -\u003e %s%n\", result.id(), result.state())\n    );\n    ```\n\n## Context-Document References\n\n`$contextPath` is an operand sentinel that defers a value lookup to a separately-supplied context document. Reach for it when the same specification needs to be evaluated against many context documents — for example, scoring a single claim against each of several candidate identities — so the criteria stay templated and only the context changes per call.\n\n```java\nimport java.util.Map;\nimport uk.codery.jspec.evaluator.SpecificationEvaluator;\nimport uk.codery.jspec.model.QueryCriterion;\nimport uk.codery.jspec.model.Specification;\nimport uk.codery.jspec.result.EvaluationOutcome;\n\nSpecification spec = new Specification(\"same-email\", java.util.List.of(\n    new QueryCriterion(\"match\",\n        Map.of(\"email\", Map.of(\"$eq\", Map.of(\"$contextPath\", \"candidate.email\"))))));\n\nSpecificationEvaluator evaluator = new SpecificationEvaluator(spec);\n\nMap\u003cString, Object\u003e target  = Map.of(\"email\", \"a@b.com\");\nMap\u003cString, Object\u003e context = Map.of(\"candidate\", Map.of(\"email\", \"a@b.com\"));\n\nEvaluationOutcome outcome = evaluator.evaluate(target, context);\n// outcome.summary().matched() == 1\n```\n\nIf a `$contextPath` operand fails to resolve, the containing criterion becomes `UNDETERMINED` and the unresolved path is recorded as `context.\u003cpath\u003e` in the result's `missingPaths` — consistent with how target-document misses are surfaced.\n\nA path whose final segment is present-but-`null` resolves successfully and yields `null` to the operator (so `$eq: null` works); a path with a missing entry is unresolved and short-circuits to `UNDETERMINED`. Omit a key entirely if you want the criterion to be `UNDETERMINED` rather than compared against `null`.\n\nThe sentinel works identically in YAML specifications — just write `$contextPath: candidate.email` wherever an operand value would appear.\n\n## Documentation\n\nFor deeper dives, read the docs in `docs/`:\n\n- **[Supported Operators](docs/OPERATORS.md)** – Reference for all 23 query operators.\n- **[Evaluation Model](docs/EVALUATION_MODEL.md)** – How the tri-state pipeline surfaces errors without throwing.\n- **[Architecture](docs/ARCHITECTURE.md)** – Core records, evaluators, and thread-safety guidance.\n- **[General Use Cases](docs/USECASES.md)** – Practical scenarios for embedding JSPEC.\n- **[AI Use Cases](docs/AI_USECASES.md)** – Synthesized guidance for guardrails, hybrid-symbolic patterns, and agent routing.\n- **[JavaDoc](https://javadoc.io/doc/uk.codery/jspec)** – Full API reference.\n\n## Building from Source\n\nTo build the project locally:\n\n```bash\n# Clone the repository\ngit clone https://github.com/thekitchencoder/jspec.git\ncd jspec\n\n# Compile and run the full suite\nmvn clean verify\n\n# Fast feedback while iterating\nmvn test\n```\n\n### Requirements\n- Java 21 or higher\n- Maven 3.6+\n\n### Dependencies\n- **Jackson DataFormat YAML** – JSON/YAML parsing for specifications and documents.\n- **Lombok** – Annotation-driven boilerplate reduction during compilation.\n- **SLF4J API** – Logging abstraction; bring your own binding.\n\n## Demo\n\nTo run the demo application and see the engine in action:\n\n```bash\nmvn test-compile exec:java -Dexec.mainClass=\"uk.codery.jspec.demo.Main\"\n```\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nThis project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fthekitchencoder%2Fjspec.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fthekitchencoder%2Fjspec?ref=badge_large)\n\n## Support\n\nFor issues, questions, or suggestions:\n- Open an issue on GitHub\n- Review existing documentation\n- Check the demo examples in `src/test/java/uk/codery/jspec/demo/`\n\n## Acknowledgments\n\n- Operator design inspired by MongoDB query language\n- Tri-state evaluation model based on graceful degradation principles\n- Built with modern Java 21 features for clean, maintainable code\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthekitchencoder%2Fjspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthekitchencoder%2Fjspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthekitchencoder%2Fjspec/lists"}