Payload validation

Fluxzero automatically validates incoming request payloads using its built-in Jakarta Validation 3.1 ↗ implementation. Hibernate Validator is not required for normal SDK payload validation.

This includes support for:

• standard Jakarta constraints such as @NotNull, @NotBlank, @Size, @Pattern, numeric constraints, and temporal constraints
• @Valid on nested objects and container/type-use validation
• validation groups, group sequences, group conversion, and custom constraint validators
• executable parameter and return-value validation
• contextual method constraints such as @AssertTrue methods that inject parameters via Fluxzero’s configured ParameterResolvers
• Constraint violations in command/query/webrequest payloads

If a constraint is violated, the handler method is never called. Instead, a ValidationException is thrown before the handler is invoked.

Java

public record CreateUser(@NotBlank String userId,
                         @NotNull @Valid UserProfile profile) {
}

Kotlin

data class CreateUser(
    @field:NotBlank val userId: String,
    @field:NotNull @field:Valid val profile: UserProfile
)

Context-aware constraint methods

Constraint methods on a payload may request contextual parameters that the SDK’s default validator can inject while a message is being handled. It uses the same resolver set as handler method injection, so values such as User, Message, DeserializingMessage, Metadata, and custom resolver values can be used directly.

Java

public record CreateUser(@NotBlank String userId) {
    @AssertTrue(message = "Only admins may create admin users")
    boolean allowedBy(User user, Message message) {
        return !userId.startsWith("admin-") || user != null && user.hasRole("admin");
    }
}

Kotlin

data class CreateUser(@field:NotBlank val userId: String) {
    @AssertTrue(message = "Only admins may create admin users")
    fun allowedBy(user: User?): Boolean {
        return !userId.startsWith("admin-") || user?.hasRole("admin") == true
    }
}

Note

If a constrained method declares parameters that cannot be resolved in the current validation context, Fluxzero skips that method for that validation run. Keep required structural checks on fields or no-argument constraint methods when a rule must also apply outside message handling.

You can disable this validation entirely by calling: Assuming you are configuring a FluxzeroBuilder builder:

Java

builder.disablePayloadValidation();

Kotlin

builder.disablePayloadValidation()

Of course, it’s also easy to provide your own validation if desired. Use replaceValidator(...) on the FluxzeroBuilder to replace the configured validator. Convenience methods on ValidationUtils delegate to the validator of the current Fluxzero instance when one is bound, and otherwise fall back to ValidationUtils.defaultValidator.

Tip

Fluxzero automatically correlates errors with the triggering message (e.g., a command or event). This means you don’t need to log extra context like the message payload or user ID — that information is already available in the audit trail in Fluxzero Runtime. It also encourages using clear, user-facing error messages without leaking internal details.