Skip to content

FAQ

Jump to bottom
Sean Leary edited this page Dec 3, 2017 · 57 revisions

Table of contents

Who is allowed to submit pull requests for this project?

How do you decide which pull requests to accept?

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

Why isn't ordering allowed in JSONObjects?

Will ordering ever be allowed in JSONObjects?

Where are the unit tests?

What is the goal of this project?

What kind of changes will be accepted for this project?

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

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

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

I want to add an external lib to the project

Can you help me debug my code?

What version of Java does this project require?

Can you change the license to remove the "The Software shall be used for Good, not Evil." line?

Who is allowed to submit pull requests for this project?

Any 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 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 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.
  • Has Douglas Crockford already spoken on this issue? If so, we follow his guidance. No exceptions.

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 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 7159: "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 can be found in https://github.com/stleary/JSON-Java-unit-test, along with instructions for combining the tests with this app. They are not included in the project for the sake of developers who just want the library code and nothing more. It is not expected that this will ever change. Instructions to quickly and easily clone the 2 projects and execute the tests are included in the unit test project.

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 7159 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 are given high priority.
  • Build enhancements will not be accepted (although build enhancements to the unit tests are welcome).
  • Style and formatting changes will not be accepted.
  • Adding new functionality will be considered.
  • Changes to existing behavior will only be accepted in the case of bugs where the existing behavior is clearly worse than the fix.

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. We want to fix as many bugs as possible, but we also don't want existing users' code to break just because they upgraded to a newer version of the library. 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 6 is required, in order to support Android devices. This is not a project requirement but we are going to try to support Android for as long as practical. That means we cannot accept pull requests that require Java 7 or greater.

You can see the following PR requests for more information on why we are using Java6 support:

Can you change the license to remove the "The Software shall be used for Good, not Evil." line?

The library author specified this license, and is the only person authorized to change it.

Clone this wiki locally