A Great Future Created by JSON Schema

JSON has been increasingly adopted as a Web API format. While JSON can be handled easily in light description languages, the trouble it has with assuring data content is viewed as problematic. For this reason, JSON Schema, which defines the structure of JSON, has attracted attention. By providing types and meta-information to JSON data, rules for formatting are added.

JSON Schema is currently being developed as a specification. You can check the details at JSON Schema and Hyper-Schema.

We’d like to think about what possibilities adopting JSON Schema can bring.

1. Validation

The primary one that comes to mind is validation. This can be done for both clients and servers. JSON Schema enables you to verify data before sending and automatically validate data you obtain.

If the verification results produce errors, you should probably return them as they are. As usage of data structures and types is assured after verification, you can feel secure when writing code.

2. Create Libraries that Handle Data

This is similar to how "Web Service" often automatically generate code from a schema like WSDL. It will automatically generate skeleton code if it’s for Java or .NET, and it will automatically create methods for script languages such as Ruby, PHP, and Python.

JSON is often handled with hash and associative array after parsing. However, by generating code in advance, you’ll be able to use it as easy-to-handle data.

3. Generate Documents

In addition, since JSON Schema explains parameters and also handles descriptions for data structures and URLs, it can be used for generating API documents, too. Although consistency must be maintained due to separation from the actual code, you can maintain the latest state by combining JSON with testing structures, which will be mentioned later on this page.

As there are many developers who refer to API documents, such output should motivate you to properly maintain JSON Schema.

4. Dummy Server

JSON Schema can be used as a base for library test servers that handle Web APIs. Although the logic parts of the server cannot be assured, having a dummy server makes local development and operation in a test environment easy.

However, while you can check requirements and types of input values on dummy servers, it doesn’t allow you to check logic, such as token validity. Note that it’s better to use it as an auxiliary tool during development.

5. Automating Test

Also, JSON Schema can be used for operating tests for a Web API itself. Post the pre-defined values, and you can verify whether the expected results will be produced. Systems that previously used Web APIs may suddenly stop working, for instance, when new required fields are added to extend the Web API. Also, in such circumstances, it is important for JSON Schema to manage versions and check whether it’s continuously operating with all versions.

After software that uses a Web API is complete, the software often enters an automatic operation phase. In order to ensure results even in such circumstances, JSON Schema can be useful.

6, Error Check During Development

With IDEs and such, adopting JSON Schema enables you to display advance warnings. The JSON structure has low readability when kept in text form, and it is often read incorrectly. JSON Schema could be useful to prevent these mistakes.

Although JSON Schema has several merits, because it was originally developed to stay away from the complexity and nuisances of WSDL and such, it has not been widely adopted. However, it will turn into an important element, as Web APIs will be used more and more often at the enterprise companies.

Rather than just being something that you should do, I believe JSON Schema will be used more if it can improve development productivity and reduce burden, for example, by automatically creating documents using JSON Schema.