Enhanced Validation Errors

OpenRegister provides clear, actionable validation error messages that help users quickly identify and fix issues when creating or updating objects.

Overview

When objects fail validation against their schema, OpenRegister returns detailed error messages that specify exactly what needs to be fixed, rather than generic error codes or unclear messages.

Key Benefits

• Clear Messages: Users know exactly which properties have issues
• Actionable Feedback: Error messages explain what needs to be fixed
• Faster Development: Developers can quickly identify validation problems
• Better API Integration: Clear error responses help with API integration
• Reduced Support: Fewer questions about unclear error messages

Problem

Previously, when validation failed, users would receive generic error messages like:

• The required properties ({missing}) are missing
• 'Invalid object'
• Generic type mismatch errors

These messages didn't tell users exactly which properties were missing or what the specific validation issues were.

Error Flow Comparison

Solution

A streamlined approach that enhances validation error messages directly within the existing ValidateObject service, requiring no additional dependencies or complex configuration.

Implementation

Simplified Validation Flow

The enhanced validation system works through a streamlined approach without additional dependencies:

Built-in Error Formatting

The ValidateObject class now includes built-in error formatting methods that provide detailed error messages for various validation scenarios:

• Required Properties: 'The required property email is missing'
• Type Mismatches: 'Property age should be of type integer but is string'
• Format Validation: 'Property email should match the format email but the value invalid-email does not'
• Length Constraints: 'Property name should have at least 3 characters, but has 1'
• Value Ranges: 'Property age should be at least 18, but is 16'
• Enum Values: 'Property status should be one of: active, inactive, pending, but is deleted'

Integration

The enhanced error formatting is automatically used throughout the validation system through a simple, streamlined approach:

1. ValidateObject Handler: Contains built-in error formatting logic in the generateErrorMessage() method
2. ObjectService: Updated to use meaningful error messages instead of generic Opis messages
3. Error Response: Provides both summary and detailed error information
4. No Additional Dependencies: No need for separate classes or dependency injection

Key Improvement: Built-in generateErrorMessage()

The solution was simplified by implementing the error formatting logic directly in the ValidateObject class. This method:

1. Intercepts Generic Messages: Catches the generic Opis error messages before they reach the user
2. Built-in Formatting: Processes validation errors through built-in formatting logic
3. Returns Clear Messages: Provides specific, actionable error messages
4. Maintains Context: Preserves all technical details for debugging while presenting user-friendly messages
5. Zero Dependencies: No additional classes or configuration needed

Before (in ObjectService.php):

if ($result->isValid() === false) {
    throw new ValidationException($result->error()->message(), errors: $result->error());
    // Generic message: 'The required properties ({missing}) are missing'
}

After (in ObjectService.php):

if ($result->isValid() === false) {
    $meaningfulMessage = $this->validateHandler->generateErrorMessage($result);
    throw new ValidationException($meaningfulMessage, errors: $result->error());
    // Clear message: 'The required property title is missing'
}

Error Response Structure

{
  'status': 'error',
  'message': 'Validation failed',
  'errors': [
    {
      'property': 'email',
      'keyword': 'required',
      'message': 'The required property 'email' is missing',
      'value': null,
      'path': ['email'],
      'schemaPath': ['required']
    }
  ]
}

Real-World API Response Examples

Missing Required Properties:

{
  'status': 'error',
  'message': 'Validation failed',
  'errors': [
    {
      'property': null,
      'message': 'The required property 'title' is missing'
    }
  ]
}

Type Mismatch:

{
  'status': 'error', 
  'message': 'Validation failed',
  'errors': [
    {
      'property': 'age',
      'message': 'Property 'age' should be of type 'integer' but is 'string''
    }
  ]
}

Multiple Validation Errors:

{
  'status': 'error',
  'message': 'Validation failed', 
  'errors': [
    {
      'property': null,
      'message': 'The required properties (name, email, address) are missing'
    }
  ]
}

Benefits

1. Improved User Experience: Users get clear, actionable error messages
2. Faster Development: Developers can quickly identify validation issues
3. Better API Documentation: Clear error responses help with API integration
4. Reduced Support: Fewer questions about unclear error messages
5. Simple Implementation: No additional dependencies or complex setup
6. Maintainable: All logic contained within existing service structure

Technical Implementation

Compatibility with Opis JsonSchema 2.3.0

The enhanced error formatter was specifically updated to work with Opis JsonSchema version 2.3.0, which has different method signatures compared to newer versions:

Key API Changes Handled:

• Data Path Access: Uses $error->data()->fullPath() instead of $error->dataPointer()
• Value Access: Uses $error->data()->value() instead of direct $error->data()
• Error Arguments: Properly accesses validation parameters through $error->args()
• Schema Information: Simplified schema path generation to work with available API methods

Method Mappings:

// Old (incompatible) approach:
$dataPointer = $error->dataPointer();    // Method doesn't exist in 2.3.0
$schemaPointer = $error->schemaPointer(); // Method doesn't exist in 2.3.0

// New (compatible) approach:
$dataPath = $error->data()->fullPath();   // Works with 2.3.0
$value = $error->data()->value();         // Works with 2.3.0
$args = $error->args();                   // Works with 2.3.0

Files Changed

Modified Files

• lib/Service/ObjectHandlers/ValidateObject.php - Added built-in enhanced error formatting methods
• lib/Service/ObjectService.php - Updated to use meaningful error messages

Approach Benefits

• Simple: No new classes or dependencies required
• Maintainable: All error formatting logic in one place
• Efficient: Direct implementation without additional overhead
• Reliable: Uses existing infrastructure without new injection points

This streamlined approach provides all the benefits of enhanced validation error messages while maintaining simplicity and avoiding additional complexity in the codebase.