forms-ajv-keywords

Custom Ajv keywords for use in OpenText™ Forms API

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
  • Keywords for all types
    • otCrossChecks
    • otFormat

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({ allowUnionTypes: true, 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'
};

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

otFormat

This keyword provides UI control information for a property. It has no validation checks, so the validation always succeeds.

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

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