Akkurate Validation Library

Akkurate provides several key capabilities for developers:

• Declarative DSL: Write clear, readable validation code using loops and conditions instead of annotations.
• Essential Constraints: Includes a wide range of built-in constraints so you only write custom logic when necessary.
• Extensibility: Custom constraints can be implemented easily as simple lambdas.
• Contextual & Asynchronous: Validation rules can query external data sources (databases, REST APIs) both synchronously and asynchronously.
• Kotlin Multiplatform: Write validation logic once and deploy it across different platforms (front-end and back-end).
• Testability: Built-in support for testing validation logic.

Akkurate provides several core capabilities for validation:

• Declarative DSL: Write clear, DRY validation code using Kotlin syntax.
• Essential Constraints: Includes a wide range of built-in constraints so you only need to write custom logic for specific business rules.
• Extensibility: Custom constraints can be implemented easily as simple lambdas.
• Contextual & Asynchronous Support: Validation can include asynchronous calls to external data sources like databases or REST APIs.
• Kotlin Multiplatform: Write validation logic once and deploy it across different platforms (front-end and back-end).
• Testability: Designed to be easily testable out of the box.

Since version 0.7.0, Akkurate uses scope control (DSL markers) to prevent implicit references to outer receivers. When nesting validation blocks (e.g., using each inside a property block), you can no longer implicitly call methods belonging to the outer scope if they conflict with the current scope. If you need to apply a constraint to the property itself rather than the elements within it, you must ensure the call is correctly scoped.

@Validate
data class Book(val title: String, val labels: List<String>)

val validateBook = Validator<Book> {
    title.isNotBlank()

    labels {
        // Apply constraints to the 'labels' property itself
        hasSizeLowerThan(10)

        each {
            // Apply constraints to each element in the list
            isNotBlank()
        }
    }
}

When comparing two values (e.g., checking if a property matches a field in the parent object), you can use the == operator directly on Validatable<T> objects. Validatable<T> implements equals and hashCode as pass-through methods to the underlying value, so you do not need to call .unwrap() manually for equality checks.

Validator<Library> {
    val library = this
    for (book in books) {
        constrain {
            // No need for .unwrap() on both sides
            book.height == library.shelfHeight
        } otherwise { "Book height must be equal to shelf height" }
    }
}

When working inside an Arrow either { ... } block (a Raise computation), you can use the bind() function to seamlessly integrate Akkurate validations.

Instead of manually converting results to Either and handling errors with when or throw, bind() allows you to work directly with the validation results. If a validation fails, bind() will automatically short-circuit the computation and return the error, allowing you to focus on the 'happy path' logic.

either {
    // bind() automatically handles the conversion and short-circuits on failure
    val book = bind(validateBook(Book("The Lord of the Rings")))
    val author = bind(validateAuthor(Author("J.R.R. Tolkien")))

    // This code only executes if both validations succeed
    println("Validated book: $book")
    println("Validated author: $author")
}

Starting from version 0.9.0, the equals implementation for ConstraintViolationSet is symmetric. This means that comparing a ConstraintViolationSet to a standard Kotlin Set<ConstraintViolation> will return the same result regardless of which object is on the left-hand side of the equals call. This fixes a previous bug where the comparison was not symmetric.

// After v0.9.0
fun compare(
    standardSet: Set<ConstraintViolation>,
    constraintViolationSet: ConstraintViolationSet
) {
    standardSet.equals(constraintViolationSet) // ✅ true
    constraintViolationSet.equals(standardSet) // ✅ true
}

The Akkurate DSL handles nullability automatically during path traversal. If a property is nullable, the nullability propagates to all child properties in the path.

Nullability Propagation

If author is Author?, then author.user becomes Validatable<User?> and author.user.emailAddress becomes Validatable<String?>.

Constraint Behavior on Nulls

By default, if a property in the path is null, the constraint will always succeed. To force a property to be non-null, you must explicitly use the isNotNull() constraint.

Validator<Book> {
    author.user.emailAddress {
        isNotNull() // Fails if the value is null
        isNotEmpty() // Only checked if not null
    }
}

@Validate
data class Book(val author: Author?)

Validator<Book> {
    author.user.emailAddress {
        isNotNull()
        isNotEmpty()
    }
}

To avoid repeating the same validation logic across different models, you can compose validators. You can call an existing Validator<T> instance on a property using the .validateWith() method. This works for both single objects and collections (using each).

@Validate
data class Book(val author: Person, val reviewers: Set<Person>)

@Validate
data class Person(val fullName: String)

val validatePerson = Validator<Person> {
    fullName.isNotEmpty()
}

val validateBook = Validator<Book> {
    author.validateWith(validatePerson)
    reviewers.each { validateWith(validatePerson) }
}

Akkurate validation relies on two primary components:

1. @Validate annotation: Applied to a data class to mark it for the KSP compiler plugin. This triggers the generation of validatable accessors.
2. Validator<T> interface: Used to define the actual validation rules via a DSL.

When you annotate a class with @Validate and build the project (e.g., ./gradlew build), the compiler generates accessors that act as a bridge between the Validatable<T> DSL and your class properties. These accessors allow you to reference properties (like title or releaseDate) directly inside the Validator lambda.