@opentext/forms-ajv-keywords

v26.2.2

Published

a month ago

Provides custom Ajv keywords for OpenText™ Forms API

Downloads

116

0High
0Medium
0Low

rpetti_ot

ot_d_serres

ddevarap_ot

OpenText Cloud Platform OCP OpenText Thrust Forms API

forms-ajv-keywords

Custom Ajv keywords for use in OpenText™ Forms API

Install

To install for use with Ajv, run:

npm install @opentext/forms-ajv-keywords

Usage

To add all available keywords:

import { ocpKeywords } from '@opentext/forms-ajv-keywords';

// create new ajv object, for example:
const ajv = new Ajv({ allErrors: true, passContext: true });

// enable OCP custom keywords
ocpKeywords(ajv);

Keywords

Keywords for numbers

`otMaximum`

This keyword checks that a number, or each number in an array, is not greater than a maximum allowed value. The maximum allowed value can either be specified in the keyword or can be the value of another property.

This keyword applies only to numbers, strings, or arrays of numbers or strings. If the data to validate is not a number, or a string that contains a valid number, the validation succeeds.

The value of this keyword is either a number (the maximum allowed value) or an object with the properties propertyPath (string: the name of the property containing the maximum allowed value) and default (number: the maximum allowed value to use if the property value is not a number or a string that contains a valid number).

const schema = {
  type: 'object',
  properties: {
    num_input1: {
      type: 'number',
      otMaximum: 4
    },
    num_input2: {
      type: 'number',
      otMaximum: {
        propertyPath: 'max_value',
        default: 128
      }
    },
    num_array1: {
      type: 'array',
      items: {
        type: 'number'
      },
      otMaximum: 4
    },
    num_array2: {
      type: 'array',
      items: {
        type: 'number'
      },
      otMaximum: {
        propertyPath: 'max_value',
        default: 128
      }
    },
    max_value: {
      type: 'number'
    }
  }
};

const validData = {
  num_input1: 2,
  num_input2: 3,
  num_array1: [1, 2, 3],
  num_array2: [2, 3, 4],
  max_value: 4
};

const invalidData1 = {
  num_input1: 5,
  num_input2: 3,
  num_array1: [4, 5, 6],
  num_array2: [3, 4, 5],
  max_value: 2
};

const invalidData2 = {
  num_input2: 129,
  num_array2: [129, 130, 131]
};

{
  oneOf: [
    {
      type: 'number'
    },
    {
      type: 'object',
      properties: {
        propertyPath: {
          type: 'string'
        },
        default: {
          type: ['number', 'string']
        }
      },
      additionalProperties: false
    }
  ]
}

Notes:

If the data to validate is an array, and otFormat.repeating is true, the keyword should be placed at the property level and not within items.

`otMinimum`

This keyword checks that a number, or each number in an array, is not less than a minimum allowed value. The minimum allowed value can either be specified in the keyword or can be the value of another property.

This keyword applies only to numbers, strings, or arrays of numbers or strings. If the data to validate is not a number, or a string that contains a valid number, the validation succeeds.

The value of this keyword is either a number (the minimum allowed value) or an object with the properties propertyPath (string: the name of the property containing the minimum allowed value) and default (number: the minimum allowed value to use if the property value is not a number or a string that contains a valid number).

const schema = {
  type: 'object',
  properties: {
    num_input1: {
      type: 'number',
      otMinimum: 4
    },
    num_input2: {
      type: 'number',
      otMinimum: {
        propertyPath: 'min_value',
        default: 128
      }
    },
    num_array1: {
      type: 'array',
      items: {
        type: 'number'
      },
      otMinimum: 4
    },
    num_array2: {
      type: 'array',
      items: {
        type: 'number'
      },
      otMinimum: {
        propertyPath: 'min_value',
        default: 128
      }
    },
    min_value: {
      type: 'number'
    }
  }
};

const validData = {
  num_input1: 5,
  num_input2: 4,
  num_array1: [4, 5, 6],
  num_array2: [3, 4, 5],
  min_value: 3
};

const invalidData1 = {
  num_input1: 5,
  num_input2: 2,
  num_array1: [3, 4, 5],
  num_array2: [0, 1, 2],
  min_value: 3
};

const invalidData2 = {
  num_input2: 127,
  num_array2: [125, 126, 127]
};

{
  oneOf: [
    {
      type: 'number'
    },
    {
      type: 'object',
      properties: {
        propertyPath: {
          type: 'string'
        },
        default: {
          type: ['number', 'string']
        }
      },
      additionalProperties: false
    }
  ]
}

Notes:

If the data to validate is an array, and otFormat.repeating is true, the keyword should be placed at the property level and not within items.

Keywords for strings

`otMaxLength`

This keyword checks that a string, or each string in an array, is not longer than a maximum allowed length. The maximum allowed length can either be specified in the keyword or can be the value of another property.

This keyword applies only to strings or arrays of strings. If the data to validate is not a string, the validation succeeds.

The value of this keyword is either a non-negative integer (the maximum allowed length) or an object with the properties propertyPath (string: the name of the property containing the maximum allowed length) and default (integer: the maximum allowed length to use if the property value is not a non-negative integer or a string that contains a valid non-negative integer).

const schema = {
  type: 'object',
  properties: {
    text_input1: {
      type: 'string',
      otMaxLength: 8
    },
    text_input2: {
      type: 'string',
      otMaxLength: {
        propertyPath: 'max_length',
        default: 128
      }
    },
    text_array1: {
      type: 'array',
      items: {
        type: 'string'
      },
      otMaxLength: 8
    },
    text_array2: {
      type: 'array',
      items: {
        type: 'string'
      },
      otMaxLength: {
        propertyPath: 'max_length',
        default: 128
      }
    },
    max_length: {
      type: 'number'
    }
  }
};

const validData = {
  text_input1: 'Average',
  text_input2: 'Good',
  text_array1: ['Average', 'Fair'],
  text_array2: ['Good', 'Best'],
  max_length: 4
};

const invalidData = {
  text_input1: 'Very poor',
  text_input2: 'Bad',
  text_array1: ['Very poor', 'Poor'],
  text_array2: ['Bad', 'Worst'],
  max_length: 2
};

{
  oneOf: [
    {
      type: 'integer',
      minimum: 0
    },
    {
      type: 'object',
      properties: {
        propertyPath: {
          type: 'string'
        },
        default: {
          type: ['integer', 'string']
        }
      },
      additionalProperties: false
    }
  ]
}

Notes:

If the data to validate is an array, and otFormat.repeating is true, the keyword should be placed at the property level and not within items.

`otMinLength`

This keyword checks that a string, or each string in an array, is not shorter than a minimum allowed length. The minimum allowed length can either be specified in the keyword or can be the value of another property.

This keyword applies only to strings or arrays of strings. If the data to validate is not a string, the validation succeeds.

The value of this keyword is either a non-negative integer (the minimum allowed length) or an object with the properties propertyPath (string: the name of the property containing the minimum allowed length) and default (integer: the minimum allowed length to use if the property value is not a non-negative integer or a string that contains a valid non-negative integer).

const schema = {
  type: 'object',
  properties: {
    text_input1: {
      type: 'string',
      otMinLength: 6
    },
    text_input2: {
      type: 'string',
      otMinLength: {
        propertyPath: 'min_length',
        default: 128
      }
    },
    text_array1: {
      type: 'array',
      items: {
        type: 'string'
      },
      otMinLength: 6
    },
    text_array2: {
      type: 'array',
      items: {
        type: 'string'
      },
      otMinLength: {
        propertyPath: 'min_length',
        default: 128
      }
    },
    min_length: {
      type: 'number'
    }
  }
};

const validData = {
  text_input1: 'Average',
  text_input2: 'Good',
  text_array1: ['Average', 'Very average'],
  text_array2: ['Good', 'Better'],
  min_length: 4
};

const invalidData1 = {
  text_input1: 'Worst',
  text_input2: 'Bad',
  text_array1: ['Worst', 'Terrible'],
  text_array2: ['Bad', 'Evil'],
  min_length: 5
};

const invalidData2 = {
  text_input2: 'Bad',
  text_array2: ['Bad', 'Evil']
};

{
  oneOf: [
    {
      type: 'integer',
      minimum: 0
    },
    {
      type: 'object',
      properties: {
        propertyPath: {
          type: 'string'
        },
        default: {
          type: ['integer', 'string']
        }
      },
      additionalProperties: false
    }
  ]
}

Notes:

If the data to validate is an array, and otFormat.repeating is true, the keyword should be placed at the property level and not within items.

Keywords for arrays

`otMaxItems`

This keyword checks that an array is not longer than a maximum allowed number of items. The maximum allowed number of items can either be specified in the keyword or can be the value of another property.

This keyword applies only to arrays. If the data to validate is not an array, the validation succeeds.

The value of this keyword is either a non-negative integer (the maximum allowed number of items) or an object with the properties propertyPath (string: the name of the property containing the maximum allowed number of items) and default (integer: the maximum allowed number of items to use if the property value is not a non-negative integer or a string that contains a valid non-negative integer).

const schema = {
  type: 'object',
  properties: {
    array_input1: {
      type: 'array',
      items: {
        type: 'integer'
      },
      otMaxItems: 3
    },
    array_input2: {
      type: 'array',
      items: {
        type: 'string'
      },
      otMaxItems: {
        propertyPath: 'max_items',
        default: 128
      }
    },
    max_items: {
      type: 'number'
    }
  }
};

const validData = {
  array_input1: [1, 2, 3],
  array_input2: ['One', 'Two', 'Three', 'Four'],
  max_items: 4
};

const invalidData = {
  array_input1: [1, 2, 3, 4],
  array_input2: ['One', 'Two', 'Three'],
  max_items: 2
};

{
  oneOf: [
    {
      type: 'integer',
      minimum: 0
    },
    {
      type: 'object',
      properties: {
        propertyPath: {
          type: 'string'
        },
        default: {
          type: ['integer', 'string']
        }
      },
      additionalProperties: false
    }
  ]
}

`otMinItems`

This keyword checks that an array is not shorter than a minimum allowed number of items. The minimum allowed number of items can either be specified in the keyword or can be the value of another property.

This keyword applies only to arrays. If the data to validate is not an array, the validation succeeds.

The value of this keyword is either a non-negative integer (the minimum allowed number of items) or an object with the properties propertyPath (string: the name of the property containing the minimum allowed number of items) and default (integer: the minimum allowed number of items to use if the property value is not a non-negative integer or a string that contains a valid non-negative integer).

const schema = {
  type: 'object',
  properties: {
    array_input1: {
      type: 'array',
      items: {
        type: 'string'
      },
      otMinItems: 3
    },
    array_input2: {
      type: 'array',
      items: {
        type: 'string'
      },
      otMinItems: {
        propertyPath: 'min_items',
        default: 128
      }
    },
    min_items: {
      type: 'number'
    }
  }
};

const validData = {
  array_input1: [1, 2, 3],
  array_input2: ['One', 'Two', 'Three', 'Four'],
  min_items: 4
};

const invalidData1 = {
  array_input1: [1, 2],
  array_input2: ['One', 'Two', 'Three'],
  min_length: 5
};

const invalidData2 = {
  array_input2: ['One', 'Two', 'Three']
};

{
  oneOf: [
    {
      type: 'integer',
      minimum: 0
    },
    {
      type: 'object',
      properties: {
        propertyPath: {
          type: 'string'
        },
        default: {
          type: ['integer', 'string']
        }
      },
      additionalProperties: false
    }
  ]
}

`otUniqueItemProperties`

This keyword checks that one or more properties in the items of an array are unique.

This keyword applies only to arrays of objects. If the data is not an array of objects, the validation succeeds.

The value of this keyword must be an array of strings - the names of the properties that should have unique values across all items in the array.

const schema = {
  type: 'array',
  items: {
    type: 'object',
    properties: {
      property1: { type: 'boolean' },
      property2: { type: 'string' },
      property3: { type: 'string' },
      property4: { type: 'number' }
    }
  },
  otUniqueItemProperties: ['property2', 'property4']
};

const validData1 = [
  { property4: 1 },
  { property4: 2 },
  { property4: 3 }
];

const validData2 = [
  { property3: '1' },
  { property3: '1' },
  { property3: '1' }
];

const invalidData1 = [
  { property2: 'id1' },
  { property2: 'id1' }, // duplicate "property2"
  { property2: 'id3' }
];

const invalidData2 = [
  { property2: 'id1', property4: 1 },
  { property2: 'id2', property4: 1 }, // duplicate "property4"
  { property2: 'id3', property4: 3 }
];

{
  type: 'array',
  items: {
    type: 'string'
  },
  uniqueItems: true
}

Keywords for basic types

`otEnum`

This keyword checks that a value, or each value in an array, is present in a list of allowed values. The list of allowed values can either be specified in the keyword or can be the value of another property.

This keyword applies only to basic types (usually strings, numbers or integers) or arrays of basic types. If the data to validate is not a basic type, the validation succeeds.

The value of this keyword is either an array (the list of allowed values) or an object with the properties propertyPath (string: the name of the property containing the list of allowed values) and default (array or string: the list of allowed values to use if the property value is empty). If the keyword value is an object, the list of allowed values can consist of either an array of values or a string containing a comma-seperated list of values.

const schema = {
  type: 'object',
  properties: {
    text_input1: {
      type: 'string',
      otEnum: ['value4', 'value5', 'value6']
    },
    text_input2: {
      type: 'string',
      otEnum: { propertyPath: 'allowed_values1' }
    },
    text_input3: {
      type: 'string',
      otEnum: { propertyPath: 'allowed_values2' }
    },
    allowed_values1: {
      type: 'array',
      items: { type: 'string' }
    },
    allowed_values2: {
      type: 'string'
    },
    num_input1: {
      type: 'number',
      otEnum: [4, 5, 6]
    },
    num_input2: {
      type: 'number',
      otEnum: { propertyPath: 'allowed_values3' }
    },
    num_input3: {
      type: 'number',
      otEnum: { propertyPath: 'allowed_values4' }
    },
    allowed_values3: {
      type: 'array',
      items: { type: 'number' }
    },
    allowed_values4: {
      type: 'string'
    },
    text_array: {
      type: 'array',
      items: {
        type: 'string'
      },
      otEnum: ['value4', 'value5', 'value6']
    },
    num_array: {
      type: 'array',
      items: {
        type: 'number'
      },
      otEnum: [4, 5, 6]
    }
  }
};

const validData = {
  text_input1: 'value6',
  text_input2: 'value1',
  text_input3: 'value3',
  allowed_values1: ['value1', 'value2', 'value3'],
  allowed_values2: 'value2, value3, value4',
  num_input1: 6,
  num_input2: 1,
  num_input3: 3,
  allowed_values3: [1, 2, 3],
  allowed_values4: '2, 3, 4',
  text_array: ['value5', 'value4'],
  num_array: [5, 4]
};

const invalidData = {
  text_input1: 'value2',
  text_input2: 'value1',
  text_input3: 'value3',
  allowed_values1: ['value2', 'value3'],
  allowed_values2: 'value2, value4',
  num_input1: 2,
  num_input2: 1,
  num_input3: 3,
  allowed_values3: [2, 3],
  allowed_values4: '2, 4',
  text_array: ['value3', 'value4'],
  num_array: [3, 4]
};

{
  oneOf: [
    {
      type: 'array',
      items: {
        type: ['string', 'integer', 'number', 'boolean']
      },
      uniqueItems: true
    },
    {
      type: 'object',
      properties: {
        propertyPath: {
          type: 'string'
        },
        default: {
          oneOf: [
            {
              type: 'string'
            },
            {
              type: 'array',
              items: {
                type: ['string', 'integer', 'number', 'boolean']
              }
            }
          ]
        }
      },
      additionalProperties: false
    }
  ]
}

Notes:

If the data to validate is an array, and otFormat.repeating is true, the keyword should be placed at the property level and not within items.
If otFormat.presentationType is combobox, the validation always succeeds.
If the current property path matches one of the property paths in otExternalReferences, and this external reference has a dictionary ID, the validation always succeeds.

`otExternalReferences`

This keyword defines the remote data source for the property. The keyword is typically used in conjunction with a drop-down list.

This keyword applies only to basic types (usually strings or numbers). Validation always succeeds.

The value of this keyword is an array of objects with the properties propertyPath (string: the name of the property that needs a remote data source) and target (object: contains the ID of a dictionary, or the key of a data source object which will be supplied by the calling application).

const schema = {
  type: 'object',
  properties: {
    property1: {
      type: 'string',
    }
  },
  otExternalReferences: [
    {
      propertyPath: 'property1',
      target: {
        dataSource: 'property1_dataSource'
      }
    }
  ]
};

{
  type: 'array',
  items: {
    type: 'object',
    properties: {
      propertyPath: {
        type: 'string'
      },
      target: {
        type: 'object',
        properties: {
          dataSource: {
            type: 'string'
          },
          dictionaryId: {
            type: 'string'
          }
        }
      }
    },
    additionalProperties: false
  }
}

`otOptions`

This keyword checks that a value, or each value in an array, is present in an array of allowed values. Each allowed value has an associated textual string that represents the value. The keyword is typically used in conjunction with a drop-down list, where the list contains strings each of which map to an internal representation.

This keyword applies only to basic types (usually strings or numbers) or arrays of basic types. If the data is not a basic type, the validation succeeds.

The value of this keyword is an array of objects with the properties value (basic type: the allowed value) and text (string: the textual string that represents the allowed value).

const schema = {
  type: 'object',
  properties: {
    selected_items: {
      type: 'array',
      items: {
        type: 'integer'
      },
      otMinimum: -2147483648,
      otMaximum: 2147483647,
      otFormat: {
        repeating: true
      },
      otOptions: [
        { value: 0, text: 'None' },
        { value: 1, text: 'Some' },
        { value: 2, text: 'All' }
      ]
    },
    position: {
      type: 'string',
      otOptions: [
        { value: '1st', text: 'Gold' },
        { value: '2nd', text: 'Silver' },
        { value: '3rd', text: 'Bronze' }
      ]
    }
  }
};

const validData = {
  selected_items: [0, 2],
  position: '2nd'
};

const invalidData = {
  selected_items: [3],
  position: 'Gold'
};

{
  type: 'array',
  items: {
    type: 'object',
    required: ['value'],
    properties: {
      value: {
        type: ['string', 'integer', 'number', 'boolean']
      },
      text: {
        type: 'string'
      }
    }
  }
}

Notes:

If the data to validate is an array, and otFormat.repeating is true, the keyword should be placed at the property level and not within items.
If otFormat.presentationType is combobox, the validation always succeeds.
If the current property path matches one of the property paths in otExternalReferences, and this external reference has a dictionary ID, the validation always succeeds.

`otReplaceVariables`

This keyword replaces any known variables found in the data value with values. Each variable in the data value must be denoted using a ${ prefix and a } suffix, and must consist of a scope and name separated by a period.

This keyword applies only to basic types (usually strings or numbers). If the data is not a basic type, the validation succeeds.

Variables are passed in to the validator using the otVariables context property. The value of this property is an object whose properties are the valid variable scopes. The value of each scope property is an object whose properties are the valid variable names for that scope. The value of each variable property is an object with the property dataType (string: the data type of the variable, which can be string, number or boolean).

const variables = {
  env: {
    VAR_STRING: { dataType: 'string' },
    VAR_NUMBER: { dataType: 'number' },
    VAR_BOOLEAN: { dataType: 'boolean' }
  }
};

const ajv = new Ajv({ allErrors: true, passContext: true });
ocpKeywords(ajv);

const validator = ajv.compile(schema);
const success = validator.call({ otVariables: variables }, data);

Each variable in the data value whose data type is string will be replaced either by a best-fit string (if the data value just contains this variable) or by an empty string (if the data value also contains other text or variables). The best-fit string is determined by looking at the other keywords in the property, for example otOptions, otFormat.dataType, default, or otMinLength. If the best-fit string needs to be padded (e.g. to satisfy otMinLength) then pattern will be used to generate the pad string; if pattern does not exist then the pad property will be used instead; and if pad does not exist then 'a' will be used.

Each variable in the data value whose data type is number will be replaced either by a best-fit integer (if the data value just contains this variable) or by the string '0' (if the data value also contains other text or variables). The best-fit integer is determined by looking at the other keywords in the property, for example otOptions, default, or otMinimum.

Each variable in the data value whose data type is boolean will be replaced either by a best-fit Boolean value (if the data value just contains this variable) or by the string 'false' (if the data value also contains other text or variables). The best-fit Boolean value is determined by looking at the other keywords in the property, for example otOptions or default.

It is recommended to use a combination of the otReplaceVariables and otType keywords, so that the type of the data value can be set to either a string (which allows the data value to contain variables) or the actual target type (which should match the data type of the variable in the data value). otType is then used to enforce the target type.

const schema = {
  type: 'object',
  properties: {
    num_input: {
      type: ['string', 'number'],
      otReplaceVariables: {},
      otType: 'number'
    }
  }
};

const validData1 = {
  num_input: '${env.VAR_NUMBER}'
};

const validData2 = {
  num_input: 1.23
};

const invalidData1 = {
  num_input: '${env.VAR_STRING}'
};

const invalidData2 = {
  num_input: '1.23'
};

{
  type: 'object',
  properties: {
    pad: {
      type: 'string'
    }
  },
  additionalProperties: false
}

`otVerifyVariables`

This keyword verifies any variables in the data value. It can be used in conjunction with otReplaceVariables - in this case, it runs last, so will just verify any variables that have not been replaced by values. Each variable in the data value must be denoted using a ${ prefix and a } suffix, and should consist of a scope and name separated by a period.

This keyword applies only to basic types (usually strings or numbers). If the data is not a basic type, the validation succeeds.

const variables = {
  env: {
    VAR_STRING: { dataType: 'string' },
    VAR_NUMBER: { dataType: 'number' },
    VAR_BOOLEAN: { dataType: 'boolean' }
  }
};

const ajv = new Ajv({ allErrors: true, passContext: true });
ocpKeywords(ajv);

const validator = ajv.compile(schema);
const success = validator.call({ otVariables: variables }, data);

Each variable in the data value will be checked to see if it is valid, and whether it exists in the list of variables passed in to the validator.

const schema = {
  type: 'object',
  properties: {
    num_input: {
      type: ['string', 'number'],
      otVerifyVariables: {},
      otType: 'number'
    }
  }
};

const validData1 = {
  num_input: '${env.VAR_NUMBER}'
};

const validData2 = {
  num_input: '${env.VAR_STRING}'
};

const invalidData1 = {
  num_input: '${env.VAR_UNKNOWN}'
};

const invalidData2 = {
  num_input: '${VAR_NUMBER}'
};

{
  type: 'object',
  properties: {},
  additionalProperties: false
}

Keywords for all types

`otCrossChecks`

This keyword checks that the data value, or a property within the data value, is equal to or present in one of the values of another property. If either of the values is an array, every item in the array is checked.

This keyword applies to basic types (usually strings or numbers), objects or arrays.

The value of this keyword is an array of checks to perform. Each check is an object with the properties message (string: a validation message that overrides the default message of "must be equal to one of the allowed values"), from (object: definition of the source value to check) and to (object: definition of the target value to check).

The source definition object has the properties property (string: the name of the property within the data value to check - if the value of this property is an array, each item in the array is checked) and itemProperty (string: the name of the sub-property within the value to check, if the value being checked is either an object or an array of objects). To check a single basic type value, or array of basic type values, do not specify either property. To check a property within an object, where the property contains a single basic type value or array of basic type values, specify just the property property. To check a property in each item of an array of objects, specify just the itemProperty property. And to check a property in each item of an array of objects, where the array is the value of a property within the data object, specify both properties.

The target definition object has the properties property (string: the name of the property within the parent to check - if the value of this property is an array, each item in the array is checked) and itemProperty (string: the name of the sub-property within the value to check, if the value being checked is either an object or an array of objects). See the source definition object for a description of the each property.

const schema = {
  type: 'object',
  properties: {
    property1: {
      type: 'string',
      otCrossChecks: [
        {
          to: { property: 'property2' }
        }
      ]
    },
    property2: {
      type: 'string'
    },
    property3: {
      type: 'string',
      otCrossChecks: [
        {
          to: { property: 'property4', itemProperty: 'property4a' }
        }
      ]
    },
    property4: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          property4a: {
            type: 'string'
          }
        }
      }
    },
    property5: {
      type: 'object',
      properties: {
        property5a: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              property5aa: {
                type: 'string'
              }
            }
          }
        }
      },
      otCrossChecks: [
        {
          from: { property: 'property5a', itemProperty: 'property5aa' },
          to: { property: 'property6' }
        }
      ]
    },
    property6: {
      type: 'array',
      items: {
        type: 'string'
      }
    }
  }
};

const validData = {
  // property1 matches property2
  property1: 'value1',
  property2: 'value1',
  // property3 matches one of the property4a values
  property3: 'value3',
  property4: [
    { property4a: 'value2' },
    { property4a: 'value3' },
    { property4a: 'value4' }
  ],
  // each value in property5aa is contained in the property6 array
  property5: {
    property5a: [
      { property5aa: 'value2' },
      { property5aa: 'value4' },
      { property5aa: 'value6' }
    ]
  },
  property6: ['value1', 'value2', 'value3', 'value4', 'value5', 'value6']
};

{
  type: 'array',
  items: {
    type: 'object',
    properties: {
      message: {
        type: 'string'
      },
      from: {
        type: 'object',
        properties: {
          property: {
            type: 'string'
          },
          itemProperty: {
            type: 'string'
          }
        },
        additionalProperties: false
      },
      to: {
        type: 'object',
        properties: {
          property: {
            type: 'string'
          },
          itemProperty: {
            type: 'string'
          }
        },
        additionalProperties: false
      }
    },
    additionalProperties: false
  }
}

`otEncryption`

This keyword indicates that the data value is encrypted. The keyword does not perform any encryption itself.

This keyword applies only to basic types (usually strings). Validation always succeeds.

The value of this keyword is an object with the property enabled (boolean: true if the data value is encrypted).

const schema = {
  type: 'object',
  properties: {
    text_input: {
      type: 'string',
      otEncryption: {
        enabled: true
      }
    }
  }
};

const validData = {
  text_input: 'unencrypted'
};

{
  type: 'object',
  properties: {
    enabled: {
      type: 'boolean'
    }
  },
  additionalProperties: false
}

`otExpressions`

This keyword checks that the data value satisfies one or more constraints. It can be placed within a schema property (to validate that property value) or within a schema object (to validate the entire object).

This keyword applies to basic types (usually strings or numbers), objects or arrays.

The value of this keyword is an object with the properties constraints (object: the constraints to evaluate), conjunctiveOperator (string: the conjunctive operator to use between each constraint) and message (string: the default error message to generate if a constraint is not satisfied).

Each property in the constraints object defines an expression to execute. The property name must consist of letters, digits, hyphens and underscores. The property value is an object with the properties type (string: the type of expression), conditions (array: the conditions from which the expression was generated, if any), expression (string: the expression to execute) and message (string: the error message to generate for this constraint).

The only type of expression currently supported is "feel", which specifies that the expression is written in FEEL (Friendly Enough Expression Language).

The constraint conditions consist of an array of objects, each with the properties type (string: the type of condition) and value (any: the value associated with the condition).

Constraint error messages are themselves expressions, whereas the default error message is a string. Constraint and default error messages are returned in the customMessage property of the params object. Only one error object is returned with the default error message, even if multiple constraints are not satisifed. The params object also contains the properties label (string: the name of the constraint), expression (string: the expression that failed) and propertyValue (any: the data value being validated).

The conjunctiveOperator may be either AND (validation only succeeds if all the constraints are satisifed) or OR (validation succeeds if any of the constraints are satisfied). The default is AND.

A context will be passed to the expression engine, so that expressions can refer to more than just the data value being validated.

The FEEL context consists of an object with the properties ? (any: the data value being validated), parent (any: the parent of the data value being validated), data (any: the root of the data value being validated, which is usually an object) and metadata (any: the metadata associated with the root of the data value being validated). These properties can be referenced within an expression to gain access to both the data value and other values (e.g. data.maxLength can be used to gain access to the value of a property named maxLength).

const schema = {
  type: 'object',
  properties: {
    text_input: {
      type: 'string',
      otExpressions: {
        constraints: {
          check_max_length: {
            type: 'feel',
            expression: 'string length(?) <= data.max_length',
            message: '"must NOT be longer than " + string(data.max_length) + " character" + (if data.max_length != 1  then "s" else "")'
          }
        }
      }
    },
    max_length: {
      type: 'integer'
    }
  }
};

const validData = {
  text_input: 'Good',
  max_length: 4
};

const invalidData = {
  text_input: 'Bad',
  max_length: 2
};

{
  type: 'object',
  properties: {
    constraints: {
      type: 'object',
      patternProperties: {
        '^[a-zA-Z0-9_][-a-zA-Z0-9_]*$': {
          type: 'object',
          properties: {
            type: {
              enum: ['feel']
            },
            components: {
              type: 'array',
              items: {
                type: 'object',
                properties: {
                  type: {
                    enum: ['function', 'condition', 'constant', 'property', 'system', 'session', 'environment']
                  },
                  value: {
                    type: ['string', 'number', 'boolean', 'array']
                  }
                },
                additionalProperties: false
              }
            },
            expression: {
              type: 'string'
            },
            message: {
              type: 'string'
            }
          },
          additionalProperties: false
        }
      },
      additionalProperties: false
    },
    conjunctiveOperator: {
      enum: ['AND', 'OR'],
      default: 'AND'
    },
    message: {
      type: 'string'
    }
  },
  additionalProperties: false
}

`otFormat`

This keyword provides UI control information for a property. For some data types, it also checks that the data value is in the correct format for the data type.

The value of this keyword is an object with the properties dataType (string: the type of data that the property value contains), presentationType (string: the type of control that the property value should be rendered as), repeating (boolean: true if the control should be rendered as a repeating control), placeholder (string: the placeholder text for the control), tooltip (string: the tooltip text for the control), precision (integer: the maximum precision for numeric, decimal and currency values), scale (integer: the maximum scale for decimal and currency values), currencyCode (string: the currency code for currency values), masked (boolean: indicates that the data value is masked), and maskedPattern (string: the pattern that was used to mask the data value).

The following data types cause the data value to be checked for errors: bigint checks that the data value is a big integer, color checks that the data value is a CSS color, currency checks that the data value is a currency value, date checks that the data value is a date, datetime checks that the data value is a date and time, decimal checks that the data value is a decimal value, fontfamily checks that the data value is a CSS font family, fontsize checks that the data value is a CSS font size, and numeric checks that the data value is a numeric value.

const schema = {
  type: 'object',
  properties: {
    property_toggle: {
      type: 'boolean',
      otFormat: {
        presentationType: 'toggle'
      }
    },
    property_datetime: {
      type: 'string',
      otFormat: {
        dataType: 'datetime',
        placeholder: 'Enter a date and time',
        tooltip: 'The date and time that the event occurred'
      }
    },
    property_masked: {
      type: 'string',
      otEncryption: {
        enabled: true
      },
      otFormat: {
        masked: true,
        maskedPattern: '####-####-####-{4}',
        placeholder: 'Enter a credit card number'
      }
    },
    array_decimal: {
      type: 'array',
      items: {
        type: 'string'
      },
      otFormat: {
        dataType: 'decimal',
        repeating: true,
        precision: 5,
        scale: 3
      }
    }
  }
};

{
  type: 'object',
  properties: {
    dataType: {
      oneOf: [
        {
          type: 'string'
        },
        {
          type: 'array',
          items: {
            type: 'string'
          },
          minItems: 1
        }
      ]
    },
    presentationType: {
      type: 'string'
    },
    repeating: {
      type: 'boolean'
    },
    placeholder: {
      type: 'string'
    },
    tooltip: {
      type: 'string'
    },
    precision: {
      oneOf: [
        {
          type: 'integer',
          minimum: 0
        },
        {
          type: 'object',
          properties: {
            propertyPath: {
              type: 'string'
            },
            default: {
              type: ['integer', 'string']
            }
          },
          additionalProperties: false
        }
      ]
    },
    scale: {
      oneOf: [
        {
          type: 'integer',
          minimum: 0
        },
        {
          type: 'object',
          properties: {
            propertyPath: {
              type: 'string'
            },
            default: {
              type: ['integer', 'string']
            }
          },
          additionalProperties: false
        }
      ]
    },
    currencyCode: {
      type: 'string'
    },
    masked: {
      type: 'boolean'
    },
    maskedPattern: {
      type: 'string'
    }
  }
}

Notes:

If the data to validate is an array, and otFormat.repeating is true, the keyword should be placed at the property level and not within items.

`otType`

This keyword can be used either as a refinement of or as a replacement for the type keyword. It executes after custom keywords which potentially modify the property value (such as otReplaceVariables), whereas type executes before.

The validation for this keyword will only execute if validation for the type keyword succeeds.

The value of this keyword is either a string or an array of strings. Each string must be one of the following: null, boolean, object, array, number, integer or string.

const schema = {
  type: 'object',
  properties: {
    property1: {
      type: 'boolean'
    },
    property2: {
      otType: 'string'
    },
    property3: {
      type: ['string', 'integer'],
      otReplaceVariables: {},
      otType: 'integer'
    }
  }
};

{
  oneOf: [
    {
      enum: ['null', 'boolean', 'object', 'array', 'number', 'integer', 'string']
    },
    {
      type: 'array',
      items: {
        enum: ['null', 'boolean', 'object', 'array', 'number', 'integer', 'string']
      },
      minItems: 1,
      uniqueItems: true
    }
  ]
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

forms-ajv-keywords

Contents

Install

Usage

Keywords

Keywords for numbers

otMaximum

Notes:

otMinimum

Notes:

Keywords for strings

otMaxLength

Notes:

otMinLength

Notes:

Keywords for arrays

otMaxItems

otMinItems

otUniqueItemProperties

Keywords for basic types

otEnum

Notes:

otExternalReferences

otOptions

Notes:

otReplaceVariables

otVerifyVariables

Keywords for all types

otCrossChecks

otEncryption

otExpressions

otFormat

Notes:

otType

`otMaximum`

`otMinimum`

`otMaxLength`

`otMinLength`

`otMaxItems`

`otMinItems`

`otUniqueItemProperties`

`otEnum`

`otExternalReferences`

`otOptions`

`otReplaceVariables`

`otVerifyVariables`

`otCrossChecks`

`otEncryption`

`otExpressions`

`otFormat`

`otType`