Object

Path: /src/type/object.coffee compiled to /lib/type/object.js

For all complex data structures you use the object type which checks for named arrays or instance objects.

This is the most complex validation form because it has different checks and uses subchecks on each entry.

Sanitize options:

  • flatten - flatten hierarchical values

Check options:

  • instanceOf - Class only objects of given class type are allowed
  • flatten - Boolean flatten deep structures
  • mandatoryKeys - Array|Boolean the list of elements which are mandatory
  • allowedKeys - Array|Boolean gives a list of elements which are also allowed or true to use the list from entries definition

Validating children:

  • entries - Object specification for entries
  • keys - Object specification for all entries per each key name

So you have two different ways to specify objects. First you can use the instanceOf check. Or specify a data object.

The mandatoryKeys and allowedKeys may both contain normal strings for complete key names and also regular expressions to match multiple. In case of using it in the mandatoryKeys field at least one matching key have to be present. And as you may suspect the mandatoryKeys are automatically also allowedKeys. If mandatoryKeys or allowedKeys are set to true instead of a list all of the specified keys in entries or keys are meant.

The keys specify the subcheck for each containing object attribute. If they are not optional or contain a default entry they will be seen also as mandatory field.

The entries list do the same as the keys section but works using key matching on multiple entires. If an object attribute matches multiple entries-rules the first will be used.

Examples:

The follwoing will check for an instance:

CoffeeScript Code
validator.check
  name: 'test'        # name to be displayed in errors (optional)
  value: input        # value to check
  schema:             # definition of checks
    type: 'object'
    instanceOf: RegeExp
, (err, result) ->
  # do something

Or you may specify the data object structure:

CoffeeScript Code
validator.check
  name: 'test'        # name to be displayed in errors (optional)
  value: input        # value to check
  schema:             # definition of checks
    type: 'object'
    mandatoryKeys: ['name']
    allowedKeys: ['mail', 'phone']
    entries: [
      type: 'string'
    ]
, (err, result) ->
  # do something

Here all object values have to be strings.

CoffeeScript Code
validator.check
  name: 'test'        # name to be displayed in errors (optional)
  value: input        # value to check
  schema:             # definition of checks
    type: 'object'
    mandatoryKeys: ['name']
    entries: [
      key: /^num-\d+/
      type: 'integer'
    ,
      type: 'string'
    ]
, (err, result) ->
  # do something

And here the keys matching the key-check (starting with ‘num-…’) have to be integers and all other strings.

If you don’t specify allowedKeys more attributes with other names are possible.

And the most complex situation is a deep checking structure with checking each key for its specifics:

CoffeeScript Code
validator.check
  name: 'test'        # name to be displayed in errors (optional)
  value: input        # value to check
  schema:             # definition of checks
    type: 'object'
    allowedKeys: true
    keys:
      name:
        type: 'string'
      mail:
        type: 'string'
        optional: true
      phone:
        type: 'string'
        optional: true
, (err, result) ->
  # do something

Here allowedKeys will check that no attributes are used which are not specified in the entries. Which attribute is optional may be specified within the attributes specification. That means this check is the same as above but also checks that the three attributes are strings.

If you specify entries and keys, the entries check will only be used as default for all keys which has no own specification.

Another option is to flatten the structure before checking it:

CoffeeScript Code
# value to check
input =
  first:
    num: { one: 1, two: 2 }
  second:
    num: { one: 1, two: 2 }
    name: { anna: 1, berta: 2 }
# run the validation
validator.check
  name: 'test'        # name to be displayed in errors (optional)
  value: input        # value to check
  schema:             # definition of checks
    type: 'object'
    flatten: true
, (err, result) ->
  # do something

This will give you the following result:

CoffeeScript Code
result =
  'first-num': { one: 1, two: 2 }
  'second-num': { one: 1, two: 2 }
  'second-name': { anna: 1, berta: 2 }

Optional Elements

You have two possibilities to make elements optional:

First you can specify the mandatory names and all other are optional:

CoffeeScript Code
validator.check
  name: 'test'        # name to be displayed in errors (optional)
  value: input        # value to check
  schema:             # definition of checks
    type: 'object'
    mandatoryKeys: ['name']
    keys:
      name:
        type: 'string'
      age:
        type: `integer`
, (err, result) ->
  # do something

Or you can set the generall rule to all are mandatory and define in each one if it is optional:

CoffeeScript Code
validator.check
  name: 'test'        # name to be displayed in errors (optional)
  value: input        # value to check
  schema:             # definition of checks
    type: 'object'
    mandatoryKeys: true
    keys:
      name:
        type: 'string'
      age:
        type: `integer`
        optional: true
, (err, result) ->
  # do something

Schema Specification

Object is the object schema definitions.

An object with the following keys allowed: flatten, instanceOf, mandatoryKeys, allowedKeys, entries, keys, title, description, key, type, optional, default. The following entries have a specific format:

flatten

Flatten is a flag to flatten the object structure.

A boolean value, which will be true for ‘true’, ‘1’, ‘on’, ‘yes’, ‘+’, 1, true and will be considered as false for ‘false’, ‘0’, ‘off’, ‘no’, ‘-’, 0, false. It’s optional.

instanceOf

Class Check is the class, the object to be instantiated from.

The value has to be a function/class which is optional.

mandatoryKeys

Mandatory Keys are the definition of mandatory keys.

It has to be one of the following types (optional):

  • All Mandatory is a flag if set to true marks all schema defined keys mandatory.

    A boolean value, which will be true for ‘true’, ‘1’, ‘on’, ‘yes’, ‘+’, 1, true and will be considered as false for ‘false’, ‘0’, ‘off’, ‘no’, ‘-’, 0, false.

  • Mandatory List is the list of mandatory keys.

    A list. Each entry has to be of type or:

    Mandatory Key is the key which to be present.

    It has to be one of the following types:

    • Key Name is the name of the mandatory key.

      A text entry in which all control characters will be removed.

    • Key Map is a RegExp to detect mandatory keys to which at least one should match.

      A valid regular expression. It has to be one of the following types:

      • An object which has to be an instance of class RegExp.
      • A text entry in which all control characters will be removed. The text should match: /^/.?/[gim]$/.
allowedKeys

Allowed Keys are the definition of allowed keys.

It has to be one of the following types (optional):

  • No more Allowed is a flag if set to true marks only the schema defined keys as allowed.

    A boolean value, which will be true for ‘true’, ‘1’, ‘on’, ‘yes’, ‘+’, 1, true and will be considered as false for ‘false’, ‘0’, ‘off’, ‘no’, ‘-’, 0, false.

  • Allowed List is the list of allowed keys.

    A list. Each entry has to be of type or:

    Allowed Key is the key which may be present.

    It has to be one of the following types:

    • Key Name is the name of the allowed key.

      A text entry in which all control characters will be removed.

    • Key Map is a RegExp to detect allowed keys to which should match.

      A valid regular expression. It has to be one of the following types:

      • An object which has to be an instance of class RegExp.
      • A text entry in which all control characters will be removed. The text should match: /^/.?/[gim]$/.
entries

Entries are an alternative definition of key’s types without the name.

A list which is optional.

keys

Keys are the definition of each key’s types.

An object which is optional.

title

Title is the title used to describe the element.

A text entry which is optional. All control characters will be removed.

description

Description is the free description of the element.

A text entry which is optional. All control characters will be removed.

key

Binding to Keyname is the mapping to which key names in an object this element belongs.

A valid regular expression which is optional. It has to be one of the following types:

  • An object which has to be an instance of class RegExp.
  • A text entry in which all control characters will be removed. The text should match: /^/.?/[gim]$/.
type

Type is the type of element.

A text entry in which all control characters will be removed.

optional

Optional is a flag defining if this element is optional.

A boolean value, which will be true for ‘true’, ‘1’, ‘on’, ‘yes’, ‘+’, 1, true and will be considered as false for ‘false’, ‘0’, ‘off’, ‘no’, ‘-’, 0, false. It’s optional.

default

Default Value is the default value to use if nothing given.

An object which is optional.