If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/json-path/JsonPath shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3mo ago
• 39+ active contributors
• Distributed ownership (top contributor 42% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live json-path/JsonPath repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/json-path/JsonPath.

What it runs against: a local clone of json-path/JsonPath — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in json-path/JsonPath | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 105 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of json-path/JsonPath. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/json-path/JsonPath.git
#   cd JsonPath
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of json-path/JsonPath and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "json-path/JsonPath(\\.git)?\\b" \\
  && ok "origin remote is json-path/JsonPath" \\
  || miss "origin remote is not json-path/JsonPath (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "json-path/src/main/java/com/jayway/jsonpath/JsonPath.java" \\
  && ok "json-path/src/main/java/com/jayway/jsonpath/JsonPath.java" \\
  || miss "missing critical file: json-path/src/main/java/com/jayway/jsonpath/JsonPath.java"
test -f "json-path/src/main/java/com/jayway/jsonpath/internal/ParseContextImpl.java" \\
  && ok "json-path/src/main/java/com/jayway/jsonpath/internal/ParseContextImpl.java" \\
  || miss "missing critical file: json-path/src/main/java/com/jayway/jsonpath/internal/ParseContextImpl.java"
test -f "json-path/src/main/java/com/jayway/jsonpath/internal/filter/FilterCompiler.java" \\
  && ok "json-path/src/main/java/com/jayway/jsonpath/internal/filter/FilterCompiler.java" \\
  || miss "missing critical file: json-path/src/main/java/com/jayway/jsonpath/internal/filter/FilterCompiler.java"
test -f "json-path/src/main/java/com/jayway/jsonpath/Configuration.java" \\
  && ok "json-path/src/main/java/com/jayway/jsonpath/Configuration.java" \\
  || miss "missing critical file: json-path/src/main/java/com/jayway/jsonpath/Configuration.java"
test -f "json-path/src/main/java/com/jayway/jsonpath/internal/EvaluationContext.java" \\
  && ok "json-path/src/main/java/com/jayway/jsonpath/internal/EvaluationContext.java" \\
  || miss "missing critical file: json-path/src/main/java/com/jayway/jsonpath/internal/EvaluationContext.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 105 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~75d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/json-path/JsonPath"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Jayway JsonPath is a Java DSL for querying and extracting data from JSON documents using XPath-like expressions (e.g., $.store.book[0].title). It provides both dot-notation and bracket-notation path syntax, supporting wildcards, deep scans, array slicing, and filter predicates to navigate complex JSON structures without manual parsing. Two-module Gradle monorepo: json-path/ contains the core engine (path parsing, expression evaluation, object navigation) and json-path-assert/ provides Hamcrest matchers for test assertions. Both follow standard Maven layout (src/main/java, src/test/java). The assert module depends on core and wraps it for fluent test DSL (JsonAssert, JsonAsserter).

Java backend developers, test engineers, and API consumers who need to extract specific values from JSON responses in REST clients, automated tests, or data transformation pipelines without writing boilerplate parsing code.

Production-ready and actively maintained. The project has CI/CD via GitHub Actions (.github/workflows/ci.yml), publishes to Maven Central with version 3.0.0 (requiring Java 17+), includes comprehensive test suites across multiple modules, and maintains a changelog. Recent dependency updates (Jackson 3.0.4, Jackson databind 2.20.1, Gson 2.13.2) indicate active maintenance.

Low risk for core functionality, but moderate dependency surface: supports multiple JSON parsers (Jackson, Gson, JSON.org, Jettison, Tapestry, Jakarta JSON-P/B) requiring careful testing across backends. Java 17 baseline is a breaking change from earlier versions. The single-module structure means breaking changes affect all consumers simultaneously. No visible open issue backlog in provided data.

Currently on version 3.0.0 with Java 17 baseline and Jackson 3.0 support. Build uses Gradle with BND OSGi bundling (biz.aQute.bnd.gradle:6.1.0). No specific PR or milestone data visible, but dependency version strings suggest recent maintenance (SLF4J 2.0.17, Hamcrest 3.0, JUnit Jupiter 5.10.1).

git clone https://github.com/json-path/JsonPath.git
cd JsonPath
./gradlew build
./gradlew test

(Gradle wrapper included; requires Java 17+)

Daily commands: This is a library, not an application. To validate locally: ./gradlew build runs full test suite. For development: ./gradlew classes compiles, ./gradlew test runs unit tests across both modules, ./gradlew jar builds JARs.

• json-path/src/main/java/com/jayway/jsonpath/JsonPath.java — Main entry point API; all JsonPath queries start here—every contributor must understand the public API surface
• json-path/src/main/java/com/jayway/jsonpath/internal/ParseContextImpl.java — Core parser that converts JsonPath expressions into executable paths—critical for understanding expression evaluation flow
• json-path/src/main/java/com/jayway/jsonpath/internal/filter/FilterCompiler.java — Compiles filter expressions (e.g., [?(...)]) into evaluators—essential for conditional path resolution
• json-path/src/main/java/com/jayway/jsonpath/Configuration.java — Global configuration registry for JSON providers and options—defines extensibility points for different JSON libraries
• json-path/src/main/java/com/jayway/jsonpath/internal/EvaluationContext.java — Runtime evaluation state machine tracking current position and results—core abstraction for path traversal
• json-path/src/main/java/com/jayway/jsonpath/internal/Path.java — Abstract representation of a parsed JsonPath expression—the bridge between parsing and evaluation
• build.gradle — Multi-module Gradle configuration; defines dependencies (Jackson, GSON, json-smart) and test infrastructure

Add support for a new JSON provider library

1. Implement the JsonProvider SPI interface from com.jayway.jsonpath.spi (define mapper methods for node access) (json-path/src/main/java/com/jayway/jsonpath/spi/JsonProvider.java)
2. Register the provider in DefaultsImpl.getJsonProvider() or user-supplied Configuration via Configuration.jsonProvider() (json-path/src/main/java/com/jayway/jsonpath/internal/DefaultsImpl.java)
3. Add test cases to verify path traversal with the new provider (json-path/src/test/java/com/jayway/jsonpath/JsonPathTest.java)
4. Optionally add Maven dependency to build.gradle ext.libs block (build.gradle)

Add a new filter operator or criteria type

1. Define the operator enum constant in RelationalOperator or LogicalOperator (json-path/src/main/java/com/jayway/jsonpath/internal/filter/RelationalOperator.java)
2. Implement evaluation logic in RelationalExpressionNode or LogicalExpressionNode (json-path/src/main/java/com/jayway/jsonpath/internal/filter/RelationalExpressionNode.java)
3. Update FilterCompiler to recognize the new operator syntax during parsing (json-path/src/main/java/com/jayway/jsonpath/internal/filter/FilterCompiler.java)
4. Add test cases for the new operator (json-path/src/test/java/com/jayway/jsonpath/FilterTest.java)

Add a new Hamcrest matcher for test assertions

1. Create a new TypeSafeMatcher subclass in json-path-assert/src/main/java/com/jayway/jsonpath/matchers/ (json-path-assert/src/main/java/com/jayway/jsonpath/matchers/WithJsonPath.java)
2. Register a static factory method in JsonPathMatchers (json-path-assert/src/main/java/com/jayway/jsonpath/matchers/JsonPathMatchers.java)
3. Write corresponding test case (json-path-assert/src/test/java/com/jayway/jsonpath/matchers/JsonPathMatchersTest.java)

Add a new path segment type or recursive descent variant

1. Define the segment class extending PathToken in internal package (or add to Path.java discriminator) (json-path/src/main/java/com/jayway/jsonpath/internal/Path.java)
2. Implement evaluation in EvaluationContext.evaluate() for the new segment type (json-path/src/main/java/com/jayway/jsonpath/internal/EvaluationContext.java)
3. Update ParseContextImpl to recognize the new syntax (json-path/src/main/java/com/jayway/jsonpath/internal/ParseContextImpl.java)
4. Add integration tests with example JSON documents (json-path/src/test/java/com/jayway/jsonpath/JsonPathTest.java)

• Gradle multi-module — undefined

Java 17 baseline is hard requirement (version 3.0.0+), will not compile or run on Java 8–16. Multiple JSON parser backends are pluggable but must be on classpath; missing a parser will cause runtime failures if that provider is selected. Filter expressions in JsonPath use a proprietary syntax (not standard JSON Schema), which can have subtle precedence/behavior differences from what users expect from XPath. The json-path-assert module's Hamcrest matchers require Hamcrest 3.0+ on test classpath.

• JsonPath Expression Syntax — This repo implements a domain-specific language (DSL) for JSON queries; understanding operators ($, @, *, .., ?, []) and their interaction is essential to using this library effectively
• Pluggable Parser Strategy — Jayway JsonPath abstracts JSON parsing behind a provider interface, allowing users to swap Jackson, Gson, or other backends without code changes; understanding how to switch or register providers is key architectural feature
• Filter Predicates / Path Filtering — JsonPath supports XPath-like filter expressions ([?(@.price < 10)]) for conditional selection within paths; this is non-obvious syntax that differs from JSON Schema and requires careful implementation
• Deep Scan Operator (..) — The .. operator recursively searches all descendants for matching keys, which can be expensive on large documents; understanding its performance implications is important for production queries
• Hamcrest Matchers — The json-path-assert module extends Hamcrest's matcher framework for fluent test assertions; understanding Hamcrest's composition model is necessary to write custom matchers
• OSGi Bundling (BND) — The build system uses BND (biz.aQute.bnd) to generate OSGi-compatible manifests; important if distributing this library in OSGi containers or understanding version constraints

• goessner/JsonPath — Original JavaScript JsonPath implementation by Stefan Goessner; this Java project is an explicit port of that standard
• rest-assured/rest-assured — REST API testing library for Java that uses Jayway JsonPath under the hood for response assertion and extraction
• square/javapoet — Not directly related, but similar ecosystem: Java DSL/fluent API for code generation; represents patterns common in modern Java tooling
• FasterXML/jackson-databind — Primary JSON parsing backend; Jayway JsonPath integrates Jackson as the default provider for deserialization
• google/gson — Alternative JSON parsing backend; Jayway JsonPath supports Gson as a pluggable provider for applications preferring it over Jackson

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for JsonPath filter expressions and Criteria class

The Criteria.java class is referenced in the file structure but has no corresponding test file visible in json-path-assert/src/test. Filter expressions are a critical feature of JsonPath that deserve thorough test coverage. This would improve reliability for complex query scenarios (e.g., $.store.book[?(@.price < 10)]) and catch edge cases in filter evaluation.

• [ ] Create json-path/src/test/java/com/jayway/jsonpath/CriteriaTest.java with tests for all Criteria operators
• [ ] Add tests for complex filter expressions: nested criteria, logical operators (AND/OR), type coercion
• [ ] Test edge cases: null values, missing properties, type mismatches in filter evaluation
• [ ] Verify compatibility across all supported JSON providers (json-smart, Jackson, Gson, etc.)

Add GitHub Actions CI workflow specifically for Jackson 3.x compatibility testing

The build.gradle shows jackson-databind v3.0.4 is included as a test dependency (jacksonDatabind3), but there's no dedicated CI workflow in .github/workflows/ to validate the library against Jackson 3 (separate from Jackson 2). Given the Java 17 baseline requirement for Jackson 3 support mentioned in README, this is critical to prevent regressions in the Jackson 3 upgrade path.

• [ ] Create .github/workflows/jackson3-test.yml that runs tests with Jackson 3.x specifically
• [ ] Ensure separate test matrices for Jackson 2.x (tools.jackson.core:jackson-databind:3.0.x) and traditional jackson-databind
• [ ] Add compatibility matrix testing across multiple Java versions (17+) to validate the Java 17 baseline
• [ ] Document any Jackson 3 specific configuration or known limitations in README.md

Create integration tests for all JSON provider implementations in json-path-assert

The json-path-assert module supports multiple JSON providers (json-smart, Jackson, Gson, Jettison, json.org, Tapestry, Jakarta JSON-P/B), but the visible test files (IsJsonTest.java, WithJsonPathTest.java, etc.) don't show parameterized tests across all providers. This would ensure consistent behavior and error handling across all supported JSON libraries.

• [ ] Create json-path-assert/src/test/java/com/jayway/jsonpath/matchers/MultiProviderTest.java using JUnit 5 @ParameterizedTest
• [ ] Parameterize existing matcher tests (JsonPathMatchersTest, WithJsonPathTest, WithoutJsonPathTest) to run against all 8+ JSON providers
• [ ] Test edge cases per provider: malformed JSON handling, number precision, Unicode handling
• [ ] Document provider-specific behavior differences (if any) in json-path-assert/README.md

• Add comprehensive Javadoc comments to public APIs in json-path-assert/src/main/java/com/jayway/jsonpath/matchers/ classes (JsonPathMatchers, IsJson, WithJsonPath, WithoutJsonPath) — currently sparse, making it hard for users to discover features.
• Create integration tests for cross-parser behavior: add test cases in json-path-assert/src/test/ that verify the same JsonPath query behaves identically when switching between Jackson 2, Jackson 3, Gson, and JSON.org backends via the pluggable parser mechanism.
• Expand the README with a 'Filters and Predicates' section with concrete examples of filter syntax (e.g., $..books[?(@.price < 10)]), including edge cases — current README mentions filter expressions exist but provides no examples.

• High · Outdated Jackson Databind v2.20.1 with Known CVEs — build.gradle - jacksonDatabind: 'com.fasterxml.jackson.core:jackson-databind:2.20.1'. Jackson Databind 2.20.1 is a maintenance release but falls behind the latest security patches. Jackson has had multiple critical deserialization vulnerabilities (e.g., CVE-2020-36518, CVE-2016-7051). While 2.20.1 is relatively recent, it should be verified against current NIST/NVD records for active exploits. Fix: Verify against CVE databases (NVD, Snyk) and upgrade to the latest stable release if vulnerabilities are found. Consider using dependency scanning tools in CI/CD pipeline.
• High · Jackson Databind v3.0.3 & v3.0.4 Mismatch in Dependencies — build.gradle - jacksonDatabind3: 'tools.jackson.core:jackson-databind:3.0.4' and test: 'tools.jackson.core:jackson-databind:3.0.3'. The build.gradle defines both Jackson 3.0.4 (jacksonDatabind3) and 3.0.3 (test dependency). This version inconsistency can lead to classpath conflicts, incompatible class versions, and unexpected behavior. Additionally, Jackson 3.x is a major version that may have different security postures than 2.x. Fix: Align Jackson 3.x versions to a single release (recommend 3.0.4). Run dependency tree analysis (gradle dependencyTree) to identify transitive conflicts. Update test dependencies to match main dependencies.
• Medium · Jettison Library with Known Vulnerabilities — build.gradle - jettison: 'org.codehaus.jettison:jettison:1.5.4'. Jettison 1.5.4 is an older JSON library with known XXE (XML External Entity) and deserialization vulnerabilities. Jettison has had CVE-2022-40150 and similar issues. This is especially concerning if the library processes untrusted JSON input. Fix: Evaluate if Jettison is still required. If it is, upgrade to the latest patch version and enable XML security features. Consider replacing with more actively maintained alternatives like Jackson or Gson.
• Medium · JSON.org Library (json-20250517) with Historical Vulnerabilities — build.gradle - jsonOrg: 'org.json:json:20250517'. While this is a recent version, JSON.org has had XXE vulnerabilities in past versions (e.g., CVE-2022-45688). Verify that the current version includes fixes for all known issues. Fix: Verify against CVE databases that version 20250517 contains no known vulnerabilities. Enable XXE prevention mechanisms in the JSON parser configuration.
• Medium · Missing Dependency Vulnerability Scanning in CI/CD — .github/workflows/ci.yml, .travis.yml. The CI/CD pipeline (.github/workflows/ci.yml) and .travis.yml do not appear to include OWASP Dependency-Check, Snyk, or similar SCA (Software Composition Analysis) tools. This means vulnerabilities in transitive dependencies may not be detected before release. Fix: Integrate OWASP Dependency-Check or Snyk into the CI/CD pipeline. Add steps to fail builds if high-severity vulnerabilities are detected. Use 'gradle dependencyCheck' or similar commands.
• Medium · Incomplete Dependency Version Management — build.gradle - test dependencies array. The build.gradle file declares dependencies directly in test configuration, which can lead to version conflicts and difficulty in managing security patches centrally. Some versions use wildcard-style declarations. Fix: Use a BOM (Bill of Materials) or centralized dependency management. Extract test dependencies to a separate dependencyManagement block. Use 'gradle dependencyInsight' to audit transitive dependencies.
• Low · No Security Policy Documentation Visible — Repository root. The repository does not contain a SECURITY.md file documenting how security vulnerabilities should be reported or the project's security response process. Fix: Create a SECURITY.md file following GitHub's recommended format. Include vulnerability

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.