Data Validation #

One common requirement when you are managing data is to perform data validation. In real world applications you may need to check that any newly created or updated document meet a certain criteria.

A common example is email validation. Let's say you have developed a registration page where you request a user's name and email and you want to ensure that the email they provide is valid.

With Kuzzle, instead of programming the validation logic yourself, you can pick from a set of predefined validation types. Validations are defined in a validation schema which determines what pattern is linked to what field, every time Kuzzle receives input data, it checks this validation schema and returns an error if a validation pattern fails. The validation schema can be configured in the validation field of the configuration file.

For a detailed look at the available properties and types, please refer to the Validation Reference at the end of this page.

Basic Validation #

A validation schema is defined using a hierarchical structure that contains a set of rules within an index, collection, and document field.

For example, below is a validation schema for the onlineshop index and products collection that defines the validation pattern for field price and field productDescription:

{
  "validation": {
    "onlineshop": {
      "products": {
        "fields": {
          "price": {
            "type": "numeric",
            "mandatory": true
          },
          "productDescription": {
            "type": "string",
            "defaultValue": "Sorry, no description available for this product."
          }
        }
      }
    }
  }
}

Let's take a look at what this validation schema does:

• It defines a set of rules for documents in the products collection of the onlineshop index.
• It ensures that price exists and is a number.
• It ensures that productDescription is a String and has a value when none is provided.

For a complete list of validation types please refer to the Validation Types reference.

Type Options #

Type Options can be used to provide advanced validation of certain fields. These are only available for some field types.

Below is an example of how the range type option is used to ensure that the field price is greater than zero:

{
  "validation": {
    "onlineshop": {
      "products": {
        "fields": {
          "price": {
            "type": "numeric",
            "mandatory": true,
            "typeOptions": {
              "range": {
                "min": 0
              }
            }
          },
          "productDescription": {
            "type": "string",
            "defaultValue": "Sorry, no description available for this product."
          }
        }
      }
    }
  }
}

For more information regarding Type Options, please refer to the Validation Types reference.

Advanced Validation #

If the basic validation functionality doesn't meet your requirements, you can take advantage of Koncorde to create complex validation specifications.

The idea is simple: use Koncorde to specify a filter that can be used to validate documents. For example, here we ensure that at least one of the fields price or vatPrice exists by placing a filter in the validators field of the validation schema:

{
  "validation": {
    "onlineshop": {
      "products": {
        "fields": {
          "price": {
            "type": "numeric",
            "typeOptions": {
              "range": {
                "min": 0
              }
            }
          },
          "vatPrice": {
            "type": "numeric",
            "typeOptions": {
              "range": {
                "min": 0
              }
            }
          },
          "productDescription": {
            "type": "string",
            "defaultValue": "Sorry, no description available for this product."
          }
        },
        "validators": [
          // Here goes the filters
          {
            "or": [
              {
                "exists": {
                  "field": "price"
                }
              },
              {
                "exists": {
                  "field": "vatPrice"
                }
              }
            ]
          }
        ]
      }
    }
  }
}

In the example above, we used both the exists operator and the or operator to build our validation rule. For more information take a look at our Koncorde Reference.

Validation Reference #

Collection properties #

The validation schema of a collection, under validation.<index>.<collection>, accepts these properties:

Field properties #

Validation types #

Plugins can add their own types with DataValidation.addType, available as context.accessors.validation.addType.