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/stleary/JSON-java 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 6w ago
• 12 active contributors
• Distributed ownership (top contributor 30% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{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 stleary/JSON-java repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/stleary/JSON-java.

What it runs against: a local clone of stleary/JSON-java — 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 stleary/JSON-java | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 73 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of stleary/JSON-java. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/stleary/JSON-java.git
#   cd JSON-java
#
# 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 stleary/JSON-java and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "src/main/java/org/json/JSONObject.java" \\
  && ok "src/main/java/org/json/JSONObject.java" \\
  || miss "missing critical file: src/main/java/org/json/JSONObject.java"
test -f "src/main/java/org/json/JSONArray.java" \\
  && ok "src/main/java/org/json/JSONArray.java" \\
  || miss "missing critical file: src/main/java/org/json/JSONArray.java"
test -f "src/main/java/org/json/JSONTokener.java" \\
  && ok "src/main/java/org/json/JSONTokener.java" \\
  || miss "missing critical file: src/main/java/org/json/JSONTokener.java"
test -f "src/main/java/org/json/JSONException.java" \\
  && ok "src/main/java/org/json/JSONException.java" \\
  || miss "missing critical file: src/main/java/org/json/JSONException.java"
test -f "src/main/java/org/json/XML.java" \\
  && ok "src/main/java/org/json/XML.java" \\
  || miss "missing critical file: src/main/java/org/json/XML.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 73 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~43d)"
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/stleary/JSON-java"
  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).

JSON-Java is the reference implementation of JSON parsing and generation in pure Java with zero external dependencies. It provides JSONObject and JSONArray classes to parse JSON strings into Java objects, serialize Java objects to JSON, and convert between JSON and other formats (XML, HTTP headers, CSV via CDL, cookies). Built for Java 1.6–25 compatibility, it's the canonical library in the org.json namespace used by millions of Java applications. Flat structure under src/main/java/org/json/ with ~30 core classes: JSONObject.java and JSONArray.java (primary APIs), specialized tokenizers (JSONTokener, XMLTokener, HTTPTokener), conversion utilities (XML.java, CDL.java, JSONML.java), and configuration classes (JSONParserConfiguration, XMLParserConfiguration). Tests live in src/test/java/. Build is Gradle-based (build.gradle) with Maven dual-support (pom.xml) for dual distribution.

Java backend developers and enterprise applications that need reliable JSON parsing without pulling in heavy dependency trees. Teams maintaining legacy Java 6+ codebases, Android developers (pre-Gradle era), and projects requiring a minimal, battle-tested reference implementation with no transitive dependencies.

Highly mature and production-ready. The codebase is stable (1M+ lines, in maintenance phase per CONTRIBUTING.md), released regularly (latest v20251224), has comprehensive CI via GitHub Actions (Maven pipeline + CodeQL static analysis), test coverage tracked with JaCoCo, and Maven Central publication. This is the de facto standard JSON library for Java—not actively adding features, but actively maintained for security and compatibility.

Very low risk for standard use. No external dependencies (zero transitive deps), single but trusted maintainer (stleary), stable API since early 2000s, and explicit maintenance phase means breaking changes are rare. Main risk: if you need cutting-edge JSON features (JSON Schema validation, streaming for huge files), you may outgrow it and need to migrate to Jackson or Gson.

The project is in maintenance mode—no major feature work visible. Version v20251224-SNAPSHOT is in progress. Recent focus: Java 1.8+ sourceCompatibility (per build.gradle), CodeQL security scanning (codeql-analysis.yml workflow), and JaCoCo code coverage reporting. A modifyStrictMode Gradle task snippet suggests ongoing work on JSONParserConfiguration strictMode feature.

git clone https://github.com/stleary/JSON-java.git
cd JSON-java
./gradlew build
./gradlew test

Or with Maven: mvn clean install. No external services needed; all tests are unit tests with JUnit 4.13.2 and Mockito.

Daily commands: This is a library, not an executable app. To use it: add org.json:json:20251224 (or latest) to your Maven/Gradle deps, then: ```java JSONObject obj = new JSONObject("{"key":"value"}"); System.out.println(obj.getString("key"));

To run tests: `./gradlew test` (or `mvn test`).

• src/main/java/org/json/JSONObject.java — Core class implementing JSON object parsing, serialization, and manipulation—the primary entry point for most use cases.
• src/main/java/org/json/JSONArray.java — Core class for JSON array handling, used alongside JSONObject for complete JSON document support.
• src/main/java/org/json/JSONTokener.java — Lexer/tokenizer that reads and parses JSON text into tokens—foundational for all JSON parsing operations.
• src/main/java/org/json/JSONException.java — Custom exception class for all JSON-related errors; every contributor must understand its usage for error handling.
• src/main/java/org/json/XML.java — Implements JSON-to-XML and XML-to-JSON conversion; critical extension showing how to add format transformations.
• src/main/java/org/json/JSONPointer.java — Implements RFC 6901 JSON Pointer specification for path-based navigation and querying of JSON structures.
• build.gradle — Gradle build configuration defining dependencies, testing, and publication workflows that all contributors must follow.

Add a new format converter (e.g., YAML, TOML)

1. Create new converter class in src/main/java/org/json/ following naming pattern like XML.java or CDL.java (src/main/java/org/json/MyFormatConverter.java)
2. Implement static methods for bidirectional conversion: toJSONObject(String input) and toMyFormat(JSONObject json) (src/main/java/org/json/MyFormatConverter.java)
3. If custom parsing options needed, create a configuration class extending ParserConfiguration (src/main/java/org/json/MyFormatParserConfiguration.java)
4. Add comprehensive test suite mirroring XMLTest.java pattern for parsing, serialization, and edge cases (src/test/java/org/json/junit/MyFormatConverterTest.java)
5. Document examples in Examples.md showing common usage patterns (Examples.md)

Add custom serialization for a new object type

1. Implement JSONString interface on your class to provide custom toJSONString() method (src/main/java/org/json/JSONString.java)
2. Alternatively, add @JSONPropertyName annotations to fields for key renaming and @JSONPropertyIgnore to exclude fields (src/main/java/org/json/JSONPropertyName.java)
3. For complex type mapping, override the bean property introspection logic in JSONObject constructor via reflection (src/main/java/org/json/JSONObject.java)
4. Add test cases in JSONObjectTest.java using test data classes from src/test/java/org/json/junit/data/ (src/test/java/org/json/junit/JSONObjectTest.java)

Extend JSON path querying capabilities

1. Extend JSONPointer class or create JSONPathExtension following RFC 6901 standard (src/main/java/org/json/JSONPointer.java)
2. Add query methods like getValue(JSONObject, String path) that delegate to JSONPointer internally (src/main/java/org/json/JSONPointer.java)
3. Update JSONPointerTest.java with new path syntax and resolution scenarios (src/test/java/org/json/junit/JSONPointerTest.java)

Modify JSON parsing behavior or validation

1. Update JSONParserConfiguration class to add new boolean/enum option flags (src/main/java/org/json/JSONParserConfiguration.java)
2. Modify JSONTokener.java to check configuration flags during tokenization (e.g., allow/disallow comments, trailing commas) (src/main/java/org/json/JSONTokener.java)
3. Update JSONObject/JSONArray constructors to pass JSONParserConfiguration through parsing pipeline (src/main/java/org/json/JSONObject.java)
4. Add test cases in JSONParserConfigurationTest.java covering new behavior flags (src/test/java/org/json/junit/JSONParserConfigurationTest.java)

• Pure Java (no external runtime dependencies) — Ensures broad compatibility across JVMs, embedded environments, and frameworks without dependency hell
• Character-by-character tokenization (JSONTokener) — Provides fine-grained control, precise error reporting with line/column info, and avoids regex overhead
• Reflection-based bean introspection — Automatic serialization of arbitrary POJOs without requiring annotations or external mappers
• Gradle + Maven dual build setup — Supports both modern (Gradle) and legacy (Maven) build ecosystems for maximum adoption

• No streaming JSON parser (only DOM-based JSONObject/JSONArray)
  • Why: undefined
  • Consequence: undefined

• Strictness vs. permissiveness trade-off: JSONTokener is lenient by default (allows single-quoted strings, unquoted keys, comments)—if you need strict RFC 7159 JSON parsing, you must use JSONParserConfiguration with strictMode enabled. This is easy to miss and silently accept invalid JSON.
• Number precision loss: JSONObject stores numbers internally as Double by default. Large integers (> 2^53) lose precision. Use BigDecimal via getBigDecimal() or configure with JSONParserConfiguration to preserve precision.
• Mutable by default: JSONObject and JSONArray are mutable and not thread-safe. Concurrent access requires external synchronization or copying.
• XML attribute/text ambiguity: XML.java's conversion is opinionated—attributes become '@key', text becomes '#text' or content. Round-trip XML→JSON→XML may not preserve original structure (e.g., mixed content).
• Parser state is consumed: JSONTokener reads and advances position; you cannot rewind. If parsing fails partway, the Tokener's position is mid-stream and unreliable.
• No streaming mode: Both JSONObject and JSONArray parse entire input into memory. For multi-GB JSON files, this will OOM. Jackson/Streaming alternatives are needed for large payloads.

• Tokenization (lexical analysis) — JSONTokener, XMLTokener, and HTTPTokener all use character-by-character reading with a position pointer. Understanding how tokens are identified (string, number, punctuation) is crucial to modifying parsers or debugging parse failures.
• Immutable builder pattern — JSONParserConfiguration and XMLParserConfiguration use immutable builder-like semantics (configuration objects that don't change after construction). This pattern appears throughout the codebase for API stability.
• Lenient vs. strict parsing — JSON-java's default behavior is lenient (allows comments, unquoted keys, single quotes) but strict mode enforces RFC 7159. This permissiveness is a core design choice that affects compatibility and security—understanding when to enforce strictness is essential.
• Type erasure and Object heterogeneity — JSONObject.get() returns Object (not generic <T>), and the library relies on runtime type checking and casting. This is a Java 1.6+ compatibility constraint that limits type safety compared to newer libraries.
• Bidirectional format conversion (XML↔JSON) — XML.java's to/fromXML() methods handle semantic mapping between XML (hierarchical, with attributes and text) and JSON (key-value). Understanding this mapping (attributes→@key, text→#text) is critical to avoid data loss in conversions.
• Code coverage and JaCoCo instrumentation — The project uses JaCoCo for coverage reporting (jacocoTestReport task in build.gradle). New contributors must ensure tests cover new code paths; coverage reports are generated at build/reports/jacoco/test/html/index.html.
• Number precision in JSON (BigDecimal vs. Double) — JSON-java stores numbers as Double by default, causing precision loss for large integers. JSONParserConfiguration can control whether to use BigDecimal. Understanding this trade-off (speed vs. precision) is vital for financial or scientific applications.

• FasterXML/jackson-databind — De facto modern replacement for JSON-java in production code; faster streaming parser with strong annotation support and broader ecosystem (jackson-jaxrs, jackson-dataformat-xml)
• google/gson — Google's type-safe JSON serializer; competitive alternative emphasizing POJO serialization and generics—often chosen for Android/mobile where JSON-java is older alternative
• json-org/json-java — This may be referenced as the 'official' fork; verify if distinct from stleary's repo (they are often conflated in ecosystem discourse)
• glassfish/javax.json — Java EE reference implementation for JSON-P (JSON Processing) spec; provides stream-based parsing and generation, more heavyweight than JSON-java
• alibaba/fastjson — High-performance Chinese alternative; used in Alibaba ecosystem; competes on speed but less standardized than Jackson or Gson in open-source

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 XMLTokenizer and XMLXsiTypeConverter

The repo has XMLTokener.java and XMLXsiTypeConverter.java in src/main/java/org/json but the test directory only has XMLTest.java and XMLMLTest.java. There's no dedicated XMLTokenerTest.java or XMLXsiTypeConverterTest.java. Given that XML parsing is a core feature with dedicated tokenizer and type converter classes, these deserve focused unit test coverage with edge cases (malformed XML, special characters, namespace handling, type conversion edge cases).

• [ ] Create src/test/java/org/json/junit/XMLTokenerTest.java with tests for XMLTokener parsing logic
• [ ] Create src/test/java/org/json/junit/XMLXsiTypeConverterTest.java covering type conversion scenarios
• [ ] Ensure tests cover edge cases: empty elements, CDATA sections, XML declarations, namespaces, and invalid type conversions
• [ ] Run ./gradlew test and verify jacoco coverage for these classes increases significantly

Add unit tests for JSONWriter and StringBuilderWriter interaction

JSONWriter.java and StringBuilderWriter.java are core output classes but there's no JSONWriterTest.java in the test suite. While JSONStringerTest.java exists (for JSONStringer), JSONWriter has different API and use cases that need dedicated test coverage. This is especially important for verifying correct output formatting, escape handling, and streaming writes.

• [ ] Create src/test/java/org/json/junit/JSONWriterTest.java
• [ ] Add tests for: basic object/array writing, nested structures, string escaping, number formatting, null handling, and write order
• [ ] Add integration tests with StringBuilderWriter to verify output stream behavior
• [ ] Run ./gradlew jacocoTestReport and verify new coverage for JSONWriter and StringBuilderWriter

Add GitHub Actions workflow for compatibility testing across Java versions

The repo targets Java 1.8+ (sourceCompatibility = '1.8') but the existing pipeline.yml workflow doesn't test against multiple Java versions (8, 11, 17, 21). This is critical for a reference implementation that claims Java 8 compatibility. A matrix-based test workflow would catch Java version-specific issues early.

• [ ] Create .github/workflows/java-matrix-test.yml with a matrix strategy testing against Java 8, 11, 17, and 21
• [ ] Include ./gradlew test and ./gradlew jacocoTestReport steps
• [ ] Ensure build fails if any Java version has test failures or code coverage drops below existing baseline
• [ ] Document results in docs/CONTRIBUTING.md noting which Java versions are officially tested

• Add missing unit tests for src/main/java/org/json/JSONPointer.java—the file exists but test coverage is incomplete. Implement tests for edge cases: empty pointer, non-existent paths, array out-of-bounds, and special characters in keys. Reference: JSONPointer RFC 6901.
• Expand src/main/java/org/json/XMLParserConfiguration.java documentation and add examples to Examples.md—currently the XMLParserConfiguration feature (for controlling XML→JSON conversion behavior) has minimal docs. Add a code sample showing how to use xmlParserConfiguration.setKeepStrings() and setXsiTypeConverter().
• Add performance benchmark suite in src/test/—create a simple JMH or manual benchmark comparing parsing speed of JSONTokener vs. alternatives for 1MB+ JSON files. Document results in docs/NOTES.md. This helps future maintainers identify regression and justify architecture decisions.

The JSON-java codebase demonstrates reasonable security practices with active CI/CD pipelines (Maven, CodeQL) and dependency management. However, several issues reduce the security posture: (1) a critical incomplete build task that requires immediate attention, (2) outdated test dependencies that should be updated, (3) missing security documentation for JSON/XML parsing best practices, and (4) lack of artifact signing for published releases. The primary concern is the corrupted build.gradle file which should be resolved immediately. Overall, this is a mature library with good security foundations, but requires attention to dependency maintenance and documentation.

• Medium · Incomplete/Corrupted Build Configuration — build.gradle (lines containing 'task modifyStrictMode'). The build.gradle file contains an incomplete task definition 'modifyStrictMode' that appears to have been truncated mid-implementation. The task attempts to modify JSONParserConfiguration.java but the code is cut off at 'def backupFile = new File(filePa'. This indicates either a merge conflict, incomplete commit, or file corruption that could lead to unpredictable build behavior. Fix: Complete or remove the 'modifyStrictMode' task. If this task is necessary, ensure the full implementation is present. If not needed, delete it entirely. Review git history to determine the intended state of this file.
• Low · Test Dependency with Known Vulnerabilities — build.gradle (testImplementation 'com.jayway.jsonpath:json-path:2.9.0'). The dependency 'com.jayway.jsonpath:json-path:2.9.0' (released 2018) is outdated and may contain known vulnerabilities. The json-path library has had multiple security updates since version 2.9.0. Fix: Update to the latest stable version of json-path. Current versions (2.8.1+) should be reviewed for security patches. Run 'gradle dependencyUpdates' to check for available updates.
• Low · Mockito Dependency Version — build.gradle (testImplementation 'org.mockito:mockito-core:4.2.0'). The mockito-core:4.2.0 dependency is from 2021 and is relatively outdated. While this is a test-only dependency with lower risk, newer versions include security patches and improvements. Fix: Update to the latest stable version of mockito-core (4.x or 5.x). Since this is test-only, the risk is low, but keeping dependencies current is a security best practice.
• Low · Missing Input Validation Documentation — SECURITY.md and README.md. The project handles JSON parsing and XML conversion, which are common attack vectors. While the codebase appears to focus on parsing, there is no explicit documentation visible in the SECURITY.md about input validation, XXE (XML External Entity) prevention, or JSON parsing security considerations. Fix: Enhance SECURITY.md with guidance on secure usage patterns, including: prevention of XXE attacks, handling of untrusted input, maximum nesting/size limits for JSON/XML parsing, and recommendations for using ParserConfiguration safely.
• Low · Source Jar and Javadoc Generation Without Signature Verification — build.gradle (java { withSourcesJar() withJavadocJar() }). The build.gradle includes tasks to generate source and javadoc JARs for publishing, but there's no evidence of signing these artifacts. This could allow man-in-the-middle attacks or substitution attacks. Fix: Implement artifact signing using GPG or similar mechanisms. Add signing configuration to the publishing block to ensure integrity of published artifacts.

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.