Valiktor Documentation

Valiktor uses a type-safe DSL to validate object properties. The primary entry point is org.valiktor.validate, which takes an object and a lambda defining the constraints. If any constraint is violated, a ConstraintViolationException is thrown. This exception contains a set of ConstraintViolation objects, each specifying the property name, the invalid value, and the violated constraint.

To handle validation errors, catch ConstraintViolationException and iterate over its constraintViolations property.

try {
    validate(employee) {
        validate(Employee::id).isPositive()
        validate(Employee::name).isNotEmpty()
    }
} catch (ex: ConstraintViolationException) {
    ex.constraintViolations
        .map { "${it.property}: ${it.constraint.name}" }
        .forEach(::println)
}

Add the valiktor-core dependency to your project using Gradle (Groovy or Kotlin DSL) or Maven. The current version is 0.12.0.

// Gradle (Groovy)
implementation 'org.valiktor:valiktor-core:0.12.0'

// Gradle (Kotlin DSL)
implementation("org.valiktor:valiktor-core:0.12.0")

<!-- Maven -->
<dependency>
  <groupId>org.valiktor</groupId>
  <artifactId>valiktor-core</artifactId>
  <version>0.12.0</version>
</dependency>

If constraints contain parameters that require specific formatting (like dates or money) instead of the default toString(), you can implement the org.valiktor.i18n.Formatter interface.

Option 1: Programmatic Registration Implement Formatter<T> and add it to org.valiktor.i18n.Formatters:

object CustomFormatter : Formatter<Custom> {
    override fun format(value: Custom, messageBundle: MessageBundle) = value.toString()
}
Formatters[Custom::class] = CustomFormatter

Option 2: SPI (Service Provider Interface) Implement org.valiktor.i18n.FormatterSpi and register it in META-INF/services/org.valiktor.i18n.FormatterSpi.

Valiktor supports recursive validation of nested objects. You can nest validate calls within the main validation block to traverse the object graph. The resulting property paths in a ConstraintViolation will reflect the nesting (e.g., company.city.name).

try {
    validate(employee) {
        validate(Employee::company).validate {
            validate(Company::city).validate {
                validate(City::name).isNotEmpty()
            }
        }
    }
} catch (ex: ConstraintViolationException) {
    // property will be 'company.city.name'
}

To validate elements within a collection or array, use the validateForEach function. This allows you to apply constraints to every element in the collection. When a violation occurs, the property path will include the index of the invalid element (e.g., dependents[0].name).

try {
    validate(employee) {
        validate(Employee::dependents).validateForEach {
            validate(Dependent::name).isNotEmpty()
        }
    }
} catch (ex: ConstraintViolationException) {
    // property will be 'dependents[0].name'
}

The valiktor-spring module provides automatic exception handling for Spring WebMvc and WebFlux. When a ConstraintViolationException is thrown, the handlers return an HTTP 422 Unprocessable Entity status with a JSON payload describing the errors.

Payload Format:

{
  "errors": [
    {
      "property": "string",
      "value": "any",
      "message": "string",
      "constraint": {
        "name": "string",
        "params": [{ "name": "string", "value": "any" }]
      }
    }
  ]
}

Spring Boot Configuration: Use the valiktor-spring-boot-starter for auto-configuration. You can configure the message bundle name via:

• YAML: valiktor.base-bundle-name: messages
• Properties: valiktor.baseBundleName=messages

The Valiktor test module provides a fluent DSL for asserting validation failures in unit tests.

• shouldFailValidation<T> { ... }: Asserts that the block throws a ConstraintViolationException.
• .verify { ... }: Allows inspecting specific violations.
• expect(property, value, constraint): Checks if a specific property failed with a specific value and constraint.
• expectAll(collection) { ... }: Validates all elements in a collection.
• expectElement { ... }: Validates a specific element within a collection loop.

shouldFailValidation<Employee> {
    // code that triggers validation
}.verify {
    expect(Employee::name, " ", NotBlank)
    expectAll(Employee::dependents) {
        expectElement {
            expect(Dependent::name, " ", NotBlank)
        }
    }
}

When using Spring WebMvc, ValiktorWebMvcAutoConfiguration automatically configures specialized exception handlers to translate Valiktor validation errors into appropriate HTTP responses.

This auto-configuration triggers if:

1. org.springframework.web.servlet.DispatcherServlet is present on the classpath.
2. A ValiktorExceptionHandler bean is already defined.

It provides the following handlers automatically (unless you define your own beans):

• ConstraintViolationExceptionHandler: Handles standard Valiktor constraint violations.
• InvalidFormatExceptionHandler: Handles Jackson InvalidFormatException (requires Jackson on classpath).
• MissingKotlinParameterExceptionHandler: Handles Kotlin-specific missing parameter exceptions (requires jackson-module-kotlin on classpath).