Custom Constraints

Adding Custom Constraints

Jedison allows you to extend validation beyond standard JSON Schema rules by adding custom constraints. These are defined in the constraints option when initializing Jedison.

How Custom Constraints Work

Custom constraints are validation functions that:

• Check for specific schema extensions (typically using x- prefixed properties)
• Return an array of validation errors/warnings
• Have access to the current validation context (validator, value, schema, key, path, translator)
• Can be configured as either errors or warnings

Implementation Example

The example shows a custom constraint checking x-my-constraint:

constraints: {
  'x-my-constraint': (context) => {
    const errors = []
    const schemaMyConstraint = context.schema['x-my-constraint']

    if (schemaMyConstraint) {
      const invalid = context.value !== schemaMyConstraint

      if (invalid) {
        errors.push({
          type: 'warning',
          path: context.path,
          constraint: 'x-my-constraint',
          messages: [
            `Value should be equal to "${schemaMyConstraint}".`
          ]
        })
      }
    }

    return errors
  }
}

Key Components

• context object containing:
  • value - The current field value
  • path - JSON path to the field
  • schema - The schema for this field
  • translator - The Translator instance
• Error objects with:
  • type - 'error' or 'warning' severity level
  • path - Location of the validation issue
  • constraint - Name of the constraint
  • messages - User-friendly error messages

Error Handling and Validation States

Jedison provides flexible error handling through the getErrors() method:

• jedison.getErrors() - Returns only error-level validations (default)
• jedison.getErrors(['error', 'warning']) - Returns both errors and warnings

Benefits of Warning-Level Constraints

Using warning-level constraints provides several advantages:

• Soft validation - Users can proceed with warnings while being informed of potential issues
• Progressive validation - Start with warnings that can be upgraded to errors later
• Better UX - Different visual treatment for errors (blocking) vs warnings (advisory)
• Flexible workflows - Allow submission with warnings while maintaining data quality standards

In the live example below, the form displays warnings (yellow) and errors (red) independently. By default, getErrors() only returns errors, while warnings are still shown in the UI. To include warnings in the validation result, pass an array of filters: ['error', 'warning']. Final validation behavior is left to the user's implementation.