FAQ

Who is allowed to submit pull requests for this project?

Anyone can submit pull requests. Please read the rest of this FAQ page for guidelines about what kinds of changes are being accepted.

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 align with the specs? If not, it will not be accepted.
Does it change the behavior of the lib? If so, it will not be accepted, unless it fixes an egregious bug. This is happening less frequently now.
Does it compile with Java 6? In general, code that cannot be compiled with Java6 will not be accepted. To check your code, download and install the Java6 JDK, then execute these commands from the root directory:
- cd src/main/java
- javac org/json/*java
Has Douglas Crockford already spoken on this issue? If so, we follow his guidance. No exceptions.

How are vulnerabilities and exploits handled?

If you think you have found a vulnerability - a weakness in the code that could be subject to attack - please open a public issue in the repository. This allows the entire community to understand the scope and come up with the best way to address the problem.

If you have evidence of a zero day exploit - an example where someone has successfully compromised the code in the wild - then it is OK to withhold details when posting the issue. In that case you can contact the project owner directly with the exploit details.

Why isn't support included for Maven, Gradle, or any other tools?

When this app was first written, there was not a single universally agreed upon build tool. This still seems to be the case. Periodically, Maven Repository releases are built and distributed here: http://mvnrepository.com/artifact/org.json/json

To build this project you can simply run javac *.java. If you want to make your own JAR file for redistribution, you can execute the following commands from the project directory:

OSX/Linux
javac *.java
mkdir -p org/json
mv *.class org/json
jar cf json-java.jar org
Windows
javac *.java
mkdir org\json
move *.class org\json
jar cf json-java.jar org

Why don't you accept pull requests with extensive formatting changes?

It's OK if your PR has some lines that are non-standard (i.e. that have a different format than the majority of the files in the project), but files that contain nothing but formatting changes will not be accepted. It's difficult to hand-check a set of 50 or so files where almost every line has changed. And even if that was practical, there is no universal standard for formatting. Your idea of the preferred formatting may be different from someone else's.

Why isn't ordering allowed in JSONObjects?

Support for ordering is one of the most popular requests, along with adding some type of build support. However, from the JSON spec RFC 8259: "An object is an unordered collection of zero or more name/value pairs". As a reference app, the design is required to stay as close to the spec as possible, so ordering in JSONObjects is not supported.

Will ordering ever be allowed in JSONObjects?

There are no current plans to support ordering. It is not expected that this will ever change.

Where are the unit tests?

The unit tests are included in the project. To execute them, use either of these commands:

./gradlew clean build test
mvn clean compile test

What is the goal of this project?

Continue in maintenance mode, in terms of stability, availability, and accessibility of the project
Make sure it continues to compile against new Java versions
Fix reported bugs.
Maintain compatibility with RFC 8259 and ECMA-404
Avoid any actions that would affect the ability of users to access and use the software
Provide some technical documentation and answer questions regarding the project design and use
Provide unit tests

What kind of changes will be accepted for this project?

Bug fixes and incompatibilities with the specs.

What if I want to refactor the code?

Unsolicited pull requests to refactor large parts of the code are considered high risk and will not be accepted. If you want to do some refactoring, then it is recommended to open an issue to discuss what you think is wrong, and how to fix it. If the change is approved you can submit a pull request. You can improve the odds of a positive outcome by making yourself known to the project by contributing to discussions and submitting code to fix issues labeled available for someone to work on. There are usually a few of these open at any given time.

Some invalid JSON text is allowed by the parser. Shouldn't this be fixed?

Per design, the JSONObject and JSONArray constructors are more forgiving than required by the spec. However, the toString() methods produce text that is strictly conforming. For example, some strings do not need to be surrounded by quotes when creating a JSONObject, but those strings will be surrounded by quotes when emitted from toString(). This behavior appears to have been part of the lib from the start, and will not be changed. More information about what is allowed can be found in the class-level comments for JSONObject and JSONArray.

Why doesn't this project have a distributable jar file?

It can be found on maven central. You can download the release version you like from here or here

My change fixes a bug. Why won't you accept it?

The most common reason for not accepting a valid bug fix is when it will result in a change to the API or behavior of the code. Changes to existing behavior will only be accepted in the case of bugs where the existing behavior is clearly worse than the fix.

I want to add an external lib to the project

One of the strengths of this library is that it has no external dependencies, making it easy to include in a project, or on a limited resource platform. There are no plans now, and none are expected in the future, to introduce 3rd party libraries.

Can you help me debug my code?

Simple and straightforward problems may be addressed at the discretion of the project participants, but in most cases it is recommended to post to StackOverflow.com or a similar forum.

What version of Java does this project require?

At the present time Java 8 is required to run the unit tests and the Maven Repository release. However, the library can be compiled and executed with Java 6.

Complete history of API changes since 2015

Release	Pull Request	File	Method	Description
Not released yet	400	XML.java	public static JSONObject toJSONObject(Reader reader)	New
.			public static JSONObject toJSONObject(Reader reader, boolean keepStrings)	New
.		XMLTokener.java	public XMLTokener(Reader r)	New
20180130
20181018	362	XMLTokener.java	static String unescapeEntity(String e)	New
.	337	JSONArray.java	public float getFloat(int index) throws JSONException	New
.			public Number getNumber(int index) throws JSONException	New
.			public float optFloat(int index)	New
.			public float optFloat(int index, float defaultValue)	New
.			public Number optNumber(int index)	New
.			public Number optNumber(int index, Number defaultValue)	New
.		JSONObject	public float getFloat(String key)	New
.			public Number getNumber(String key)	New
.			public BigDecimal optBigDecimal(String key, BigDecimal defaultValue)	New
.			public double optDouble(String key)	New
.			public double optDouble(String key, double defaultValue)	New
.			public float optFloat(String key)	New
.			public float optFloat(String key, float defaultValue)	New
.			public Number optNumber(String key)	New
.			public Number optNumber(String key, Number defaultValue)	New
.	336	JSONObject.java (Null)	public int hashCode()	New
.		JSONObject.java	public JSONObject put(String key, float value)	New
.			public JSONPointer(final String pointer)	Add final to String
.		JSONStringer.java	public String toString()	Add @Override annotation to method
.		XML.java	public static String toString(final Object object, final String tagName)	Add final to Object, String
20170516	324	JSONArray.java	public Object query(JSONPointer jsonPointer)	New
.			public Object optQuery(JSONPointer jsonPointer)	New
.		JSONObject.java	public Object query(JSONPointer jsonPointer)	New
.			public Object optQuery(JSONPointer jsonPointer)	New
.	288	XML.java	public static String unescape(String string)	New
.			public static Object stringToValue(String string)	Remove @Deprecated annotation
20160810	261	JSONArray.java	public String toString()	Remove @Override annotation
20160807	253	JSONML.java	public static JSONArray toJSONArray(String string, boolean keepStrings) throws JSONException	New
.			public static JSONArray toJSONArray(XMLTokener x, boolean keepStrings) throws JSONException	New
.			public static JSONObject toJSONObject(String string, boolean keepStrings) throws JSONException	New
.			public static JSONObject toJSONObject(XMLTokener x, boolean keepStrings)	New
.		JSONTokener.java	public JSONTokener(InputStream inputStream)	Remove throws JSONException
.			public String toString()	Add @Override annotation
.		XML.java	public static Object stringToValue(String string)	Add @Deprecated annotation
.			public static JSONObject toJSONObject(String string, boolean keepStrings) throws JSONException	New
.	249	JSONArray.java	public String toString()	Add @Override annotation
.		JSONObject.java (Null)	public String toString()	Add @Override annotation
.		JSONObject.java	public String toString()	Add @Override annotation
.	236	JSONTokener.java	public JSONException syntaxError(String message, Throwable causedBy)	New
.	233	JSONArray.java	public Object optQuery(String jsonPointer)	New
.		JSONObject	public Object optQuery(String jsonPointer)	New
.	222	JSONArray.java	public Object query(String jsonPointer)	New
.		JSONObject.java	public Object query(String jsonPointer)	New
.		JSONPointer.java	public class JSONPointer	New class
.		JSONPointerException.java	public class JSONPointerException	New class
.	203	JSONArray.java	public List toList()	New
.		JSONObject.java	public Map<String, Object> toMap()	New
20160212	185	JSONArray.java	public Writer write(Writer writer, int indentFactor, int indent)	Change to public
.		JSONObject.java	public Writer write(Writer writer, int indentFactor, int indent)	Change to public
20151123	159	JSONException.java	public JSONException(final String message)	Final String
.			public JSONException(final String message, final Throwable cause)	New
.			public JSONException(final Throwable cause)	Change to final
.			public Throwable getCause()	REMOVED to use super class implementation
.	153	JSONArray.java	public JSONArray(Collection> collection) // change from to >
.			public JSONArray put(Collection<?> value)	From to <?>
.			public JSONArray put(Map, ?> value)	From <Object,Object> to ,?>
.			public JSONArray put(int index, Collection<?> value) throws JSONException	From to <?>
.			public JSONArray put(int index, Map, ?> value) throws JSONException	From <Object,Object> to ,?>
.		JSONObject.java	public JSONObject(Map, ?> map)	From <Object,Object> to ,?>
.			public JSONObject put(String key, Collection<?> value) throws JSONException	From to <?>
.			public JSONObject put(String key, Map, ?> value) throws JSONException	From <Object,Object> to ,?>
20150729	140	JSONArray.java	public <E extends Enum> E getEnum(Class clazz, int index) throws JSONException	New
.			public <E extends Enum> E optEnum(Class clazz, int index)	New
.			public <E extends Enum> E optEnum(Class clazz, int index, E defaultValue)	New
.		JSONObject	public <E extends Enum> E getEnum(Class clazz, String key) throws JSONException	New
.			public <E extends Enum> E optEnum(Class clazz, String key)	New
.			public <E extends Enum> E optEnum(Class clazz, String key, E defaultValue)	New
.	135	JSONArray.java	public BigDecimal getBigDecimal (int index) throws JSONException	New
.			public BigInteger getBigInteger (int index) throws JSONException	New
.			public BigInteger optBigInteger(int index, BigInteger defaultValue)	New
.			public BigDecimal optBigDecimal(int index, BigDecimal defaultValue)	New
.		JSONObject.java	public BigInteger getBigInteger(String key) throws JSONException	New
.			public BigDecimal getBigDecimal(String key) throws JSONException	New
.			public BigInteger optBigInteger(String key, BigInteger defaultValue)	New
.			public BigDecimal optBigDecimal(String key, BigDecimal defaultValue)	New
.	132	JSONArray.java	public class JSONArray implements Iterable	Made iterable
.			public Iterator iterator()	New

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FAQ

Table of contents