Valiktor is a type-safe, powerful and extensible fluent DSL to validate objects in Kotlin.
implementation 'org.valiktor:valiktor-core:0.12.0'
implementation("org.valiktor:valiktor-core:0.12.0")
<dependency>
<groupId>org.valiktor</groupId>
<artifactId>valiktor-core</artifactId>
<version>0.12.0</version>
</dependency>
- For install other modules, see Modules.
data class Employee(val id: Int, val name: String, val email: String) {
init {
validate(this) {
validate(Employee::id).isPositive()
validate(Employee::name).hasSize(min = 3, max = 80)
validate(Employee::email).isNotBlank().isEmail()
}
}
}
The main function org.valiktor.validate
expects an object and an anonymous function that will validate it. Within this, it's possible to validate the object properties by calling org.valiktor.validate
with the respective property as parameter. Thanks to Kotlin's powerful reflection, it's type safe and very easy, e.g.: Employee::name
. There are many validation constraints (org.valiktor.constraints.*
) and extension functions (org.valiktor.functions.*
) for each data type. For example, to validate that the employee's name cannot be empty: validate(Employee::name).isNotEmpty()
.
All the validate
functions are evaluated and if any constraint is violated, a ConstraintViolationException
will be thrown with a set of ConstraintViolation
containing the property, the invalid value and the violated constraint.
For example, consider this data class:
data class Employee(val id: Int, val name: String)
And this invalid object:
val employee = Employee(id = 0, name = "")
Now, let's validate its id
and name
properties and handle the exception that will be thrown by printing the property name and the violated constraint:
try {
validate(employee) {
validate(Employee::id).isPositive()
validate(Employee::name).isNotEmpty()
}
} catch (ex: ConstraintViolationException) {
ex.constraintViolations
.map { "${it.property}: ${it.constraint.name}" }
.forEach(::println)
}
This code will return:
id: Greater
name: NotEmpty
See the sample
Valiktor can also validate nested objects and properties recursively.
For example, consider these data classes:
data class Employee(val company: Company)
data class Company(val city: City)
data class City(val name: String)
And this invalid object:
val employee = Employee(company = Company(city = City(name = "")))
Now, let's validate the property name
of City
object and handle the exception that will be thrown by printing the property name and the violated constraint:
try {
validate(employee) {
validate(Employee::company).validate {
validate(Company::city).validate {
validate(City::name).isNotEmpty()
}
}
}
} catch (ex: ConstraintViolationException) {
ex.constraintViolations
.map { "${it.property}: ${it.constraint.name}" }
.forEach(::println)
}
This code will return:
company.city.name: NotEmpty
See the sample
Array and collection properties can also be validated, including its elements.
For example, consider these data classes:
data class Employee(val dependents: List<Dependent>)
data class Dependent(val name: String)
And this invalid object:
val employee = Employee(
dependents = listOf(
Dependent(name = ""),
Dependent(name = ""),
Dependent(name = "")
)
)
Now, let's validate the property name
of all Dependent
objects and handle the exception that will be thrown by printing the property name and the violated constraint:
try {
validate(employee) {
validate(Employee::dependents).validateForEach {
validate(Dependent::name).isNotEmpty()
}
}
} catch (ex: ConstraintViolationException) {
ex.constraintViolations
.map { "${it.property}: ${it.constraint.name}" }
.forEach(::println)
}
This code will return:
dependents[0].name: NotEmpty
dependents[1].name: NotEmpty
dependents[2].name: NotEmpty
See the sample
Valiktor provides a decoupled internationalization, that allows to maintain the validation logic in the core of the application and the internationalization in another layer, such as presentation or RESTful adapter. This guarantees some design principles proposed by Domain-Driven Design or Clean Architecture, for example.
The internationalization works by converting a collection of ConstraintViolation
into a collection of ConstraintViolationMessage
through the extension function org.valiktor.i18n.mapToMessage
by passing the following parameters:
baseName
: specifies the prefix name of the message properties, the default value isorg/valiktor/messages
.locale
: specifies thejava.util.Locale
of the message properties, the default value is the default locale of the application.
For example:
try {
validate(employee) {
validate(Employee::id).isPositive()
validate(Employee::name).isNotEmpty()
}
} catch (ex: ConstraintViolationException) {
ex.constraintViolations
.mapToMessage(baseName = "messages", locale = Locale.ENGLISH)
.map { "${it.property}: ${it.message}" }
.forEach(::println)
}
This code will return:
id: Must be greater than 1
name: Must not be empty
Currently the following locales are natively supported by Valiktor:
ca
(Catalan)de
(German)en
(English)es
(Spanish)ja
(Japanese)pt_BR
(Portuguese/Brazil)
Any constraint message of any language can be overwritten simply by adding the message key into your message bundle file. Generally the constraint key is the qualified class name plus message
suffix, e.g.: org.valiktor.constraints.NotEmpty.message
.
Some constraints have parameters of many types and these parameters need to be interpolated with the message. The default behavior of Valiktor is to call the object toString()
function, but some data types require specific formatting, such as date/time and monetary values. So for these cases, there are custom formatters (org.valiktor.i18n.formatters.*
).
For example:
try {
validate(employee) {
validate(Employee::dateOfBirth).isGreaterThan(LocalDate.of(1950, 12, 31))
}
} catch (ex: ConstraintViolationException) {
ex.constraintViolations
.mapToMessage(baseName = "messages")
.map { "${it.property}: ${it.message}" }
.forEach(::println)
}
With en
as the default locale, this code will return:
dateOfBirth: Must be greater than Dec 31, 1950
With pt_BR
as the default locale, this code will return:
dateOfBirth: Deve ser maior que 31/12/1950
Currently the following types have a custom formatter supported by Valiktor:
Creating a custom formatter is very simple, just implement the interface org.valiktor.i18n.Formatter
, like this:
object CustomFormatter : Formatter<Custom> {
override fun format(value: Custom, messageBundle: MessageBundle) = value.toString()
}
Then add it to the list of formatters (org.valiktor.i18n.Formatters
):
Formatters[Custom::class] = CustomFormatter
It's also possible to use the SPI (Service Provider Interface) provided by Valiktor using the java.util.ServiceLoader
to discover the formatters automatically without adding them to the list programmatically. For this approach, it's necessary to implement the interface org.valiktor.i18n.FormatterSpi
, like this:
class CustomFormatterSpi : FormatterSpi {
override val formatters = setOf(
Custom::class to CustomFormatter
)
}
Then create a file org.valiktor.i18n.FormatterSpi
within the directory META-INF.services
with the content:
com.company.CustomFormatterSpi
See the sample
Valiktor provides a lot of constraints and validation functions for the most common types, but in some cases this is not enough to meet all needs.
It's possible to create custom validations in three steps:
To create a custom constraint, it's necessary to implement the interface org.valiktor.Constraint
, which has these properties:
name
: specifies the name of the constraint, the default value is the class name, e.g.:Between
.messageBundle
: specifies the base name of the default message property file, the default value isorg/valiktor/messages
.messageKey
: specifies the name of the key in the message property file, the default value is the qualified class name plusmessage
suffix, e.g.:org.valiktor.constraints.Between.message
.messageParams
: specifies aMap<String, *>
containing the parameters to be replaced in the message, the default values are all class properties, obtained through reflection.
For example:
data class Between<T>(val start: T, val end: T) : Constraint
The validation logic must be within an extension function of org.valiktor.Validator<E>.Property<T>
, where E
represents the object and T
represents the property to be validated.
There is an auxiliary function named validate
that expects a Constraint
and a validation function as parameters.
For example:
fun <E> Validator<E>.Property<Int?>.isBetween(start: Int, end: Int) =
this.validate(Between(start, end)) { it == null || it in start.rangeTo(end) }
To support suspending functions, you must use coValidate
instead of validate
:
suspend fun <E> Validator<E>.Property<Int?>.isBetween(start: Int, end: Int) =
this.coValidate(Between(start, end)) { it == null || it in start.rangeTo(end) }
And to use it:
validate(employee) {
validate(Employee::age).isBetween(start = 1, end = 99)
}
Note: null properties are valid (it == null || ...
), this is the default behavior for all Valiktor functions. If the property is nullable and cannot be null, the function isNotNull()
should be used.
Add internationalization support for the custom constraint is very simple. Just add a message to each message bundle file.
For example:
en
(e.g.:messages_en.properties
):
org.valiktor.constraints.Between.message=Must be between {start} and {end}
pt_BR
(e.g.:messages_pt_BR.properties
):
org.valiktor.constraints.Between.message=Deve estar entre {start} e {end}
Note: the variables start
and end
are extracted through the property messageParams
of the constraint Between
and will be formatted in the message using the Message formatters. If you need a custom formatter, see Creating a custom formatter.
See the sample
Valiktor supports suspending functions natively, so you can use it in your validations.
For example, consider this suspending function:
suspend fun countByName(name: String): Int
It cannot be called by isValid
because it doesn't allow suspending functions:
validate(employee) {
validate(Employee::name).isValid { countByName(it) == 0 } // compilation error
}
but we can use isCoValid
, that expects a suspending function:
validate(employee) {
validate(Employee::name).isCoValid { countByName(it) == 0 } // OK
}
Implementing validation on REST APIs is not always so easy, so developers end up not doing it right. But the fact is that validations are extremely important to maintaining the integrity and consistency of the API, as well as maintaining the responses clear by helping the client identifying and fixing the issues.
Valiktor provides integration with Spring WebMvc and Spring WebFlux (reactive approach) to make validating easier. The module valiktor-spring
has four exception handlers:
Spring WebMvc:
ConstraintViolationExceptionHandler
: handlesConstraintViolationException
fromvaliktor-core
.InvalidFormatExceptionHandler
: handlesInvalidFormatException
fromjackson-databind
.MissingKotlinParameterExceptionHandler
: handlesMissingKotlinParameterException
fromjackson-module-kotlin
.
Spring WebFlux:
ReactiveConstraintViolationExceptionHandler
: handlesConstraintViolationException
fromvaliktor-core
.ReactiveInvalidFormatExceptionHandler
: handlesInvalidFormatException
fromjackson-databind
.ReactiveMissingKotlinParameterExceptionHandler
: handlesMissingKotlinParameterException
fromjackson-module-kotlin
.
All the exception handlers return the status code 422
(Unprocessable Entity) with the violated constraints in the following payload format:
{
"errors": [
{
"property": "the invalid property name",
"value": "the invalid value",
"message": "the internationalization message",
"constraint": {
"name": "the constraint name",
"params": [
{
"name": "the param name",
"value": "the param value"
}
]
}
}
]
}
Valiktor also use the Spring Locale Resolver to determine the locale that will be used to translate the internationalization messages.
By default, Spring resolves the locale by getting the HTTP header Accept-Language
, e.g.: Accept-Language: en
.
Consider this controller:
@RestController
@RequestMapping("/employees")
class EmployeeController {
@PostMapping(consumes = [MediaType.APPLICATION_JSON_VALUE])
fun create(@RequestBody employee: Employee): ResponseEntity<Void> {
validate(employee) {
validate(Employee::id).isPositive()
validate(Employee::name).isNotEmpty()
}
return ResponseEntity.created(...).build()
}
}
Now, let's make two invalid requests with cURL
:
- with
Accept-Language: en
:
curl --header "Accept-Language: en" \
--header "Content-Type: application/json" \
--request POST \
--data '{"id":0,"name":""}' \
http://localhost:8080/employees
Response:
{
"errors": [
{
"property": "id",
"value": 0,
"message": "Must be greater than 0",
"constraint": {
"name": "Greater",
"params": [
{
"name": "value",
"value": 0
}
]
}
},
{
"property": "name",
"value": "",
"message": "Must not be empty",
"constraint": {
"name": "NotEmpty",
"params": []
}
}
]
}
- with
Accept-Language: pt-BR
:
curl --header "Accept-Language: pt-BR" \
--header "Content-Type: application/json" \
--request POST \
--data '{"id":0,"name":""}' \
http://localhost:8080/employees
Response:
{
"errors": [
{
"property": "id",
"value": 0,
"message": "Deve ser maior que 0",
"constraint": {
"name": "Greater",
"params": [
{
"name": "value",
"value": 0
}
]
}
},
{
"property": "name",
"value": "",
"message": "NĂŁo deve ser vazio",
"constraint": {
"name": "NotEmpty",
"params": []
}
}
]
}
Samples:
Consider this router using Kotlin DSL:
@Bean
fun router() = router {
accept(MediaType.APPLICATION_JSON).nest {
"/employees".nest {
POST("/") { req ->
req.bodyToMono(Employee::class.java)
.map {
validate(it) {
validate(Employee::id).isPositive()
validate(Employee::name).isNotEmpty()
}
}
.flatMap {
ServerResponse.created(...).build()
}
}
}
}
}
Now, let's make two invalid requests with cURL
:
- with
Accept-Language: en
:
curl --header "Accept-Language: en" \
--header "Content-Type: application/json" \
--request POST \
--data '{"id":0,"name":""}' \
http://localhost:8080/employees
Response:
{
"errors": [
{
"property": "id",
"value": 0,
"message": "Must be greater than 0",
"constraint": {
"name": "Greater",
"params": [
{
"name": "value",
"value": 0
}
]
}
},
{
"property": "name",
"value": "",
"message": "Must not be empty",
"constraint": {
"name": "NotEmpty",
"params": []
}
}
]
}
- with
Accept-Language: pt-BR
:
curl --header "Accept-Language: pt-BR" \
--header "Content-Type: application/json" \
--request POST \
--data '{"id":0,"name":""}' \
http://localhost:8080/employees
Response:
{
"errors": [
{
"property": "id",
"value": 0,
"message": "Deve ser maior que 0",
"constraint": {
"name": "Greater",
"params": [
{
"name": "value",
"value": 0
}
]
}
},
{
"property": "name",
"value": "",
"message": "NĂŁo deve ser vazio",
"constraint": {
"name": "NotEmpty",
"params": []
}
}
]
}
Samples:
Valiktor provides an interface to customize the HTTP response, for example:
data class ValidationError(
val errors: Map<String, String>
)
@Component
class ValidationExceptionHandler(
private val config: ValiktorConfiguration
) : ValiktorExceptionHandler<ValidationError> {
override fun handle(exception: ConstraintViolationException, locale: Locale) =
ValiktorResponse(
statusCode = HttpStatus.BAD_REQUEST,
headers = HttpHeaders().apply {
this.set("X-Custom-Header", "OK")
},
body = ValidationError(
errors = exception.constraintViolations
.mapToMessage(baseName = config.baseBundleName, locale = locale)
.map { it.property to it.message }
.toMap()
)
)
}
You can customize status code, headers and payload by implementing the interface ValiktorExceptionHandler
.
For Spring Boot applications, the module valiktor-spring-boot-starter
provides auto-configuration support for the exception handlers and property support for configuration.
Currently the following properties can be configured:
Property | Description |
---|---|
valiktor.baseBundleName | The base bundle name containing the custom messages |
Example with YAML
format:
valiktor:
base-bundle-name: messages
Example with Properties
format:
valiktor.baseBundleName=messages
Valiktor provides a module to build fluent assertions for validation tests, for example:
shouldFailValidation<Employee> {
// some code here
}
The function shouldFailValidation
asserts that a block fails with ConstraintViolationException
being thrown.
It's possible to verify the constraint violations using a fluent DSL:
shouldFailValidation<Employee> {
// some code here
}.verify {
expect(Employee::name, " ", NotBlank)
expect(Employee::email, "john", Email)
expect(Employee::company) {
expect(Company::name, "co", Size(min = 3, max = 50))
}
}
Collections and arrays are also supported:
shouldFailValidation<Employee> {
// some code here
}.verify {
expectAll(Employee::dependents) {
expectElement {
expect(Dependent::name, " ", NotBlank)
expect(Dependent::age, 0, Between(1, 16))
}
expectElement {
expect(Dependent::name, " ", NotBlank)
expect(Dependent::age, 17, Between(1, 16))
}
expectElement {
expect(Dependent::name, " ", NotBlank)
expect(Dependent::age, 18, Between(1, 16))
}
}
}
There are a number of modules in Valiktor, here is a quick overview:
The main library providing the validation engine, including:
- 40 validation constraints
- 200 validation functions for all standard Kotlin/Java types
- Internationalization support
- Default formatters for array, collection, date and number types
This module provides support for JavaMoney API types, including:
- Validation constraints and functions for
MonetaryAmount
- Default formatter for
MonetaryAmount
This module provides support for JavaTime API types, including:
- Validation constraints and functions for
LocalDate
,LocalDateTime
,OffsetDateTime
andZonedDateTime
- Default formatter for all
LocalDate
,LocalDateTime
,LocalTime
,OffsetDateTime
,OffsetTime
andZonedDateTime
This module provides support for Joda-Money API types, including:
- Validation constraints and functions for
Money
andBigMoney
- Default formatter for
Money
andBigMoney
This module provides support for Joda-Time API types, including:
- Validation constraints and functions for
LocalDate
,LocalDateTime
andDateTime
- Default formatter for all
LocalDate
,LocalDateTime
,LocalTime
andDateTime
Spring WebMvc and WebFlux integration, including:
- Configuration class to set a custom base bundle name
- Exception handler for
ConstraintViolationException
from Valiktor - Exception handlers for
InvalidFormatException
andMissingKotlinParameterException
from Jackson
Provides auto-configuration support for valiktor-spring, including:
- Configuration class based on properties
- Spring WebMvc exception handlers
- Spring WebFlux exception handlers
Spring Boot Starter library including the modules valiktor-spring and valiktor-spring-boot-autoconfigure
This module provides fluent assertions for validation tests
- valiktor-sample-hello-world
- valiktor-sample-nested-properties
- valiktor-sample-collections
- valiktor-sample-javamoney
- valiktor-sample-javatime
- valiktor-sample-jodamoney
- valiktor-sample-jodatime
- valiktor-sample-custom-constraint
- valiktor-sample-custom-formatter
- valiktor-sample-spring-boot-1-webmvc
- valiktor-sample-spring-boot-2-webmvc
- valiktor-sample-spring-boot-2-webflux
- valiktor-sample-spring-boot-2-webflux-fn
For latest updates see CHANGELOG.md file.
Please read CONTRIBUTING.md for more details, and the process for submitting pull requests to us.
This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.