Introduction to JSON Schema Basics

JSON is a lightweight data exchange format. Its basic structure is a collection of "name / value" pairs. It is very easy for people to read and write, and also easy for machine parsing and generation.

Previous articles: Basic introduction and code test of cJSON , the use of C language format cJSON library has been introduced. This article introduces the JSON Schema closely related to JSON.

1 problem introduction

Suppose that in an actual project, we use json to describe the information of a product, which has:

Identifier: productId
Product Name: product name
Sales price: price
An optional set of tags: Tags

It is represented by JSON as follows:

{
  "productId": 1,
  "productName": "A green door",
  "price": 12.50,
  "tags": [ "home", "green" ]
}

It seems very concise, but this description also leaves some problems, such as:

What does productId mean?
Is productName required?
Can price be zero?
Are tags all strings?

If we arbitrarily give some unrealistic values to the JSON data here, it will have an unexpected impact. Therefore, there needs to be a rule to restrict the validity of JSON data, which should be described by JSON Schema.

2 JSON Schema

JSON Schema is a proposed IETF standard to solve the problem of data format description mentioned earlier. JSON Schema itself uses JSON data format.

Let's take a look at the basic syntax of JSON Schema.

2.1 beginning of schema

Let's start with the properties of the four keywords

$schema: used to specify JSON Schema version information, which can be omitted. Note: if this keyword is used, its value must use the value officially provided, and cannot be written by yourself.
$id: defines the URI of the Schema and the basic URI on which other URI references in the Schema are resolved. It can be omitted.
title and description: only descriptive. They do not add constraints to the data being verified and can be omitted.
type: first constraint to validate JSON data. In this example, our JSON data must be a JSON object.

Here is a basic JSON Schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "title": "Product",
  "description": "A product in the catalog",
  "type": "object"
}

From the above example, we have a brief understanding of the structure at the beginning of JSON Schema:

Schema keyword: schema and id
Schema comments: title and description
Validation keyword: type

2.2 attribute definition

The type keyword describes the overall type of json data. How to describe the internal elements of json data depends on the properties keyword.

Another required keyword is introduced to describe which keywords are required in JSON data. For example, productId is the only value identifying the product.

The JSON Schema after adding attribute information is as follows:

{
  "title": "Product",
  "description": "A product from Acme's catalog",
  "type": "object",
  "properties": {
    "productId": {
      "description": "The unique identifier for a product",
      "type": "integer"
    }
  },
  "required": [ "productId" ]
}

Imitate the description of the product IDproductId and continue to supplement the product name productName.

Product name is also required. There is actually no difference between it and product name, because computers usually focus on ID, while humans usually focus on name. Note that the required keyword is an array of strings that can record multiple values.

The supplemented JSON Schema is as follows:

{
  "title": "Product",
  "description": "A product from Acme's catalog",
  "type": "object",
  "properties": {
    "productId": {
      "description": "The unique identifier for a product",
      "type": "integer"
    },
    "productName": {
      "description": "Name of the product",
      "type": "string"
    }
  },
  "required": [ "productId", "productName" ]
}

At this time, according to the description of JSON Schema, our JSON data is as follows:

{
    "productId": 1,
    "productName": "A green door"
}

2.3 in depth understanding of attributes

Assuming that the product is not free, that is, the price is greater than 0, how to describe it?

Our JSON data now adds price data:

{
    "productId": 1,
    "productName": "A green door",
    "price": 12.50
}

We can use the exclusiveMinimum keyword to verify the minimum value of the specified value.

The JSON Schema supplemented with price is as follows:

{
  "title": "Product",
  "description": "A product from Acme's catalog",
  "type": "object",
  "properties": {
    "productId": {
      "description": "The unique identifier for a product",
      "type": "integer"
    },
    "productName": {
      "description": "Name of the product",
      "type": "string"
    },
    "price": {
      "description": "The price of the product",
      "type": "number",
      "exclusiveMinimum": 0
    }
  },
  "required": [ "productId", "productName", "price" ]
}

Next, let's look at the tags keyword. If this product has the following characteristics:

If there is a label, there must be at least one label,
Label must be text.
The label must be unique and there is no duplication in the product.
Labels are not required.

According to the above requirements, there is a corresponding Schema description:

The type verification keyword of tags is array, and the minItems keyword is used to verify the minimum number of elements in the array.
Use the items keyword to define what appears in the array. In this case, the value of the type validation keyword is string.
Use the uniqueItems keyword to verify that the elements in the array are unique to each other.
Do not add tags to the required validation keyword array, indicating that it is optional.

The JSON Schema after adding tag is as follows:

{
  "title": "Product",
  "description": "A product from Acme's catalog",
  "type": "object",
  "properties": {
    "productId": {
      "description": "The unique identifier for a product",
      "type": "integer"
    },
    "productName": {
      "description": "Name of the product",
      "type": "string"
    },
    "price": {
      "description": "The price of the product",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "tags": {
      "description": "Tags for the product",
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "uniqueItems": true
    }
  },
  "required": [ "productId", "productName", "price" ]
}

At this time, according to the description of JSON Schema, our JSON data is as follows:

{
    "productId": 1,
    "productName": "A green door",
    "price": 12.50,
    "tags": [ "home", "green" ]
}

2.4 nested data structures

So far, our JSON data has only one level.

How to describe multi-level nested JSON data (the element inside JSON data is a JSON object) with JSON Schema? For example, add dimension information dimensions to the product, which itself is a JSON object:

{
    "productId": 1,
    "productName": "A green door",
    "price": 12.50,
    "tags": [ "home", "green" ],
    "dimensions": {
        "length": 7.0,
        "width": 12.0,
        "height": 9.5
    }
}

For nested data, you can continue to describe JSON Schema accordingly.

The JSON Schema after adding dimensions is as follows:

{
  "title": "Product",
  "description": "A product from Acme's catalog",
  "type": "object",
  "properties": {
    "productId": {
      "description": "The unique identifier for a product",
      "type": "integer"
    },
    "productName": {
      "description": "Name of the product",
      "type": "string"
    },
    "price": {
      "description": "The price of the product",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "tags": {
      "description": "Tags for the product",
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "uniqueItems": true
    },
    "dimensions": {
      "type": "object",
      "properties": {
        "length": {
          "type": "number"
        },
        "width": {
          "type": "number"
        },
        "height": {
          "type": "number"
        }
      },
      "required": [ "length", "width", "height" ]
    }
  },
  "required": [ "productId", "productName", "price" ]
}

Note: for brevity, the description of dimensions is omitted in the example

3 validate JSON format using Shema

Many online websites can verify JSON data through JSON Schema, such as here: https://jsonschemalint.com/#/version/draft-07/markup/json

Copy the JSON Schema used in this article to the left border of the browser and the JSON data to the right border. You can see that both boxes are green, and the lower right corner prompts that the verification has passed.

We make some mistakes manually. For example, if the price field in JSON data is deleted, the whole border will turn red, and the following prompt is missing price.

For another example, adding a duplicate green tag to the tags array will also give an error prompt. These are the practical roles played by JSON Schema.

4 Summary

This chapter mainly introduces three points:

Relationship between JSON Schema and JSON: JSON Schema is a description of JSON data format.
Basic usage of JSON Schema. Learn about the usage of JSON Schema through some common validation Keywords:
- title and description: only descriptive and can be omitted.
- Type: verify the type of JSON data
- Properties: describes the specific properties of JSON internal data
- Required: describes which keywords are required in JSON data
- exclusiveMinimum: verifies the minimum value of the specified value
- minItems: verify the minimum number of elements in the array
- items: used to define the contents of the array
- uniqueItems: verify that the elements in the array are unique relative to each other.
Use JSON Schema to verify whether the corresponding JSON data meets the requirements.

Posted on Wed, 01 Dec 2021 16:48:02 -0500 by qing

Programmer Help