> ## Documentation Index
> Fetch the complete documentation index at: https://validity-kt.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Why Validity

> What Validity is, the problem it solves, and the ideas the rest of these docs build on.

Validity checks that your data follows its rules, and tells you, in one pass, every rule it breaks. You write the rules
in Kotlin, next to the data, with the words of the requirement:

```kotlin theme={null}
::email required { email() }
::age ifPresent { min(18) }
```

Each broken rule becomes a `Violation` with three things:

> [card] A path
>
> Where the value is: `email`, `shipping.zipCode`, `items[1].quantity`, `prices[USD]`.

> [card] A message
>
> For people: `must be a valid email`. Configurable, and translatable.

> [card] A code
>
> For programs: `email`. Stable across versions and languages.

## The problem it solves

Most validation code starts as a few `if`s in a controller. Then the rules multiply: a field required only for
companies, a total that must match its items, a coupon that must exist in the database, a message in Portuguese for
some users. The `if`s spread, they stop at the first error, and nobody can tell which rules a request really follows.

Validity gives those rules one place and one vocabulary:

* **Rules read like the requirements.** `::email required { email() }` is the sentence from the ticket.
* **Conditions are plain Kotlin.** "Required if", "only for companies" and "after the check-in" are an `if`, a `when`
  and a field of the object. No validation groups, no annotations on the class.
* **`null` is decided once.** `required`, `ifPresent` and `forbidden` settle what `null` means, and every constraint
  after them works on the non-null type.
* **Every error at once.** A form shows all its errors in one round trip, and an API returns all of them in one
  response.

## How it compares

| | Validity | Konform | Valiktor | Akkurate | Jakarta Validation |
| - | - | - | - | - | - |
| Rules are | Kotlin DSL | Kotlin DSL | Kotlin DSL | Kotlin DSL | annotations |
| They live | in the class, or beside it | in a `Validation<T>` | usually in `init` | in a `Validator<T>` | on fields and classes |
| A rule on another field | `if`, `when` | `dynamic { }` | code in the block | code in the block | class-level constraint, groups |
| Code generation | none | none | none | KSP plugin | none |
| Platforms | JVM 17+ | Multiplatform | JVM | Multiplatform | JVM |

Each of them is a solid choice, and some go where Validity does not yet: Konform and Akkurate run on Kotlin
Multiplatform, and Jakarta Validation plugs straight into the frameworks that read its annotations.

## The ideas behind these docs

**1. A validation is a list of rules about one object**

You declare it in the class with [`Validatable`](https://validity-kt.dev/guides/rules-in-the-class), or beside it with
[`validation<T> { }`](https://validity-kt.dev/guides/rules-beside-the-class). Both run the same engine and accept the same constraints.

**2. A property starts with what null means**

[`required`, `ifPresent` or `forbidden`](https://validity-kt.dev/guides/null-values) come first. Inside their block, the value is never
`null`.

**3. Constraints are functions on the value**

`email()`, `minLength(3)`, `cpf()`: there are [175 of them](https://validity-kt.dev/constraints/overview.md), and
[your own](https://validity-kt.dev/guides/custom-constraints.md) look exactly the same.

**4. Validating returns every violation**

[`validate()`](https://validity-kt.dev/guides/results) gives you a list. [`validateOrThrow()`](https://validity-kt.dev/guides/exceptions) throws it, for the
edge of your system.

## Nothing hidden

No annotations, no code generation, no `kotlin-reflect`. `validity-core` depends on nothing but the Kotlin standard
library and kotlinx.coroutines, and phone numbers live in their own module, [`validity-phone`](https://validity-kt.dev/constraints/phone),
so libphonenumber is there only if you ask for it.

> [card] [Install it](https://validity-kt.dev/installation.md)
>
> Add one dependency to Gradle or Maven.

> [card] [Validate your first class](https://validity-kt.dev/quickstart.md)
>
> From zero to a list of violations in five minutes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.