NAV

Introduction

Kuzzle natively provides a way to validate the documents you want to create, replace, update or publish against a validation schema. You can specify the validation rules in the kuzzle configuration file in validation.

Schema Structure

The validation schema must follow the following structure to be valid:

{
  "myIndex": {
    "myCollection": {
      "strict": true,
      "fields": {
        "fieldName": {
            "mandatory": true,
          "type": "string",
          "defaultValue": "a default value",
          "multivalued": {
            "value": true,
            "minCount": 1,
            "maxCount": 5
          },
          "typeOptions": {
            "length": {
              "min": 2,
              "max": 12
            }
          }
        },
        "anotherFieldName": {
          "..."
        },
        "myObjectField": {
          "type": "object",
          "..."
        },
        "myObjectField/mySubField": {
          "..."
        }
      },
      "validators": [
          "..."
      ]
    },
    "..."
  },
  "..."
}

Please refer below for a detailed overview of the available validations.

Fields specification

strict

Possible values: Boolean true or false

Default: false

Purpose: If true, the document will be rejected if it attemps to define new fields that have not been defined in the schema.

Fields

The property name defines the path of the field in the document. The root fields will use their name directly. Sub fields contained in objects will use their path with the pattern “objectField/[/ …]”.

type

Possible values (Elasticsearch types):

  • string: value(s) must be a string, additional optional constraints in typeOptions
  • ip_address: value(s) must be a valid IP address(v4 or v6)
  • integer: value(s) must be a valid integer, additional optional constraints in typeOptions
  • numeric: value(s) must be a valid number, additional optional constraints in typeOptions
  • geo_point: value(s) must be a valid geo-point
  • geo_shape: value(s) must be a valid geo-shape
  • date: value(s) must be a valid date, additional optional constraints in typeOptions
  • object: value(s) must be a valid object, additional optional constraints in typeOptions

Possible values (Special types):

  • email: value(s) must be a valid email address, additional optional constraints in typeOptions
  • url: value(s) must be a valid url
  • enum: (string) value(s) must be contained in the valid values, additional mandatory configuration in typeOptions
  • anything: value(s) can be of any type (useful to specify a mandatory or multi-valued field without any other constraints, or when you use the strict option)

Default: no default (mandatory)

Purpose: Defines the type of the provided fields. Checks are performed depending on the provided type.

Documentation: You can find more information about Elasticsearch types in the Elasticearch documentation

mandatory

Possible values: Boolean true or false

Default: false

Purpose: Specifies whether the field must be present and different from the NULL value.

defaultValue

Possible values: Any value that fits the type of the field. If the field is multi-valued, the default value MUST be an array of values (even if it contains only one value).

Purpose: Provides a value if the field is not present or equals NULL.

Behavior : Applies the default value to the given field when it is not specified or its value is null.

description

Possible values: Any string describing the field, its content and its conditions.

Default: empty (optional)

Purpose: Allows the author of the validation specification to remember what is the field’s purpose (can also contain keywords to search the field in a configuration file).

multivalued

value

Possible values: Boolean true or false

Default: false

Purpose: Specifies whether the field must contain an array of values or not. If true, fields[field].multivalued.minCount and fields[field].multivalued.maxCount can be used. If true, a scalar can not be provided for the field.

minCount

Possible values: A positive integer, less or equal to multivalued.maxCount

Default: 0

Purpose: Defines the minimum (inclusive) count of items provided in the multi-valued field.

maxCount

Possible values: A positive integer, greater or equal to multivalued.minCount

Default: infinite

Purpose: Defines the maximum (inclusive) count of items provided in the multi-valued field.

typeOptions

This configuration is available depending on the types of the field.

range

Associated types: integer, float, date

Possible values: An object with a min and/or a max property, e.g.:

// Integer or float
"typeOptions": {
  "range": {
    "min": 10,
    "max": 20
  }
}

// Date
"typeOptions": {
  "range": {
    "min": "2010-01-01",
    "max": "NOW"
  }
}

Default Behavior: no min and no max

Purpose: Defines a minimum and/or a maximum (inclusive) values for the field.

Specific to dates: Use a date with the format ISO_8601 as min and max value : “YYYY-MM-DDTHH:mm:ss.SSSZ”. The special keyword “NOW” is also available and represents a current time in UTC format.

Examples:

  • Full format: “2010-12-25T14:12:44.123+01:00”
  • Date & Time (without millis) : "2010-12-25T14:12:44"
  • Only date: “2010-12-25”
  • Time relative to the current day : “T14:12:44”

length

Associated type: string

Possible values: An object with a min and/or a max property, ie:

"typeopts": {
  "length": {
    "min": 10,
    "max": 20
  }
}

Default Behavior: no min and no max

Purpose: Defines a minimum and/or a maximum (inclusive) values for the field.

notEmpty

Associated type: email, ip_address, url

Possible values: Boolean true or false

Default: false

Purpose: Specifies whether a field can contain empty strings or not. If set to false, the field must either be empty or fulfill the field requirement (follow an email format by example).

formats

Associated type: date

Possible values: An array of strings representing the date format. The document date will have to match one of the provided formats in order to be valid.

epoch_millis
epoch_second
strict_date_optional_time
basic_date
basic_date_time
basic_date_time_no_millis
basic_ordinal_date
basic_ordinal_date_time
basic_ordinal_date_time_no_millis
basic_time
basic_time_no_millis
basic_t_time
basic_t_time_no_millis
basic_week_date
strict_basic_week_date
basic_week_date_time
strict_basic_week_date_time
basic_week_date_time_no_millis
strict_basic_week_date_time_no_millis
date
strict_date
date_hour
strict_date_hour
date_hour_minute
strict_date_hour_minute
date_hour_minute_second
strict_date_hour_minute_second
date_hour_minute_second_fraction
strict_date_hour_minute_second_fraction
date_hour_minute_second_millis
strict_date_hour_minute_second_millis
date_time
strict_date_time
date_time_no_millis
strict_date_time_no_millis
hour
strict_hour
hour_minute
strict_hour_minute
hour_minute_second
strict_hour_minute_second
hour_minute_second_fraction
strict_hour_minute_second_fraction
hour_minute_second_millis
strict_hour_minute_second_millis
ordinal_date
strict_ordinal_date
ordinal_date_time
strict_ordinal_date_time
ordinal_date_time_no_millis
strict_ordinal_date_time_no_millis
time
strict_time
time_no_millis
strict_time_no_millis
t_time
strict_t_time
t_time_no_millis
strict_t_time_no_millis
week_date
strict_week_date
week_date_time
strict_week_date_time
week_date_time_no_millis
strict_week_date_time_no_millis
weekyear
strict_weekyear
weekyear_week
strict_weekyear_week
weekyear_week_day
strict_weekyear_week_day
year
strict_year
year_month
strict_year_month
year_month_day
strict_year_month_day

DocumentationElasticsearch documentation (all except date_optional_time)

Default: [“epoch_millis”]

Purpose: Define the accepted formats that can be used for dates

strict

Associated type: object

Possible values: Boolean true or false

Default Behavior: If not set, uses the same value as its parent, recursively.

Purpose: Specifies whether the field can contain non declared fields. If true, a document that attempts to add a not declared field will be rejected.

values

Associated type: enum (mandatory)

Values: an array of strings defining the valid values 

Purpose:Defines all valid values for an enum field. All field values have to match one of the valid values for a multi-valued field.

shapeTypes

Associated type: geo_shape (mandatory)

Possible value: an array of shapes type within

  • point
  • linestring
  • polygon
  • multipoint
  • multilinestring
  • multipolygon
  • geometrycollection
  • envelope
  • circle

Default: an array of all types

Purpose: Limit the shapes available for a given geo_shape field.

DocumentationElasticsearch documentation

Validators

The validators property is an array of DSL filters. Each filters have to match in order for the document to be valid.

Structure

{
  "myIndex": {
    "myCollection": {
      "strict": true,
      "fields": {
        "..."
      },
      "validators": [
        { "equals": { "fieldName": "maximilian"} },
        {
          "bool": {
            "must": [
              "..."
            ],
            "must_not": [
              "..."
            ],
            "should": [
              "..."
            ],
            "should_not": [
              "..."
            ]
          }
        },
        "..."
      ]
    },
    "..."
  },
  "..."
}

Translates in the following DSL query:

{
  "bool": {
    "must": [
      { "equals": { "fieldName": "maximilian"} },
      {
        "bool": {
          "must": [
            "..."
          ],
          "must_not": [
            "..."
          ],
          "should": [
            "..."
          ],
          "should_not": [
            "..."
          ]
        }
      },
      "..."
    ]
  }
}