4.5 JSON Schema Validation

From version 8.0.21, collections can be configured to verify documents against a JSON schema. This enables you to require that documents have a certain structure before they can be inserted or updated in a collection. You specify a JSON schema as described at http://json-schema.org. Schema validation is performed by the server from version 8.0.19, and which returns an error message if a document in a collection does not validate against the assigned JSON schema. For more information on JSON schema validation in MySQL, see JSON Schema Validation Functions. This section describes how to configure a collection to validate documents against a JSON schema.

Note

Connector/J implements JSON schema validation very differently from the model described below. See Schema Validation in the MySQL Connector/J 8.0 Developer Guide for details.

To enable or modify JSON schema validation you pass in a JSON object like:

{
    validation: {
      level: "off|strict",
      schema: "json-schema"
    }
}

Here, validation is JSON object which contains the keys you can use to configure JSON schema validation. The first key is level, which can take the value strict or off. The second key, schema, is a JSON schema, as defined at http://json-schema.org. If the level key is set to strict, documents are validated against the json-schema when they are added to the collection, or when an operation updates the document. If the document does not validate, the server generates an error and the operation fails. If the level key is set to off, documents are not validated against the json-schema.

Creating a Validated Collection

To enable JSON schema validation when you create a new collection, pass in a validation JSON object as described in the introduction. For example, to create a collection that holds longitude and latitude values and validate that these values should be numbers and are required for the document to validate, issue:

MySQL Shell JavaScript Code

var coll = schema.createCollection("longlang", {
  validation: {
    level: "strict",
    schema:   {
      "id": "http://json-schema.org/geo",
      "$schema": "http://json-schema.org/draft-06/schema#",
      "description": "A geographical coordinate",
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number"
        },
        "longitude": {
          "type": "number"
        }
      },
      "required": ["latitude", "longitude"]
    }
  }
})

MySQL Shell Python Code

coll = schema.create_collection("longlang", validation={
    "level": "strict",
    "schema":   {
        "id": "http://json-schema.org/geo",
        "$schema": "http://json-schema.org/draft-06/schema#",
        "description": "A geographical coordinate",
        "type": "object",
        "properties": {
            "latitude": {
                "type": "number"
            },
            "longitude": {
                "type": "number"
            }
        },
        "required": ["latitude", "longitude"]
    }
})

Node.js JavaScript Code

var coll = schema.createCollection("longlang", {
  validation: {
    level: "strict",
    schema:   {
      "id": "http://json-schema.org/geo",
      "$schema": "http://json-schema.org/draft-06/schema#",
      "description": "A geographical coordinate",
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number"
        },
        "longitude": {
          "type": "number"
        }
      },
      "required": ["latitude", "longitude"]
    }
  }
})

C# Code

var collOptions = CreateCollectionOptions() {
  reuseExistingObject = false,
  validation = Validation() {
    level = ValidationLevel.Strict,
    schema = "{\"id\": \"http://json-schema.org/geo\","
             + "\"$schema\": \"http://json-schema.org/draft-06/schema#\","
             + "       \"description\": \"A geographical coordinate\","
             + "       \"type\": \"object\","
             + "       \"properties\": {"
             + "          \"latitude\": {"
             + "             \"type\": \"number\""
             + "          },"
             + "          \"longitude\": {"
             + "             \"type\": \"number\""
             + "          }"
             + "       },"
             + "       \"required\": [\"latitude\", \"longitude\"]"
             + "  }"
    }
};

var coll = schema.CreateCollection("longlang", collOptions);

Python Code

coll = schema.create_collection("longlang", validation={
    "level": "strict",
    "schema":   {
        "id": "http://json-schema.org/geo",
        "$schema": "http://json-schema.org/draft-06/schema#",
        "description": "A geographical coordinate",
        "type": "object",
        "properties": {
            "latitude": {
                "type": "number"
            },
            "longitude": {
                "type": "number"
            }
        },
        "required": ["latitude", "longitude"]
    }
})

Modifying Collection Validation

You can modify a collection to control the JSON schema validation of documents. For example you can enable or disable validation, or change the JSON schema which documents are validated against.

In order to modify the JSON schema validation of a collection, pass in a validation JSON object as described in the introduction. For example, to modify a collection to disable JSON schema validation, the JSON object would be:

{ 
   validation: {
       "level": "off"
   }
}

When modifying the JSON schema validation, you can pass in only the level option to change the level of schema validation. For example, pass in the JSON object demonstrated to disable JSON schema validation. This makes no change to the JSON schema previously specified, and it is not removed. Alternatively, you can modify only the schema by passing in a new JSON schema object, in the same way as described at Creating a Validated Collection.