4.6 JSON Schema Validation

Staring 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 starting from version 8.0.19, 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 in this section. See Schema Validation in the MySQL Connector/J 8.0 Developer Guide for details.

To enable or modify JSON schema validation, you supply to a collection a validation JSON object like the following:

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

Here, validation is a JSON object that 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, if they are already in the collection, when they are updated by some operations. If a 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, supply a validation JSON object as described above. For example, to create a collection that holds longitude and latitude values and require validating those values as numbers:

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 that documents are validated against.

In order to modify the JSON schema validation of a collection, supply a validation JSON object when calling the Collection.modify() method. For example, to modify a collection to disable JSON schema validation, the validation object would be:

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

When modifying the JSON schema validation, you can supply the level option alone to change just the level of schema validation. For example, pass the JSON object shown above to disable JSON schema validation. This makes no change to the JSON schema previously specified and does not remove the JSON schema from the collection. Alternatively, you can modify the schema only by passing just a new JSON schema object.