0Pricing
Spring Boot 4 Complete Guide · Lesson

Building Custom Constraint Annotations

Create reusable custom validators with ConstraintValidator for domain-specific validation logic.

Building Custom Constraint Annotations is a free Spring Boot 4 Complete Guide lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Spring Boot 4 Complete Guide learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Custom Constraints?

Bean Validation ships with annotations like @NotNull, @Size, and @Email. But real applications have domain-specific rules that no built-in annotation covers.

  • A username must be lowercase and 3-20 chars
  • A phone number must match your country's format
  • A status field must be one of an allowed enum set

Instead of writing manual checks in every controller or service, you can build a reusable custom constraint annotation that plugs into the same validation pipeline as the built-in ones.

The Two Pieces of a Custom Constraint

Every custom constraint in Spring Boot 4 (which uses Jakarta Bean Validation) has exactly two parts:

  • The annotation — what you write on a field, e.g. @ValidUsername. It declares metadata and points to a validator.
  • The ConstraintValidator — a class containing the actual isValid() logic.

The @Constraint meta-annotation links the two together. When validation runs, the framework instantiates your validator and calls isValid() for each annotated field.

Defining the Annotation

A custom constraint annotation must declare three standard attributes: message, groups, and payload. The @Constraint(validatedBy = ...) wires it to a validator class.

Note the imports come from jakarta.validation, not the old javax.validation.

import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.*;

@Documented
@Constraint(validatedBy = UsernameValidator.class)
@Target({ ElementType.FIELD, ElementType.PARAMETER })
@Retention(RetentionPolicy.RUNTIME)
public @interface ValidUsername {
    String message() default "invalid username";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

Understanding @Target and @Retention

Two meta-annotations control where and when your constraint applies:

  • @Target — where the annotation can be placed. FIELD for entity fields, PARAMETER for method args, METHOD for getters, TYPE_USE for generics like List<@ValidUsername String>.
  • @Retention(RUNTIME) — the annotation must survive into runtime so the validation engine can read it via reflection. This is mandatory; SOURCE or CLASS retention would make the constraint invisible.

Writing the ConstraintValidator

The validator implements ConstraintValidator<A, T>, where A is your annotation type and T is the type of the value being validated (e.g. String).

The isValid() method returns true if valid. A key rule: treat null as valid and let @NotNull handle nullness separately. This keeps each constraint focused on one concern.

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

public class UsernameValidator
        implements ConstraintValidator<ValidUsername, String> {

    @Override
    public boolean isValid(String value, ConstraintValidatorContext ctx) {
        if (value == null) {
            return true; // let @NotNull handle null
        }
        return value.matches("^[a-z0-9_]{3,20}$");
    }
}

Applying the Constraint

Once defined, your constraint is used exactly like a built-in one. Place it on a DTO field and combine it with other constraints. Spring evaluates all of them when the object is validated.

Use @NotNull alongside @ValidUsername since the validator deliberately allows null.

import jakarta.validation.constraints.NotNull;

public record RegisterRequest(
        @NotNull
        @ValidUsername(message = "username must be 3-20 lowercase chars")
        String username,

        @NotNull
        String password
) {}

Triggering Validation in a Controller

To run validation on incoming request bodies, annotate the parameter with @Valid. If any constraint fails, Spring throws a MethodArgumentNotValidException before your method body runs.

The message you set on the annotation becomes the error message reported back to the client.

import jakarta.validation.Valid;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping("/register")
    public String register(@Valid @RequestBody RegisterRequest req) {
        return "registered: " + req.username();
    }
}

Customizing the Error Message Dynamically

Sometimes a static message isn't enough — you want the message to reflect why validation failed. Use the ConstraintValidatorContext to disable the default message and build a custom one.

You must call disableDefaultConstraintViolation() first, then add your own violation, otherwise both messages appear.

@Override
public boolean isValid(String value, ConstraintValidatorContext ctx) {
    if (value == null) return true;
    if (value.length() < 3 || value.length() > 20) {
        ctx.disableDefaultConstraintViolation();
        ctx.buildConstraintViolationWithTemplate(
                "username length must be between 3 and 20")
           .addConstraintViolation();
        return false;
    }
    return value.matches("^[a-z0-9_]+$");
}

Passing Parameters to Your Constraint

Make constraints configurable by adding attributes to the annotation. For example, a @ValidUsername that accepts min and max length.

The validator reads these in initialize(), which runs once before isValid() calls.

public @interface ValidUsername {
    String message() default "invalid username";
    int min() default 3;
    int max() default 20;
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

Reading Parameters in initialize()

Override initialize() to capture the annotation's attribute values into fields. The framework calls it once per validator instance, before any isValid() invocation.

This lets one validator class serve many different configurations.

public class UsernameValidator
        implements ConstraintValidator<ValidUsername, String> {

    private int min;
    private int max;

    @Override
    public void initialize(ValidUsername ann) {
        this.min = ann.min();
        this.max = ann.max();
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext ctx) {
        if (value == null) return true;
        return value.length() >= min && value.length() <= max
                && value.matches("^[a-z0-9_]+$");
    }
}

Pure-Java: The Validation Logic Standalone

The core regex and length logic is plain Java you can test without any framework. Here is the same rule expressed as a runnable program to prove the logic before wiring it into Spring.

This isolation makes your validators easy to unit test.

public class Main {
    static boolean isValidUsername(String value, int min, int max) {
        if (value == null) return true;
        return value.length() >= min && value.length() <= max
                && value.matches("^[a-z0-9_]+$");
    }

    public static void main(String[] args) {
        System.out.println(isValidUsername("alice_99", 3, 20)); // true
        System.out.println(isValidUsername("Al", 3, 20));       // false
        System.out.println(isValidUsername("Bad Name", 3, 20)); // false
        System.out.println(isValidUsername(null, 3, 20));       // true
    }
}

Quick Check

You implement a custom ConstraintValidator for a String field. The field is optional, and a separate @NotNull already guards nullness. What should isValid() return when the value is null?

Recap

You learned how to build reusable custom constraint annotations in Spring Boot 4:

  • A constraint has two parts: the annotation (with message, groups, payload) and a ConstraintValidator.
  • @Constraint(validatedBy = ...) links them; @Retention(RUNTIME) and @Target control visibility and placement.
  • isValid() holds the logic and should treat null as valid, deferring to @NotNull.
  • Use initialize() to read annotation parameters, and ConstraintValidatorContext to craft dynamic messages.
  • Apply the constraint on DTO fields and trigger it with @Valid in controllers.

With these patterns, domain rules live in one tested place and plug seamlessly into Spring's validation pipeline.

Frequently asked questions

Is the “Building Custom Constraint Annotations” lesson free?

Yes — the full text of “Building Custom Constraint Annotations” is free to read here on the web, and the Spring Boot 4 Complete Guide course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Spring Boot 4 Complete Guide course, upgrade to CoddyKit PRO.

What will I learn in “Building Custom Constraint Annotations”?

Create reusable custom validators with ConstraintValidator for domain-specific validation logic. You practise Spring Boot 4 Complete Guide with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Spring Boot 4 Complete Guide?

No prior experience is required. Spring Boot 4 Complete Guide on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Building Custom Constraint Annotations” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Spring Boot 4 Complete Guide lesson?

Yes. Every Spring Boot 4 Complete Guide lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Bean Validation Constraints and Constraint Groups
  2. Building Custom Constraint Annotations
  3. Global Exception Handling with @ControllerAdvice
  4. RFC 7807 Problem Detail Responses
← Back to Spring Boot 4 Complete Guide