Json схема как составить

JSON (JavaScript Object Notation) is a simple and lightweight text-based data format. JSON Schema is an IETF standard providing a format for what JSON data is required for a given application and how to interact with it. Applying such standards for a JSON document lets you enforce consistency and data validity across similar JSON data.

.Let’s take a look at a document example with a person’s name and their indoor and outdoor hobbies.

{
  "id": 7,
  "name": "John Doe",
  "age": 22,
  "hobbies": {
        "indoor": [
            "Chess"
        ],
        "outdoor": [
            "BasketballStand-up Comedy"
        ]
    }
}

If you were to look at the above example, you would not necessarily know if id can be zero (0). You would also not know if you could leave age blank. For this reason, we need to have metadata that holds information about valid data types and the description of the keys. Additionally, JSON Schema gives you a standard way to structure the metadata.

Basic JSON Schema Example

Let’s look at an example of a JSON Schema for the above document type.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$id": "https://example.com/employee.schema.json",
    "title": "Record of employee",
    "description": "This document records the details of an employee",
    "type": "object",
    "properties": {
        "id": {
            "description": "A unique identifier for an employee",
            "type": "number"
        },
        "name": {
            "description": "Full name of the employee",
            "type": "string"
        },
        "age": {
            "description": "Age of the employee",
            "type": "number"
        },
        "hobbies": {
            "description": "Hobbies of the employee",
            "type": "object",
            "properties": {
                "indoor": {
                    "type": "array",
                    "items": {
                        "description": "List of indoor hobbies",
                        "type": "string"
                    }
                },
                "outdoor": {
                    "type": "array",
                    "items": {
                        "description": "List of outdoor hobbies",
                        "type": "string"
                    }
                }
            }
        }
    }
}

It could look daunting at first glance but we will break it down to understand further.

JSON Schema Keywords and Properties

We have different keywords that are used in the above example. The following list explains what each of these keywords mean.

• $schema: States that this schema complies with v4 of the IETF standard
• $id: Defines the base URI to resolve other URI references within the schema.
• title: Describes the intent of the schema.
• description: Gives the description of the schema.
• type: Defines the type of data.
• properties: Defines various keys and their value types within a JSON document.
• minimum: Defines the minimum acceptable value for a numeric datatype.
• items: Enumerates the definition for the items that can appear in an array.
• minItems: Defines the minimum number of items that should appear in an array.
• uniqueItems: Enforces if every item in the array should be unique relative to one another.
• required: Lists the keys that are required and mandatory.

For a full list of keywords, visit json-schema.org. The link explains the keywords that you can use in your schema and their purpose.

How do I create a JSON schema?

You can use online JSON schema generators if you have a simple JSON document, then modify the schema as per the requirement of your project. Alternatively, you can build a JSON schema of your own from scratch by following the steps below

Starting the Schema

If you have already familiarized yourself with the JSON schema keywords and properties, we can jump right into starting a basic JSON schema. Lets begin with five basic keywords to define an employee.

Base Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "title": "Record of Employee",
  "description": "This document records the details of an employee",
  "type": "object"
}

In the above example, $schema links to the resource that identifies the dialect and the valid schemas written for this dialect.

$id keyword identifies the schema resource. Here are a couple of things to know about this keyword:

• The URI in this keyword is an identifier and not necessarily a network locator.
• It must be a string.
• It must represent a valid URI reference that is normalized and resolves absolute URI.
• It must not contain a non empty fragment.
• It should not contain an empty fragment.

title keyword gives a short description of the schema and you can use the description keyword to explain more about the schema. In the above example, the title hints that this schema is about a record of an employee and the description explains that in detail.

type keyword explains the valid data type of a record. In the above example, type sets the constraint for this document and tells us that this record is an object.

JSON Schema Properties

The Entry Schema

The schema that we have used in the above section is a basic outline. Lets build on it by adding an id field to the employee record.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$id": "https://example.com/employee.schema.json",
    "title": "Record of employee",
    "description": "This document records the details of an employee",
    "type": "object",
    "properties": {
        "id": {
            "description": "A unique identifier for an employee",
            "type": "number"
        }
    }
}

We have added two sub-properties, “id.description”, stating that it is a unique identifier, and “id.type”, explaining that it is a number.

Let’s do the same for name and age — but this time, with new keywords.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$id": "https://example.com/employee.schema.json",
    "title": "Record of employee",
    "description": "This document records the details of an employee",
    "type": "object",
    "properties": {
        "id": {
            "description": "A unique identifier for an employee",
            "type": "string"
        },
        "name": {
            "description": "full name of the employee",
            "type": "string"
            "minLength":2
        },
        "age": {
            "description": "age of the employee",
            "type": "number",
            "minimum": 16
        }
    },
    "required": [
        "id"  
        "name",
        "age"
    ]
}

In the name property, we have introduced the minLength keyword to make sure that the property has at least two characters. Similarly, in the age property, we have used the minimum keyword to ensure that the age of the employee exceeds 16 everytime. It can be of type number or type integer. We have also used the required keyword to define the mandatory properties. Now, let’s take it a step further and add an object inside the employee object.

Nesting Data Structures

To add an object inside an object in JSON format, we use nested data structure. Creating subschemas for Nested objects work quite similarly to the creating schemas for root objects. You can use all the schema keywords that you used when defining the root object except for $schema and $id. They only have to be stated at the beginning of a schema.

Arrays of Things

The following example shows how we can create an object within an object that takes an array type data. Here, we will use a few new keywords in addition to the ones we have already used.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$id": "https://example.com/employee.schema.json",
    "title": "Record of employee",
    "description": "This document records the details of an employee",
    "type": "object",
    "properties": {
        "id": {
            "description": "A unique identifier for an employee",
            "type": "number"
        },
        "name": {
            "description": "name of the employee",
            "type": "string",
            "minLength":2
        },
        "age": {
            "description": "age of the employee",
            "type": "number",
            "minimum": 16
        },
        "hobbies": {
            "description": "hobbies of the employee",
            "type": "object",
            "properties": {
                "indoor": {
                    "type": "array",
                    "items": {
                        "description": "List of hobbies",
                        "type": "string"
                    },
                    "minItems": 1,
                    "uniqueItems": true
                },
                "outdoor": {
                    "type": "array",
                    "items": {
                        "description": "List of hobbies",
                        "type": "string"
                    },
                    "minItems": 1,
                    "uniqueItems": true
                }
            },
            "required": [
                "indoor",
                "outdoor"
            ]
        }
    },
    "required": [
        "id",
        "name",
        "age",
        "hobbies"
    ],
 "additionalProperties": false
}

In the above example, we have defined two array fields – indoor and outdoor in the “hobbies” object. You might have noticed the items keyword. This keyword defines the properties of each item.

Similarly, minItems defines the minimum number of items that must be present in the array, maxItems defines the maximum number of items that can be present within the array uniqueItems uniquely identifies each item.

You will also see the required keyword again within the subobject. Like the required keyword in the root JSON object, the required keyword within the subobject dictates the mandatory properties within the subobjects.

Lastly, we have also introduced additionalProperties. In the above example, it is a boolean taking the value false , telling us that we can’t use any other property that isn’t listed under the properties keyword.

However, additionalProperties doesn’t necessarily have to be a boolean. It can also be an object. For example, in the schema below, this keyword is stating that any additional property that we use under this schema is required to be of type string.

"additionalProperties": { "type": "string" }

Describing Geographical Coordinates

Though the above example is limited to a use case, there are limitless uses of JSON schema. One of the areas where JSON schema can be used to validate and enforce consistency is with geographical coordinates. Because of the nature of the data, there is a high chance of accepting invalid or inconsistent data.

In the example below, we can see that coordinates are represented using numeric data types.

{
  "latitude": 58.858093,
  "longitude": 22.294694
}

But there is a limit to the value that we can use for a coordinate i.e., the values cannot be more than 90 or less than negative 90. So let’s create a JSON schema to address this scenario.

{
  "$id": "https://example.com/geographical-location.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Longitude and Latitude Values",
  "description": "A geographical coordinate.",
  "required": [ "latitude", "longitude" ],
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    }
  }
}

Here you can see that we have used the minimum and maximum keyword for each property to limit the range of acceptable values. This not only resolves the issue with data validation but also ensures that incorrect values do not get through.

Using Your Schema for Validation in MongoDB Atlas

You can use $jsonSchema in a document validator to enforce the specified schema on insert and update operations in MongoDB, including in MongoDB Atlas. Since MongoDB stores the data in BSON (Binary JSON), you can easily store and retrieve all your data in JSON format.

MongoDB also lets you enforce a schema to validate your data and maintain a data structure. We will use MongoDB Atlas and MongoDB Compass to demonstrate how.

Suppose we insert the following documents into a collection named employees inside a database named mongodatabase.

Document 1

{
    "id": 7,
    "name": "John Doe",
    "age": 22,
    "hobbies": {
        "indoor": [
            "Chess"
        ],
        "outdoor": [
            "Basketball"
        ]
    }
}

Document 2

{
     "id": 8,
     "name": "Jonathon Smith",
     "age": 22
}

Document 3

{
    "id": 1,
    "name": "Jane Doe",
    "age": 25,
    "hobbies": {
        "indoor": [
            "Chess"
        ],
        "outdoor": [
            "Football"
        ]
    }
}

We will enforce the schema from the previous section to validate these documents in MongoDB Compass.

Firstly, let’s connect our cluster with our Compass.

• Log into MongoDB Atlas and click Clusters
• Click on CONNECT to connect with your cluster.
• Set up connection security by adding your IP address and creating a database user. Then select Choose a connection method.
• Select Connect using MongoDB Compass.
• Download MongoDB Compass if you have not already and copy the connection string.
• Open MongoDB Compass and paste the connection string. Your connection string should look similar to this:

mongodb+srv://<username>:<password>@cluster0.9ddm0.mongodb.net/test

Replace <username> and <password> with the username and password of the database user that you created.

Now, let’s go into the mongodatabase and look at the documents inside the employees collection.

Click on the Validation tab and insert the following JSON schema to validate our documents. Begin the schema definition with $jsonSchema keyword. Because we don’t need the $id and $schema keywords to get started, we will remove them.

{
  $jsonSchema: {
    "title": "Record of employee",
    "description": "This document records the details of an employee",
    "type": "object",
    "properties": {
        "id": {
            "description": "A unique identifier for an employee",
            "type": "number"
        },
        "name": {
            "description": "name of the employee",
            "type": "string",
            "minLength":2
        },
        "age": {
            "description": "age of the employee",
            "type": "number",
            "minimum": 16
        },
        "hobbies": {
            "description": "hobbies of the employee",
            "type": "object",
            "properties": {
                "indoor": {
                    "type": "array",
                    "items": {
                        "description": "List of hobbies",
                        "type": "string"
                    },
                    "minItems": 1,
                    "uniqueItems": true
                },
                "outdoor": {
                    "type": "array",
                    "items": {
                        "description": "List of hobbies",
                        "type": "string"
                    },
                    "minItems": 1,
                    "uniqueItems": true
                }
            },
            "required": [
                "indoor",
                "outdoor"
            ]
        }
    },
    "required": [
        "id",
        "name",
        "age",
        "hobbies"
    ],
 "additionalProperties": false
}
}

If you have followed the steps so far, you should get the following result.

As our schema requires a hobbies field in every document, the document with the id: 8 fails because it didn’t contain the required field.

You can also set additional validation rules by following the documentation on setting validation rules for your schema. To match documents that satisfy the specified JSON Schema, you can use the $jsonSchema operator. The MongoDB JSON Schema documentation is an excellent resource to get you up and running.

To learn more about MongoDB Atlas, refer to this article.

Next Steps

By now, you should understand the JSON Schema, why it is used, and how we can use it. We have certainly expanded on the concept and how you can use it with MongoDB but there is more to cover.

If you want to learn more about JSON Schema with MongoDB, we recommend you go through MongoDB’s JSON Schema validation resource. If you are interested in knowing more about JSON Schema validation generally, visit this article.

FAQs

Последнее изменение: 11.10.2019

Schema

Examples

$anchor

{
 "$id": "http://example.com",
 
 "$ref": "#mail",
 
 "$defs": {
  "mail": {
   "$anchor": "mail",
   "format": "email"
  }
 }
}

$id

{
 "$id": "http://example.com",

 "$ref": "#mail",
 
 "$defs": {
  "mail": {
   "$id": "#mail",
   "format": "email"
  }
 }
}

Schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 18,
      "maximum": 150
    }
  },
  "required": ["email"]
}

Examples

Schema

{
  "type": "array",
  "minItems": 2,
  "items": {
    "type": ["string", "number"]
  }
}

Examples

Copyright © Zindex Software. All rights reserved

Let’s pretend we’re interacting with a JSON based product catalog. This catalog has a product which has an id, a name, a price, and an optional set of tags.

Example JSON data for a product API

An example product in this API is:

{
    "id": 1,
    "name": "A green door",
    "price": 12.50,
    "tags": ["home", "green"]
}

While generally straightforward, that example leaves some open questions. For example, one may ask:

• What is id?
• Is name required?
• Can price be 0?
• Are all tags strings?

When you’re talking about a data format, you want to have metadata about what fields mean, and what valid inputs for those fields are. JSON schema is a specification for standardizing how to answer those questions for JSON data.

To start a schema definition, let’s begin with a basic JSON schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme's catalog",
    "type": "object"
}

The above schema has four properties called keywords.

The title and description keywords are descriptive only, in that they do not add
constraints to the data being validated. The intent of the schema is stated with these two keywords
(that is, this schema describes a product).

The type keyword defines the first constraint on our JSON data: it has to be a JSON
Object.

Finally, the $schema keyword states that this schema is written according to the draft
v4 specification.

Next let’s answer our previous questions about this API, starting with id.

What is id?

id is a numeric value that uniquely identifies a product. Since this is the canonical identifier for a product, it doesn’t make sense to have a product without one, so it is required.

In JSON Schema terms, we can update our schema to:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme's catalog",
    "type": "object",
    "properties": {
        "id": {
            "description": "The unique identifier for a product",
            "type": "integer"
        }
    },
    "required": ["id"]
}

Is name required?

name is a string value that describes a product. Since there isn’t
much to a product without a name, it also is required. Adding this gives us the schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme's catalog",
    "type": "object",
    "properties": {
        "id": {
            "description": "The unique identifier for a product",
            "type": "integer"
        },
        "name": {
            "description": "Name of the product",
            "type": "string"
        }
    },
    "required": ["id", "name"]
}

Can price be 0?

According to Acme’s docs, there are no free products. In JSON schema a number can have a minimum. By default this minimum is inclusive, so we need to specify exclusiveMinimum. Therefore we can update our schema with price:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme's catalog",
    "type": "object",
    "properties": {
        "id": {
            "description": "The unique identifier for a product",
            "type": "integer"
        },
        "name": {
            "description": "Name of the product",
            "type": "string"
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        }
    },
    "required": ["id", "name", "price"]
}

Are all tags strings?

Finally, we come to the tags property. Unlike the previous
properties, tags have many values, and is represented as a JSON array. According
to Acme’s docs, all tags must be strings, but you aren’t required to specify
tags. We simply leave tags out of the list of required properties.

However, Acme’s docs add two constraints:

• there must be at least one tag,
• all tags must be unique.

The first constraint can be added with minItems, and the second one by
specifying uniqueItems as being true:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme's catalog",
    "type": "object",
    "properties": {
        "id": {
            "description": "The unique identifier for a product",
            "type": "integer"
        },
        "name": {
            "description": "Name of the product",
            "type": "string"
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        },
        "tags": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "minItems": 1,
            "uniqueItems": true
        }
    },
    "required": ["id", "name", "price"]
}

The above example is by no means definitive of all the types of data JSON schema can define. For more definitive information see the full standard draft.

As a final example, here’s a spec for an array of products, with the products having 2 new properties. The first is a dimensions property for the size of the product, and the second is a warehouseLocation field for where the warehouse that stores them is geographically located.

And also, since JSON Schema defines a reference schema for a geographic location, instead of coming up with our own, we’ll reference the canonical one.

Set of products:

[
    {
        "id": 2,
        "name": "An ice sculpture",
        "price": 12.50,
        "tags": ["cold", "ice"],
        "dimensions": {
            "length": 7.0,
            "width": 12.0,
            "height": 9.5
        },
        "warehouseLocation": {
            "latitude": -78.75,
            "longitude": 20.4
        }
    },
    {
        "id": 3,
        "name": "A blue mouse",
        "price": 25.50,
        "dimensions": {
            "length": 3.1,
            "width": 1.0,
            "height": 1.0
        },
        "warehouseLocation": {
            "latitude": 54.4,
            "longitude": -32.7
        }
    }
]

Set of products schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product set",
    "type": "array",
    "items": {
        "title": "Product",
        "type": "object",
        "properties": {
            "id": {
                "description": "The unique identifier for a product",
                "type": "number"
            },
            "name": {
                "type": "string"
            },
            "price": {
                "type": "number",
                "minimum": 0,
                "exclusiveMinimum": true
            },
            "tags": {
                "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"]
            },
            "warehouseLocation": {
                "description": "Coordinates of the warehouse with the product",
                "$ref": "http://json-schema.org/geo"
            }
        },
        "required": ["id", "name", "price"]
    }
}