stleary/JSON-java

_{^{image credit: Ismael Pérez Ortiz}}

JSON in Java [package org.json]

Click here if you just want the latest release jar file.

Overview

JSON 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

If you would like to contribute to this project

For more information on contributions, please see 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.

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

javac org/json/*.java

Create the jar file in the current directory

jar cf json-java.jar org/json/*.class

Compile a program that uses the jar (see example code below)

javac -cp .;json-java.jar Test.java (Windows)
javac -cp .:json-java.jar Test.java (Unix Systems)

Test file contents

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

java -cp .;json-java.jar Test (Windows)
java -cp .:json-java.jar Test (Unix Systems)

Expected output

{"abc":"def"}

Tools to build the package and execute the unit tests

Execute the test suite with Maven:

mvn clean test

Execute the test suite with Gradlew:

gradlew clean build test

Optional Execute the test suite in strict mode with Gradlew:

gradlew testWithStrictMode

Optional Execute the test suite in strict mode with Maven:

mvn test -P test-strict-mode 

Notes

For more information, please see NOTES.md

Files

For more information on files, please see FILES.md

Release history:

For the release history, please see RELEASES.md