@opentext/forms-ajv-keywords

v26.1.1

Published

10 days ago

Provides custom Ajv keywords for OpenText™ Forms API

Downloads

127

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 is not greater than the maximum value specified in another property.

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

The value of this keyword is an object with the properties propertyPath (string: the name of the property containing the maximum value of the number) and default (number: the maximum 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_input: {
      type: 'number',
      otMaximum: {
        propertyPath: 'max_value',
        default: 128
      }
    },
    max_value: {
      type: 'number'
    }
  }
};

const validData = {
  num_input: 3,
  max_value: 4
};

const invalidData1 = {
  num_input: 3,
  max_value: 2
};

const invalidData2 = {
  num_input: 129
};

`otMinimum`

This keyword checks that a number is not less than the minimum value specified in another property.

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

The value of this keyword is an object with the properties propertyPath (string: the name of the property containing the minimum value of the number) and default (number: the minimum 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_input: {
      type: 'number',
      otMinimum: {
        propertyPath: 'min_value',
        default: 128
      }
    },
    min_value: {
      type: 'number'
    }
  }
};

const validData = {
  num_input: 4,
  min_value: 3
};

const invalidData1 = {
  num_input: 2,
  min_value: 3
};

const invalidData2 = {
  num_input: 127
};

Keywords for strings

`otMaxLength`

This keyword checks that a string is not longer than the maximum length specified in another property.

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

The value of this keyword is an object with the properties propertyPath (string: the name of the property containing the maximum length of the string) and default (number: the maximum 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_input: {
      type: 'string',
      otMaxLength: {
        propertyPath: 'max_length',
        default: 128
      }
    },
    max_length: {
      type: 'number'
    }
  }
};

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

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

`otMinLength`

This keyword checks that a string is not shorter than the minimum length specified in another property.

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

The value of this keyword is an object with the properties propertyPath (string: the name of the property containing the minimum length of the string) and default (number: the minimum 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_input: {
      type: 'string',
      otMinLength: {
        propertyPath: 'min_length',
        default: 128
      }
    },
    min_length: {
      type: 'number'
    }
  }
};

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

const invalidData1 = {
  text_input: 'Bad',
  min_length: 5
};

const invalidData2 = {
  text_input: 'Bad'
};

Keywords for arrays

`otMaxItems`

This keyword checks that an array is not longer than the maximum number of items specified in another property.

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

The value of this keyword is an object with the properties propertyPath (string: the name of the property containing the maximum number of items in the array) and default (number: the maximum 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_input: {
      type: 'array',
      items: {
        type: 'string'
      },
      otMaxItems: {
        propertyPath: 'max_items',
        default: 128
      }
    },
    max_items: {
      type: 'number'
    }
  }
};

const validData = {
  array_input: ['One', 'Two', 'Three', 'Four'],
  max_items: 4
};

const invalidData = {
  array_input: ['One', 'Two', 'Three'],
  max_items: 2
};

`otMinItems`

This keyword checks that an array is not shorter than the minimum number of items specified in another property.

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

The value of this keyword is an object with the properties propertyPath (string: the name of the property containing the minimum number of items in the array) and default (number: the minimum 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_input: {
      type: 'array',
      items: {
        type: 'string'
      },
      otMinItems: {
        propertyPath: 'min_items',
        default: 128
      }
    },
    min_items: {
      type: 'number'
    }
  }
};

const validData = {
  array_input: ['One', 'Two', 'Three', 'Four'],
  min_items: 4
};

const invalidData1 = {
  array_input: ['One', 'Two', 'Three'],
  min_length: 5
};

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

`otUniqueItemProperties`

The 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 }
];

Keywords for basic types

`otEnum`

This keyword checks that the data value is present in the value of another property.

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

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

const schema = {
  type: 'object',
  properties: {
    property1: {
      type: 'string',
      otEnum: { propertyPath: 'property2' }
    },
    property2: {
      type: 'array',
      items: { type: 'string' }
    },
    property3: {
      type: 'string',
      otEnum: { propertyPath: 'property4' }
    },
    property4: {
      type: 'string'
    },
    property5: {
      type: 'number',
      otEnum: { propertyPath: 'property6' }
    },
    property6: {
      type: 'array',
      items: { type: 'number' }
    }
  }
};

const validData = {
  property1: 'value1',
  property2: ['value1', 'value2', 'value3'],
  property3: 'value3',
  property4: 'value2, value3, value4',
  property5: 5,
  property6: [3, 4, 5]
};

const invalidData1 = {
  property1: 'value1',
  property2: ['value2', 'value3']
};

const invalidData2 = {
  property3: 'value1',
  property4: 'value2, value3'
};

const invalidData3 = {
  property5: 1,
  property6: [2, 3]
};

`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). If the data is not a basic type, the validation succeeds.

The value of this keyword is an array of objects with the properties propertyPath (string: the name of the property that needs remote data source) and target (object: 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'
      }
    }
  ]
};

`otOptions`

This keyword checks that the data value 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). 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: 'number',
      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,
  position: '2nd'
};

const invalidData1 = {
  selected_items: 3
};

const invalidData2 = {
  position: 'Gold'
};

`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 by an empty string.

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 minimum.

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'
};

`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}'
};

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, then 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 then 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 propertyItem 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 then 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']
};

`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
};

`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), and tooltip (string: the tooltip text for the control).

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, date checks that the data value is a date, datetime checks that the data value is a date and time, fontfamily checks that the data value is a CSS font family, and fontsize checks that the data value is a CSS font size.

const schema = {
  type: 'object',
  properties: {
    property1: {
      type: 'boolean',
      otFormat: {
        presentationType: 'toggle'
      }
    },
    property2: {
      type: 'string',
      otFormat: {
        dataType: 'datetime',
        placeholder: 'Enter a date and time',
        tooltip: 'The date and time that the event occurred'
      }
    }
  }
};

`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'
    }
  }
};

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

forms-ajv-keywords

Contents

Install

Usage

Keywords

Keywords for numbers

otMaximum

otMinimum

Keywords for strings

otMaxLength

otMinLength

Keywords for arrays

otMaxItems

otMinItems

otUniqueItemProperties

Keywords for basic types

otEnum

otExternalReferences

otOptions

otReplaceVariables

otVerifyVariables

Keywords for all types

otCrossChecks

otExpressions

otFormat

otType

`otMaximum`

`otMinimum`

`otMaxLength`

`otMinLength`

`otMaxItems`

`otMinItems`

`otUniqueItemProperties`

`otEnum`

`otExternalReferences`

`otOptions`

`otReplaceVariables`

`otVerifyVariables`

`otCrossChecks`

`otExpressions`

`otFormat`

`otType`