# stleary/json-java architecture

> Architecture diagram of the GitHub repository stleary/json-java, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stleary/json-java
- Repository: https://github.com/stleary/json-java

## Overview

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: [`src/main/java/org/json/JSONObject.java`](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONObject.java) (JSONObject), [`src/main/java/org/json/JSONArray.java`](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONArray.java) (JSONArray), [`src/main/java/org/json/Property.java`](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/Property.java) (Property), [`src/main/java/org/json/JSONTokener.java`](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONTokener.java) (JSONTokener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & release"]
  node_gradle["Gradle build<br/>build config<br/>[build.gradle]"]
  node_maven["Maven POM<br/>build config<br/>[pom.xml]"]
  node_pipeline["CI pipeline<br/>workflow<br/>[pipeline.yml]"]
  node_codeql["CodeQL scan<br/>workflow"]
end

subgraph group_core["Core JSON"]
  node_jsonobject["JSONObject<br/>core model<br/>[JSONObject.java]"]
  node_jsonarray["JSONArray<br/>core model<br/>[JSONArray.java]"]
  node_jsonexception(("JSONException<br/>runtime error<br/>[JSONException.java]"))
  node_jsonpointerexception(("Pointer error<br/>runtime error"))
  node_tokener["JSONTokener<br/>parser input<br/>[JSONTokener.java]"]
  node_stringer["JSONStringer<br/>writer builder<br/>[JSONStringer.java]"]
  node_jsonwriter["JSONWriter<br/>writer API<br/>[JSONWriter.java]"]
  node_stringbuilderwriter["StringBuilderWriter<br/>writer adapter"]
  node_jsonstring["JSONString<br/>render hook<br/>[JSONString.java]"]
  node_jsonpointer{{"JSONPointer<br/>query path<br/>[JSONPointer.java]"}}
  node_parserconfig["ParserConfig<br/>config base"]
  node_jsonconfig["JSONParserConfig"]
end

subgraph group_formats["Format adapters"]
  node_xml["XML<br/>[XML.java]"]
  node_xmltokener["XMLTokener<br/>xml parser<br/>[XMLTokener.java]"]
  node_xmlconfig["XMLParserConfig<br/>parser config"]
  node_http["HTTP<br/>header adapter<br/>[HTTP.java]"]
  node_httptokener["HTTPTokener<br/>http parser<br/>[HTTPTokener.java]"]
  node_cookie["Cookie<br/>[Cookie.java]"]
  node_cookielist["CookieList<br/>cookie adapter<br/>[CookieList.java]"]
  node_cdl["CDL<br/>csv-like adapter<br/>[CDL.java]"]
  node_jsonmlconfig["JSONMLConfig"]
  node_jsonml["JSONML<br/>xml-json bridge<br/>[JSONML.java]"]
end

subgraph group_mapping["Bean mapping"]
  node_property["Property<br/>reflection mapper<br/>[Property.java]"]
  node_jsonpropertyname["JSONPropertyName<br/>annotation"]
  node_jsonpropertyignore["JSONPropertyIgnore<br/>annotation"]
  node_xmlxsitypeconverter["XMLXsiTypeConverter<br/>type converter"]
end

subgraph group_tests["Test harness"]
  node_tests["JUnit tests<br/>test suite"]
end

node_tokener -->|"parse object"| node_jsonobject
node_tokener -->|"parse array"| node_jsonarray
node_xmltokener -->|"tokenize"| node_xml
node_httptokener -->|"tokenize"| node_http
node_parserconfig -->|"specialize"| node_jsonconfig
node_parserconfig -->|"specialize"| node_xmlconfig
node_xmlconfig -->|"control"| node_xml
node_jsonconfig -->|"control"| node_tokener
node_jsonobject -->|"query"| node_jsonpointer
node_jsonarray -->|"query"| node_jsonpointer
node_jsonpointer -->|"fail"| node_jsonpointerexception
node_jsonobject -->|"fail"| node_jsonexception
node_jsonarray -->|"fail"| node_jsonexception
node_stringer -->|"build on"| node_jsonwriter
node_jsonwriter -->|"emit to"| node_stringbuilderwriter
node_jsonstring -->|"customize"| node_stringer
node_property -->|"map to"| node_jsonobject
node_jsonpropertyname -->|"annotate"| node_property
node_jsonpropertyignore -->|"annotate"| node_property
node_xmlxsitypeconverter -->|"convert"| node_property
node_jsonml -->|"bridge"| node_xml
node_cdl -->|"shape"| node_jsonarray
node_cookie -->|"shape"| node_jsonobject
node_cookielist -->|"shape"| node_jsonobject
node_http -->|"shape"| node_jsonobject
node_gradle -->|"build"| node_pipeline
node_maven -->|"build"| node_pipeline
node_pipeline -->|"run"| node_tests
node_codeql -.->|"analyze"| node_tests

click node_jsonobject "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONObject.java"
click node_jsonarray "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONArray.java"
click node_jsonexception "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONException.java"
click node_jsonpointerexception "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONPointerException.java"
click node_tokener "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONTokener.java"
click node_stringer "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONStringer.java"
click node_jsonwriter "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONWriter.java"
click node_stringbuilderwriter "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/StringBuilderWriter.java"
click node_jsonstring "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONString.java"
click node_jsonpointer "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONPointer.java"
click node_xml "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/XML.java"
click node_xmltokener "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/XMLTokener.java"
click node_xmlconfig "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/XMLParserConfiguration.java"
click node_http "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/HTTP.java"
click node_httptokener "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/HTTPTokener.java"
click node_cookie "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/Cookie.java"
click node_cookielist "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/CookieList.java"
click node_cdl "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/CDL.java"
click node_parserconfig "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/ParserConfiguration.java"
click node_jsonconfig "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONParserConfiguration.java"
click node_jsonmlconfig "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONMLParserConfiguration.java"
click node_jsonml "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONML.java"
click node_property "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/Property.java"
click node_jsonpropertyname "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONPropertyName.java"
click node_jsonpropertyignore "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONPropertyIgnore.java"
click node_xmlxsitypeconverter "https://github.com/stleary/json-java/blob/master/src/main/java/org/json/XMLXsiTypeConverter.java"
click node_gradle "https://github.com/stleary/json-java/blob/master/build.gradle"
click node_maven "https://github.com/stleary/json-java/blob/master/pom.xml"
click node_pipeline "https://github.com/stleary/json-java/blob/master/.github/workflows/pipeline.yml"
click node_codeql "https://github.com/stleary/json-java/blob/master/.github/workflows/codeql-analysis.yml"
click node_tests "https://github.com/stleary/json-java/tree/master/src/test/java/org/json/junit"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gradle,node_maven,node_pipeline,node_codeql toneBlue
class node_jsonobject,node_jsonarray,node_jsonexception,node_jsonpointerexception,node_tokener,node_stringer,node_jsonwriter,node_stringbuilderwriter,node_jsonstring,node_jsonpointer,node_parserconfig,node_jsonconfig toneAmber
class node_xml,node_xmltokener,node_xmlconfig,node_http,node_httptokener,node_cookie,node_cookielist,node_cdl,node_jsonmlconfig,node_jsonml toneMint
class node_property,node_jsonpropertyname,node_jsonpropertyignore,node_xmlxsitypeconverter toneRose
class node_tests toneIndigo
```

## Components

### Build & release

Maven/Gradle build, wrapper, and GitHub Actions pipelines.

- [Gradle build](https://github.com/stleary/json-java/blob/master/build.gradle): build config · Gradle build entrypoint and wrapper support. · `build.gradle`
- [Maven POM](https://github.com/stleary/json-java/blob/master/pom.xml): build config · Maven build and publication metadata. · `pom.xml`
- [CI pipeline](https://github.com/stleary/json-java/blob/master/.github/workflows/pipeline.yml): workflow · Main GitHub Actions build/test workflow. · `.github/workflows/pipeline.yml`
- [CodeQL scan](https://github.com/stleary/json-java/blob/master/.github/workflows/codeql-analysis.yml): workflow · Security analysis workflow. · `.github/workflows/codeql-analysis.yml`

### Core JSON

In-memory model, parsing, serialization, and pointer access.

- [JSONObject](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONObject.java): core model · Primary JSON object representation and central data structure. · `src/main/java/org/json/JSONObject.java`
- [JSONArray](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONArray.java): core model · Primary JSON array representation. · `src/main/java/org/json/JSONArray.java`
- [JSONException](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONException.java): runtime error · Library-local runtime failure for JSON operations. · `src/main/java/org/json/JSONException.java`
- [Pointer error](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONPointerException.java): runtime error · Failure mode for JSONPointer evaluation. · `src/main/java/org/json/JSONPointerException.java`
- [JSONTokener](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONTokener.java): parser input · Central character/input reader for parsing JSON text. · `src/main/java/org/json/JSONTokener.java`
- [JSONStringer](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONStringer.java): writer builder · Structured JSON text builder. · `src/main/java/org/json/JSONStringer.java`
- [JSONWriter](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONWriter.java): writer API · Streaming-style JSON output API. · `src/main/java/org/json/JSONWriter.java`
- [StringBuilderWriter](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/StringBuilderWriter.java): writer adapter · Writer backed by a StringBuilder for text generation. · `src/main/java/org/json/StringBuilderWriter.java`
- [JSONString](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONString.java): render hook · Opt-in interface for custom JSON rendering. · `src/main/java/org/json/JSONString.java`
- [JSONPointer](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONPointer.java): query path · Path-based navigation and extraction over JSON documents. · `src/main/java/org/json/JSONPointer.java`
- [ParserConfig](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/ParserConfiguration.java): config base · Shared parser configuration base type. · `src/main/java/org/json/ParserConfiguration.java`
- [JSONParserConfig](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONParserConfiguration.java): config · Parser configuration for JSON behavior. · `src/main/java/org/json/JSONParserConfiguration.java`

### Format adapters

Conversion helpers for XML, HTTP, cookies, and delimited text.

- [XML](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/XML.java): xml bridge · JSON↔XML conversion utilities. · `src/main/java/org/json/XML.java`
- [XMLTokener](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/XMLTokener.java): xml parser · Tokenizer for XML-oriented text inputs. · `src/main/java/org/json/XMLTokener.java`
- [XMLParserConfig](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/XMLParserConfiguration.java): parser config · Configuration for XML parsing and conversion. · `src/main/java/org/json/XMLParserConfiguration.java`
- [HTTP](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/HTTP.java): header adapter · HTTP header string parsing and formatting. · `src/main/java/org/json/HTTP.java`
- [HTTPTokener](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/HTTPTokener.java): http parser · Tokenizer for HTTP-like text inputs. · `src/main/java/org/json/HTTPTokener.java`
- [Cookie](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/Cookie.java): cookie adapter · Cookie string parsing and formatting. · `src/main/java/org/json/Cookie.java`
- [CookieList](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/CookieList.java): cookie adapter · Delimited cookie list handling. · `src/main/java/org/json/CookieList.java`
- [CDL](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/CDL.java): csv-like adapter · Comma-delimited data conversion utilities. · `src/main/java/org/json/CDL.java`
- [JSONMLConfig](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONMLParserConfiguration.java): config · Parser configuration for JSONML behavior. · `src/main/java/org/json/JSONMLParserConfiguration.java`
- [JSONML](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONML.java): xml-json bridge · 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](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/Property.java): reflection mapper · Reflection and property access support for object-to-JSON mapping. · `src/main/java/org/json/Property.java`
- [JSONPropertyName](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONPropertyName.java): annotation · Annotation for custom JSON property names. · `src/main/java/org/json/JSONPropertyName.java`
- [JSONPropertyIgnore](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/JSONPropertyIgnore.java): annotation · Annotation for excluding properties from mapping. · `src/main/java/org/json/JSONPropertyIgnore.java`
- [XMLXsiTypeConverter](https://github.com/stleary/json-java/blob/master/src/main/java/org/json/XMLXsiTypeConverter.java): type converter · Converter support for XML xsi:type-aware mapping. · `src/main/java/org/json/XMLXsiTypeConverter.java`

### Test harness

JUnit coverage and fixture resources.

- [JUnit tests](https://github.com/stleary/json-java/tree/master/src/test/java/org/json/junit): test suite · Repository validation harness for parsing, serialization, conversion, and edge cases. · `src/test/java/org/json/junit`

## Connections

- 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.
