Getting Started with JSON Schema

If you are experienced in Information and Technology, you must be aware of the importance of getting JSON documents validated and elucidated. For the same, many tools are used. JSON Schema is one such tool, or to be precise, a vocabulary, to validate the structure of JSON documents by providing the needed structure, definition, semantics, and content improvement to the object.

A schema is said to be the blueprint of the JSON document. It offers a concise and clear document comprehendible by humans and machines in an easy manner. The structure it provides proves useful in machine testing and validating data submitted via a client. But, how to get started with it?

Let us go with an example of a JSON product catalog. To initiate a schema, opting for a basic one, to begin with, the first step is to start with its four properties. They are known as “keywords” and are expressed as JSON keys. The keywords are as follows:

“$schema” - This keyword points out that the schema is written per a certain draft of the standard and is opted for many reasons, of which version control is a major one.
“$id” - This keyword shows the URI for the schema.
“title” and “description” - Merely used for displaying intent and are only descriptive.
“type” - Defines the initial constraint.

In the above keywords, a) and b) are schema keywords, c) are annotations, while d) refers to validation keywords.

The next step is to define the properties. A unique identifier for products is used in the second step. It is in the form of an arithmetic value and is referred to as “productId”. We use the above-stated validation and annotation keywords. A string value is used to give a name to the product. The value is referred to as “productName”. An interesting fact is that “productId” and “productName” are the same, yet both are to be used to create ease for human readers (name) and machines (Id).

To include more factors (like price, discounts, specifications), we dwell deeper into the properties with the third step. Price is denoted using “description” and “type”. If, for example, the price cannot be zero, then we must specify the “minimum” and “exclusiveMinimum” keywords for validation.

The “tags” key can be used to fulfill other criteria and specifications, if any, demanded by the client. E.g., If the requirement is that each tag should be unique, “uniqueItems” keyword will be used.

Now, what we have is a unidimensional schema without any complications. To increase its levels, the “dimensions” key should be used to nest subsequent data structures. The “properties” key should be used to define it, while the “description” key is not required here. With this and finally, the “required” key (the scope of this key is limited to dimensions), we would be able to feed in more levels.

You can also put references out of the schema since, till now, the coding is completely limited to self. Transfers of schema with various data structures are useful to improve its maintenance, convenience to read and ensure reusability. A combination of “minimum” and “maximum” keys enables us to decide a range for validation, and later on, references can be incorporated easily.

There you have your structured data in a JSON document. Merely reading the guide will be just like reading about how to swim; theoretical and practical applications are different. So, practice it and get acquainted with this tool.

Other useful articles: