How stleary/json-java works
1. This repository is a self-contained Java library, not an application or service. Its deliverable is the org.json package, published as a JAR and used as an embedded dependency by other projects.
2. The core data model lives around JSONObject and JSONArray. These are the main in-memory representations for JSON objects and arrays, with JSONException and JSONPointerException as the primary failure modes.
3. Parsing flows through tokenizers and parsers: JSONTokener is the central character/input reader, with specialized tokenizers for XML, HTTP, and XML/HTML-like content (XMLTokener, HTTPTokener). These classes turn raw text into JSON structures.
4. Serialization flows in the opposite direction through JSONStringer, JSONWriter, and StringBuilderWriter. The library can generate JSON text from object graphs, with JSONString as the opt-in interface for custom JSON rendering.
5. The library also supports navigation and extraction via JSONPointer, which provides path-based access into JSON documents. This is a separate concern from parsing and serialization, and it acts as a read/query boundary over already-built JSON structures.
6. Beyond JSON, the package includes format adapters for related text formats:
- XML and XMLParserConfiguration for JSON↔XML conversion
- HTTP, Cookie, and CookieList for header and cookie string handling
- CDL for comma-delimited/columnar data conversion
These are utility subsystems layered on top of the same JSON object model.
7. There is a reflective bean/property subsystem to map Java objects into JSON. Classes such as Property, JSONPropertyName, JSONPropertyIgnore, and XMLXsiTypeConverter support annotation-driven and reflection-based translation from Java types, records, enums, and custom objects into JSON-compatible forms.
8. Configuration is explicit and versioned through parser configuration types: ParserConfiguration, JSONParserConfiguration, XMLParserConfiguration, and JSONMLParserConfiguration. These control parsing behavior without introducing external framework dependencies.
9. Error handling is intentionally lightweight and library-local. There is no exception hierarchy beyond JSON-specific runtime exceptions, and the code emphasizes small, direct APIs with minimal runtime dependencies.
10. The src/test tree is substantial and acts as the main validation harness. Tests cover parsing, serialization, pointer behavior, XML conversion, HTTP/cookie handling, configuration behavior, locale/number edge cases, and regression cases from src/test/resources.
11. The repository is built with both Maven and Gradle (pom.xml, build.gradle, Gradle wrapper). CI runs through GitHub Actions, including a general build/test pipeline and a CodeQL security scan; releases are also documented and signed.
12. Architectural boundary-wise, the project is intentionally narrow: it owns text parsing, object modeling, and format conversion for JSON-related data only. It does not include networking, persistence, UI, or application orchestration; those responsibilities are left to downstream consumers.
Main entry points: JSONObject.java JSONObject · JSONArray.java JSONArray · Property.java Property · JSONTokener.java JSONTokener
Components 31
Build & release
Maven/Gradle build, wrapper, and GitHub Actions pipelines.
- Gradle build · Gradle build entrypoint and wrapper support.
build.gradle - Maven POM · Maven build and publication metadata.
pom.xml - CI pipeline · Main GitHub Actions build/test workflow.
.github/workflows/pipeline.yml - CodeQL scan · Security analysis workflow.
.github/workflows/codeql-analysis.yml
Core JSON
In-memory model, parsing, serialization, and pointer access.
- JSONObject · Primary JSON object representation and central data structure.
src/main/java/org/json/JSONObject.java - JSONArray · Primary JSON array representation.
src/main/java/org/json/JSONArray.java - JSONException · Library-local runtime failure for JSON operations.
src/main/java/org/json/JSONException.java - Pointer error · Failure mode for JSONPointer evaluation.
src/main/java/org/json/JSONPointerException.java - JSONTokener · Central character/input reader for parsing JSON text.
src/main/java/org/json/JSONTokener.java - JSONStringer · Structured JSON text builder.
src/main/java/org/json/JSONStringer.java - JSONWriter · Streaming-style JSON output API.
src/main/java/org/json/JSONWriter.java - StringBuilderWriter · Writer backed by a StringBuilder for text generation.
src/main/java/org/json/StringBuilderWriter.java - JSONString · Opt-in interface for custom JSON rendering.
src/main/java/org/json/JSONString.java - JSONPointer · Path-based navigation and extraction over JSON documents.
src/main/java/org/json/JSONPointer.java - ParserConfig · Shared parser configuration base type.
src/main/java/org/json/ParserConfiguration.java - JSONParserConfig · Parser configuration for JSON behavior.
src/main/java/org/json/JSONParserConfiguration.java
Format adapters
Conversion helpers for XML, HTTP, cookies, and delimited text.
- XML · JSON↔XML conversion utilities.
src/main/java/org/json/XML.java - XMLTokener · Tokenizer for XML-oriented text inputs.
src/main/java/org/json/XMLTokener.java - XMLParserConfig · Configuration for XML parsing and conversion.
src/main/java/org/json/XMLParserConfiguration.java - HTTP · HTTP header string parsing and formatting.
src/main/java/org/json/HTTP.java - HTTPTokener · Tokenizer for HTTP-like text inputs.
src/main/java/org/json/HTTPTokener.java - Cookie · Cookie string parsing and formatting.
src/main/java/org/json/Cookie.java - CookieList · Delimited cookie list handling.
src/main/java/org/json/CookieList.java - CDL · Comma-delimited data conversion utilities.
src/main/java/org/json/CDL.java - JSONMLConfig · Parser configuration for JSONML behavior.
src/main/java/org/json/JSONMLParserConfiguration.java - JSONML · JSONML conversion helpers for XML-like structures.
src/main/java/org/json/JSONML.java
Bean mapping
Reflection and annotation-driven conversion from Java objects to JSON forms.
- Property · Reflection and property access support for object-to-JSON mapping.
src/main/java/org/json/Property.java - JSONPropertyName · Annotation for custom JSON property names.
src/main/java/org/json/JSONPropertyName.java - JSONPropertyIgnore · Annotation for excluding properties from mapping.
src/main/java/org/json/JSONPropertyIgnore.java - XMLXsiTypeConverter · Converter support for XML xsi:type-aware mapping.
src/main/java/org/json/XMLXsiTypeConverter.java
Test harness
JUnit coverage and fixture resources.
- JUnit tests · Repository validation harness for parsing, serialization, conversion, and edge cases.
src/test/java/org/json/junit
Connections 29
- JSONTokener → JSONObject: parse object · Character streams are turned into JSON objects.
- JSONTokener → JSONArray: parse array · Character streams are turned into JSON arrays.
- XMLTokener → XML: tokenize · XML-oriented token streams feed XML conversion.
- HTTPTokener → HTTP: tokenize · HTTP-like text is parsed through a dedicated tokenizer.
- ParserConfig → JSONParserConfig: specialize · JSON parsing behavior is configured through a specialized subtype.
- ParserConfig → XMLParserConfig: specialize · XML parsing behavior is configured through a specialized subtype.
- XMLParserConfig → XML: control · XML conversion behavior is driven by configuration.
- JSONParserConfig → JSONTokener: control · JSON parsing behavior is driven by configuration.
- JSONObject → JSONPointer: query · Pointer evaluation reads values from JSON objects.
- JSONArray → JSONPointer: query · Pointer evaluation reads values from JSON arrays.
- JSONPointer → Pointer error: fail · Pointer evaluation signals dedicated pointer errors.
- JSONObject → JSONException: fail · Object operations raise library-local runtime errors.
- JSONArray → JSONException: fail · Array operations raise library-local runtime errors.
- JSONStringer → JSONWriter: build on · JSONStringer is a structured facade over JSONWriter.
- JSONWriter → StringBuilderWriter: emit to · Writer output is commonly backed by StringBuilderWriter.
- JSONString → JSONStringer: customize · Custom renderers feed into JSON text generation.
- Property → JSONObject: map to · Reflection maps Java objects into JSON objects.
- JSONPropertyName → Property: annotate · Annotation-driven names influence property mapping.
- JSONPropertyIgnore → Property: annotate · Annotation-driven ignores influence property mapping.
- XMLXsiTypeConverter → Property: convert · XML type conversion participates in object mapping.
- JSONML → XML: bridge · JSONML sits on top of XML conversion helpers.
- CDL → JSONArray: shape · Delimited data is expressed through JSON arrays.
- Cookie → JSONObject: shape · Cookie parsing and formatting reuse the JSON object model.
- CookieList → JSONObject: shape · Cookie lists are expressed through JSON object structures.
- HTTP → JSONObject: shape · HTTP header parsing and formatting reuse the JSON object model.
- Gradle build → CI pipeline: build · The main CI workflow validates the Gradle build.
- Maven POM → CI pipeline: build · The main CI workflow validates the Maven build.
- CI pipeline → JUnit tests: run · CI runs the test harness.
- CodeQL scan → JUnit tests: analyze · Security scanning complements the normal test pipeline.