# Technical Documentation: stleary/JSON-java > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/stleary/JSON-java) ### Overview (`README.md`) image credit: Ismael Pérez Ortiz JSON in Java [package org.json] =============================== [](https://mvnrepository.com/artifact/org.json/json) [](https://github.com/stleary/JSON-java/actions/workflows/pipeline.yml) [](https://github.com/stleary/JSON-java/actions/workflows/codeql-analysis.yml) [](https://javadoc.io/doc/org.json/json) **[Click here if you just want the latest release jar file.](https://repo1.maven.org/maven2/org/json/json/20260814/json-20260814.jar)** # Overview [JSON](http://www.JSON.org/) is a light-weight language-independent data interchange format. The JSON-Java package is a reference implementation that demonstrates how to parse JSON documents into Java objects and how to generate new JSON documents from the Java classes. The files in this package implement JSON encoders and decoders. The package can also convert between JSON and XML, HTTP headers, Cookies, and CDL. Project goals include: * Reliable and consistent results * Adherence to the JSON specification * Easy to build, use, and include in other projects * No external dependencies * Fast execution and low memory footprint * Maintain backward compatibility * Designed and tested to use on Java versions 1.6 - 25 # License Clarification This project is in the public domain. This means: * You can use this code for any purpose, including commercial projects * No attribution or credit is required * You can modify, distribute, and sublicense freely * There are no conditions or restrictions whatsoever We recognize this can create uncertainty for some corporate legal departments accustomed to standard licenses like MIT or Apache 2.0. If your organization requires a named license for compliance purposes, public domain is functionally equivalent to the Unlicense or CC0 1.0, both of which have been reviewed and accepted by organizations including the Open Source Initiative and Creative Commons. You may reference either when explaining this project's terms to your legal team. # Signing keys used in releases The signing keys can be found in [SECURITY.md](https://github.com/stleary/JSON-java/blob/master/docs/SECURITY.md) # If you would like to contribute to this project For more information on contributions, please see [CONTRIBUTING.md](https://github.com/stleary/JSON-java/blob/master/docs/CONTRIBUTING.md) Bug fixes, code improvements, and unit test coverage changes are welcome! Because this project is currently in the maintenance phase, the kinds of changes that can be accepted are limited. For more information, please read the [FAQ](https://github.com/stleary/JSON-java/wiki/FAQ). The project has recently received a number of pull requests that each make a small change to existing behavior. Most come from reading the code or a specification, many apparently with the help of AI tools, and not from a problem that someone met in use. Each change is small, but together they put backward compatibility at risk. For that reason, the requirements below now apply. # Requirements for code changes These requirements apply to every pull request that changes code under src/main: **1. File an issue first.** The issue must come from someone who hit the problem in real use. It should describe what you were doing, the input, the result you got, and the result you expected. A difference from a specification that was found by reading the code is not enough on its own. **2. State which inputs change, and how.** The pull request description must link the issue and list the inputs that behave differently, with the result before and after the change. If no existing behavior changes, say so. Pull requests that do not meet these requirements may be closed without review. Pull requests that only change unit tests or documentation do not need an issue. Security vulnerabilities are handled separately; please report them as described in SECURITY.md. **JSONPointer is frozen** Several fixes that bring JSONPointer in line with RFC 6901 ship in the release that follows 20260814. Once that release is published, JSONPointer is frozen. It will be reopened only for bugs that users report, under the requirements above. Its behavior is pinned by JSONPointerConformanceTest (**TBD**). # Build Instructions The org.json package can be built from the command line, Maven, and Gradle. The unit tests can be executed from Maven, Gradle, or individually in an IDE e.g. Eclipse. **Building from the command line** *Build the class files from the package root directory src/main/java* ```shell javac org/json/*.java ``` *Create the jar file in the current directory* ```shell jar cf json-java.jar org/json/*.class ``` *Compile a program that uses the jar (see example code below)* ```shell javac -cp .;json-java.jar Test.java (Windows) javac -cp .:json-java.jar Test.java (Unix Systems) ``` *Test file contents* ```java import org.json.JSONObject; public class Test { public static void main(String args[]){ JSONObject jo = new JSONObject("{ \"abc\" : \"def\" }"); System.out.println(jo); } } ``` *Execute the Test file* ```shell java -cp .;json-java.jar Test (Windows) java -cp .:json-java.jar Test (Unix Systems) ``` *Expected output* ```json {"abc":"def"} ``` **Tools to build the package and execute the unit tests** Execute the test suite with Maven: ```shell mvn clean test ``` Execute the test suite with Gradlew: ```shell gradlew clean build test ``` *Optional* Execute the test suite in strict mode with Gradlew: ```shell gradlew testWithStrictMode ``` *Optional* Execute the test suite in strict mode with Maven: ```shell mvn test -P test-strict-mode ``` # Notes For more information, please see [NOTES.md](https://github.com/stleary/JSON-java/blob/master/docs/NOTES.md) # Files For more information on files, please see [FILES.md](https://github.com/stleary/JSON-java/blob/master/docs/FILES.md) # Release history: For the release history, please see [RELEASES.md](https://github.com/stleary/JSON-java/blob/master/docs/RELEASES.md) --- ### CONTRIBUTING (`docs/CONTRIBUTING.md`) # Contribution Guidelines Feel free to work on any issue with a #hacktoberfest label. If you discover an issue you would like to work on, you can add a new issue to the list. If it meets our criteria, a hacktoberfest label will be added. # Who is allowed to submit pull requests for this project? Anyone can submit pull requests for code, tests, or documentation. # How do you decide which pull requests to accept? * Does it call out a bug that needs to be fixed? If so, it goes to the top of the list. * Does it fix a major user inconvenience? These are given high priority as well. * Does it align with the specs? If not, it will probably not be accepted. It turns out there are gray areas in the specs. If this is in a gray area, it will likely be given the benefit of the doubt. * Does it break the existing behavior of the lib? If so, it will not be accepted, unless it fixes an egregious bug. This is happening less frequently now. # For more guidance, see these links: [README.md (includes build instructions)](https://github.com/stleary/JSON-java#readme) [FAQ - all your questions answered](https://github.com/stleary/JSON-java/wiki/FAQ) --- ### FILES (`docs/FILES.md`) # Files **JSONObject.java**: The `JSONObject` can parse text from a `String` or a `JSONTokener` to produce a map-like object. The object provides methods for manipulating its contents, and for producing a JSON compliant object serialization. **JSONArray.java**: The `JSONArray` can parse text from a String or a `JSONTokener` to produce a vector-like object. The object provides methods for manipulating its contents, and for producing a JSON compliant array serialization. **JSONTokener.java**: The `JSONTokener` breaks a text into a sequence of individual tokens. It can be constructed from a `String`, `Reader`, or `InputStream`. It also can parse text from a `String`, `Number`, `Boolean` or `null` like `"hello"`, `42`, `true`, `null` to produce a simple json object. **JSONException.java**: The `JSONException` is the standard exception type thrown by this package. **JSONPointer.java**: Implementation of [JSON Pointer (RFC 6901)](https://tools.ietf.org/html/rfc6901). Supports JSON Pointers both in the form of string representation and URI fragment representation. **JSONPropertyIgnore.java**: Annotation class that can be used on Java Bean getter methods. When used on a bean method that would normally be serialized into a `JSONObject`, it overrides the getter-to-key-name logic and forces the property to be excluded from the resulting `JSONObject`. **JSONPropertyName.java**: Annotation class that can be used on Java Bean getter methods. When used on a bean method that would normally be serialized into a `JSONObject`, it overrides the getter-to-key-name logic and uses the value of the annotation. The Bean processor will look through the class hierarchy. This means you can use the annotation on a base class or interface and the value of the annotation will be used even if the getter is overridden in a child class. **JSONString.java**: The `JSONString` interface requires a `toJSONString` method, allowing an object to provide its own serialization. **JSONStringer.java**: The `JSONStringer` provides a convenient facility for building JSON strings. **JSONWriter.java**: The `JSONWriter` provides a convenient facility for building JSON text through a writer. **CDL.java**: `CDL` provides support for converting between JSON and comma delimited lists. **Cookie.java**: `Cookie` provides support for converting between JSON and cookies. **CookieList.java**: `CookieList` provides support for converting between JSON and cookie lists. **HTTP.java**: `HTTP` provides support for converting between JSON and HTTP headers. **HTTPTokener.java**: `HTTPTokener` extends `JSONTokener` for parsing HTTP headers. **XML.java**: `XML` provides support for converting between JSON and XML. **JSONML.java**: `JSONML` provides support for converting between JSONML and XML. **XMLTokener.java**: `XMLTokener` extends `JSONTokener` for parsing XML text. --- ### NOTES (`docs/NOTES.md`) # Notes **Recent directory structure change** _Due to a recent commit - [#515 Merge tests and pom and code](https://github.com/stleary/JSON-java/pull/515) - the structure of the project has changed from a flat directory containing all of the Java files to a directory structure that includes unit tests and several tools used to build the project jar and run the unit tests. If you have difficulty using the new structure, please open an issue so we can work through it._ **Implementation notes** Numeric types in this package comply with [ECMA-404: The JSON Data Interchange Format](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) and [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259#section-6). This package fully supports `Integer`, `Long`, and `Double` Java types. Partial support for `BigInteger` and `BigDecimal` values in `JSONObject` and `JSONArray` objects is provided in the form of `get()`, `opt()`, and `put()` API methods. Although 1.6 compatibility is currently supported, it is not a project goal and might be removed in some future release. In compliance with RFC8259 page 10 section 9, the parser is more lax with what is valid JSON then the Generator. For Example, the tab character (U+0009) is allowed when reading JSON Text strings, but when output by the Generator, the tab is properly converted to \t in the string. Other instances may occur where reading invalid JSON text does not cause an error to be generated. Malformed JSON Texts such as missing end " (quote) on strings or invalid number formats (1.2e6.3) will cause errors as such documents can not be read reliably. Some notable exceptions that the JSON Parser in this library accepts are: * Unquoted keys `{ key: "value" }` * Unquoted values `{ "key": value }` * Unescaped literals like "tab" in string values `{ "key": "value with an unescaped tab" }` * Numbers out of range for `Double` or `Long` are parsed as strings Recent pull requests added a new method `putAll` on the JSONArray. The `putAll` method works similarly to other `put` methods in that it does not call `JSONObject.wrap` for items added. This can lead to inconsistent object representation in JSONArray structures. For example, code like this will create a mixed JSONArray, some items wrapped, others not: ```java SomeBean[] myArr = new SomeBean[]{ new SomeBean(1), new SomeBean(2) }; // these will be wrapped JSONArray jArr = new JSONArray(myArr); // these will not be wrapped jArr.putAll(new SomeBean[]{ new SomeBean(3), new SomeBean(4) }); ``` For structure consistency, it would be recommended that the above code is changed to look like 1 of 2 ways. Option 1: ```Java SomeBean[] myArr = new SomeBean[]{ new SomeBean(1), new SomeBean(2) }; JSONArray jArr = new JSONArray(); // these will not be wrapped jArr.putAll(myArr); // these will not be wrapped jArr.putAll(new SomeBean[]{ new SomeBean(3), new SomeBean(4) }); // our jArr is now consistent. ``` Option 2: ```Java SomeBean[] myArr = new SomeBean[]{ new SomeBean(1), new SomeBean(2) }; // these will be wrapped JSONArray jArr = new JSONArray(myArr); // these will be wrapped jArr.putAll(new JSONArray(new SomeBean[]{ new SomeBean(3), new SomeBean(4) })); // our jArr is now consistent. ``` **Unit Test Conventions** Test filenames should consist of the name of the module being tested, with the suffix "Test". For example, Cookie.java is tested by CookieTest.java. The fundamental issues with JSON-Java testing are:
* JSONObjects are unordered, making simple string comparison ineffective. * Comparisons via **equals()** is not currently supported. Neither JSONArray nor JSONObject override hashCode() or equals(), so comparison defaults to the Object equals(), which is not useful. * Access to the JSONArray and JSONObject internal containers for comparison is not currently available. General issues with unit testing are:
* Just writing tests to make coverage goals tends to result in poor tests. * Unit tests are a form of documentation - how a given method works is demonstrated by the test. So for a code reviewer or future developer looking at code a good test helps explain how a function is supposed to work according to the original author. This can be difficult if you are not the original developer. * It is difficult to evaluate unit tests in a vacuum. You also need to see the code being tested to understand if a test is good. * Without unit tests, it is hard to feel confident about the quality of the code, especially when fixing bugs or refactoring. Good tests prevent regressions and keep the intent of the code correct. * If you have unit test results along with pull requests, the reviewer has an easier time understanding your code and determining if it works as intended. --- ### RELEASES (`docs/RELEASES.md`) # Release history: JSON-java releases can be found by searching the Maven repository for groupId "org.json" and artifactId "json". For example: [https://search.maven.org/search?q=g:org.json%20AND%20a:json&core=gav](https://search.maven.org/search?q=g:org.json%20AND%20a:json&core=gav) ~~~ 20260814 Fixes XML.unescape whitespace handling 20260719 Fixes CVE-2026-59171 very large BigInteger, BigDecimal 20260522 Publish key data, recent commits for minor fixes 20251224 Records, fromJson(), and recent commits 20250517 Strict mode hardening and recent commits 20250107 Restore moditect in pom.xml 20241224 Strict mode opt-in feature, and recent commits. This release does not contain module-info.class. It is not recommended if you need this feature. 20240303 Revert optLong/getLong changes, and recent commits. 20240205 Recent commits. 20231013 First release with minimum Java version 1.8. Recent commits, including fixes for CVE-2023-5072. 20230618 Final release with Java 1.6 compatibility. Future releases will require Java 1.8 or greater. 20230227 Fix for CVE-2022-45688 and recent commits 20220924 New License - public domain, and some minor updates 20220320 Wrap StackOverflow with JSONException 20211205 Recent commits and some bug fixes for similar() 20210307 Recent commits and potentially breaking fix to JSONPointer 20201115 Recent commits and first release after project structure change 20200518 Recent commits and snapshot before project structure change 20190722 Recent commits 20180813 POM change to include Automatic-Module-Name (#431) JSONObject(Map) now throws an exception if any of a map keys are null (#405) 20180130 Recent commits 20171018 Checkpoint for recent commits. 20170516 Roll up recent commits. 20160810 Revert code that was breaking opt*() methods. 20160807 This release contains a bug in the JSONObject.opt*() and JSONArray.opt*() methods, it is not recommended for use. Java 1.6 compatability fixed, JSONArray.toList() and JSONObject.toMap(), RFC4180 compatibility, JSONPointer, some exception fixes, optional XML type conversion. Contains the latest code as of 7 Aug 2016 20160212 Java 1.6 compatibility, OSGi bundle. Contains the latest code as of 12 Feb 2016. 20151123 JSONObject and JSONArray initialization with generics. Contains the latest code as of 23 Nov 2015. 20150729 Checkpoint for Maven central repository release. Contains the latest code as of 29 July 2015. ~~~ --- ### SECURITY (`docs/SECURITY.md`) # Security Policy ## Reporting a Vulnerability Please follow the instructions in the ["How are vulnerabilities and exploits handled?"](https://github.com/stleary/JSON-java/wiki/FAQ#how-are-vulnerabilities-and-exploits-handled) section in the FAQ. ## Verifying Release Signatures All releases of `org.json:json` published to Maven Central are signed with PGP. The fingerprint, keyserver location, and verification procedure below let you confirm that the artifacts you've downloaded were produced by this project and have not been modified in transit. ### Signing Key | | | | --- | --- | | **Fingerprint** | `FB35 C8D0 2B47 24DA DA23 DE0A FD11 6C19 69FC CFF3` | | **Long key ID** | `FD116C1969FCCFF3` | | **Keyserver** | `hkps://keyserver.ubuntu.com` | The full 40-character fingerprint above is the canonical identifier for the key. Always pin or compare against the full fingerprint rather than the long or short key ID. ### Importing the Key ```bash gpg --keyserver hkps://keyserver.ubuntu.com \ --recv-keys FB35C8D02B4724DADA23DE0AFD116C1969FCCFF3 ``` After importing, confirm the fingerprint matches what's published here: ```bash gpg --fingerprint FB35C8D02B4724DADA23DE0AFD116C1969FCCFF3 ``` ### Verifying an Artifact Download both the artifact and its detached signature from Maven Central. For example, for version `20251224`: ```bash curl -O https://repo1.maven.org/maven2/org/json/json/20251224/json-20251224.jar curl -O https://repo1.maven.org/maven2/org/json/json/20251224/json-20251224.jar.asc gpg --verify json-20251224.jar.asc json-20251224.jar ``` A successful verification will report `Good signature from ...` and display the same fingerprint shown above. If GPG reports `BAD signature`, a mismatched fingerprint, or `No public key`, do not use the artifact and please open an issue. The same procedure applies to the `.pom` and any other signed sidecars in the release directory; substitute the filename you want to verify. ### Gradle Dependency Verification If you are using Gradle's [dependency verification](https://docs.gradle.org/current/userguide/dependency_verification.html) feature, add an entry like the following to `gradle/verification-metadata.xml`: ```xml ``` Gradle also accepts the long key ID (`FD116C1969FCCFF3`), but pinning the full fingerprint is recommended. ### Key Rotation If the signing key is ever rotated or revoked, this document will be updated in the `master` branch with the new fingerprint, and the change will be visible in the file's commit history. Always check this file directly in the repository for the current authoritative value before trusting any third-party copy of the fingerprint. --- --- METRICS --- - Files Extracted: 6 - Estimated Token Budget: ~5131 tokens - Canonical Reference: https://codewiki.google/github.com/stleary/JSON-java