What is JSON Schema?

What is JSON Schema?

If you’ve ever worked with XML Schema, RelaxNG, or asn.1, you probably already know what JSON Schema is and can skip this article. If you’re hearing this word for the first time, or if you’ve heard it before but don’t understand it, you’ve come to the right place.

To understand what JSON Schema is, we should first understand what JSON is.

JSON stands for “JavaScript Object Notation”, a simple format for exchanging data over the Internet. Because JavaScript exists in most Web browsers, and JSON is based on JavaScript, it’s easy to support in JavaScript. At the same time, it has proved useful and simple enough that it is now used in many other environments that do not involve data exchange over the Internet.

In essence, JSON is built on the following data structures:

Object: {"key1": "value1"."key2": "value2"} array: ["first"."second"."third"] Value: 42 3.1415926 Character string:"This is a string"Boolean:true falseNull: nullCopy the code

These types have close equivalents in most programming languages, but they may go by different names.

With these simple data types, a variety of structured data can be represented. However, with this great flexibility comes great responsibility, because the same concept can be expressed in an infinite number of ways. For example, you can imagine representing information about someone in JSON in different ways:

{ 
  "name": "George Washington"."birthday": "February 22, 1732"."address": "Mount Vernon, Virginia, United States"
}
Copy the code

And:

{ 
  "first_name": "George"."last_name": "Washington"."birthday": "1732-02-22"."address": {
    "street_address": "3200 Mount Vernon Memorial Highway"."city": "Mount Vernon"."state": "Virginia"."country": "United States"}}Copy the code

Both statements are equally valid, but the second is clearly more formal than the first. The design of data records depends largely on their intended use in the application, so there is no right or wrong answer. However, when an application requests a PERSON’s JSON record through the API and expects it, it is important to know exactly how the record should be organized. That said, JSON Schema comes in handy when we need to know how to expect fields and values to be represented in JSON data.

The following JSON Schema fragment describes how the second example above is built. We won’t go into the details here, but if you look closely, you can see that the JSON data structure in the second example above, and the type information of the individual fields in it, are clearly explained here.

{
  "type": "object"."properties": {
    "first_name": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    },
    "birthday": {
      "type": "string"."format": "date"
    },
    "address": {
      "type": "object"."properties": {
        "street_address": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "country": {
          "type": "string"
        }
      }
    }
  }
}
Copy the code

By “validating” the first sample JSON data for this JSON Schema, you can see that it fails:

{
  "name": "George Washington"."birthday": "February 22, 1732"."address": "Mount Vernon, Virginia, United States"
}
Copy the code

However, the second example goes through:

{
  "first_name": "George"."last_name": "Washington"."birthday": "22-02-1732"."address": {
    "street_address": "3200 Mount Vernon Memorial Highway"."city": "Mount Vernon"."state": "Virginia"."country": "United States"}}Copy the code

You may have noticed that the JSON Schema itself is written in JSON. It is a specification for JSON data, not a computer program. It is simply a declarative format for describing JSON data structures. This is both its strength and its weakness (similar to other Schema languages). It is easy and concise to describe the surface structure of the data and can be used to automatically validate the data while the program is running. However, because JSON Schema cannot contain arbitrary code, there are some limitations on relationships between data elements that cannot be expressed. Thus, any “validation tool” for sufficiently complex data formats may have two validation phases: one at the structural level and one at the semantic level. For structure-level checks, the Schema language can be used. For semantic-level checks, you may need to use a more general programming language.

JSON Schema plays an important role in the design and implementation of API. API implementations with JSON Schema validation capabilities can help automate validation of data from user input and in various scenarios where validation needs to be done at runtime. This helps developers to describe the JSON data hosted on their apis in a more formal and rigorous manner, while reducing the amount of manual verification code they have to write.

Unfortunately, popular REST API designs do not directly leverage JSON Schema’s capabilities. This is largely due to the fact that the API request parameters are not a JSON object, but rather described in the form of a resource model. This makes it impossible to use JSON Schema to describe and automate validation of data passed on such apis.

In CEAMS general enterprise application interface management system, the system does not use REST API design style, but refers to the classic SOAP protocol design, stipulates that the API request parameters and return results must be a JSON object or array, An API specification design wizard with JSON Schema support is provided for developers, where users can easily design and formulate their own JSON data specifications on the API. At the same time, the designed JSON Schema will complete the verification of the REQUESTED and returned JSON data during the execution of the program, which helps improve the security of API data and avoids the tedious verification code written by hand.

In addition to being used for verifying JSON data, JSON Schema also has good application scenarios in automatic API documents, automatic input form generation, and JSON data visualization, because it can provide clear and rigorous declarations for JSON data. A number of open source projects provide the ability to automate input form generation based on JSON Schema. CEAMS integrates well-known Angular Schema Forms to provide developers with a clear, intuitive API testing tool. Such tools help developers further simplify the PROCESS of API testing and improve the efficiency of testing.