[enhancement] Making `@Valid` optional for adapter generation, if inferrable

[mechite]

Related to (#666) avaje/avaje-http#666
and related to (#672) avaje/avaje-http#672

#672 implements a warning for avaje-http @Valid used outside of @Controller, which
is one of the issues that we face with the confusing / same annotation naming.

This issue is to request two things:

1. Issue a warning, if not already doing this, for usages of avaje-validator @Valid (or the
   @jakarta.validation.Valid etc that we support) - given that the type has no actual
   constraint usages declared

   Is it easy to determine if no constraints are declared?
   This update would do the same that #672 does.

2. Potentially more difficult update - @ValidatorModule annotation that goes on either
   a module-info or package-info for package/module-wide generation of validator adapters.

   This would have to walk the exports (or the annotated package) to list out what types contain
   usages of constraint annotations (annotations marked with @Constraint, etc).

   Then, the following example:

   import io.avaje.validation.constraints.NotBlank;
   
   //@Valid not required
   record User(@NotBlank String name, int age) {}

   ...becomes all that is required to generate a validation adapter.
   Whether that adapter is actually used with a call to validate doesn't matter

   ---

   An issue with this approach is similar to what @rbygrave said about "redundant @Inject",
   which also reminds me about Java not requiring @Override - a lot of these serve as a
   documentation tool.

   I like it for @Inject, I like it for @Controller @Valid, but I'm not sure if we need to say
   that an adapter is being generated, if it never gets used anyway.

   Marking a module as @ValidatorModule already does give some "explicit-ness" to this?
   (I chose that name here to be analogous to @InjectModule)

[rbygrave]

Just to state that we have to "prefer simplicity" and "prefer long term maintainability", and what that means is that things that "might be goodish maybe" but come at the cost of increasing complexity and hence damaging long term maintainability have a high bar to get over.

That is, we want to make sure we are clear in understanding the motivations and pain points that are being addressed by any given feature.

For this issue, we want to have a clear understanding of what the motivation / pain points are, the current workaround and options, and why the current situation isn't good enough.

[SentryMan]

For this issue, we want to have a clear understanding of what the motivation / pain points are, the current workaround and options, and why the current situation isn't good enough.

I don't see what's unclear? The request is to make it so that he doesn't have to annotate every single class with @Valid, he wants to annotate just the package/module and have everything in that package/module generated.

It can be inferred that the motivation/pain point is that he dislikes doing it manually for every class, the workaround is to keep the status quo, and the options are to agree if this is a good idea or disagree and do nothing.

[SentryMan]

options are to agree if this is a good idea or disagree and do nothing.

Myself I feel this idea has less mileage because of all the other annotations you need to put on a class for validating. Might be better for Jsonb to be honest

[mechite]

For this issue, we want to have a clear understanding of what the motivation / pain points are, the current workaround and options, and why the current situation isn't good enough.

The pain point is having two differing @Valid annotations.
I believe @SentryMan said that they can all be interchanged, but this can be confusing.

It kinda makes sense to me that we have @jakarta.validation.Valid, and this applies in both your
entity/DTO/etc contexts, and your @Controller context.
 

jakarta.validation:jakarta.validation-api:3.1.1 was published Feb 2025 and pulls no transitives.
It sucks to me that they didn't separate the constraints and @Valid (i.e. jakarta-validation-annotations).

 
 
It reduces clarity as Avaje is offering us two @Valid, semantically different, functionally identical.
http avaje/avaje-http#672 and validator #334 to me, is offering a clean solution, to the "clarity"
problem we created in trying to keep our two libraries decoupled.

---

The other proposal (@ValidatorModule) can be much more debatable.
I brought it up because it would be possible, not because it is actually something needed
or reducing verbosity in any way.

I don't hate the @Valid, I just hate that we have two of them, and even just issuing
warnings to "force one usage scenario" for each is really enough to solve that.

---

the current workaround and options

Really, right now there is no issue except that I now have a few projects that were mixing
and matching avaje-http @Valid on e.g. my DTOs, and avaje-validator @Valid on my
@Controllers, and this can confuse a reader.

[SentryMan]

I think we're pretty much good on the duplicate valid annotation front with that http PR being merged. On the validator side, that we should warn if a user forgets to add any constraints is just obvious to me. The only thing left which I find contentious is the @ValidatorModule thing.

[rbygrave]

It reduces clarity as Avaje is offering us two @Valid, semantically different, functionally identical.

No I don't think so. They are semantically different and functionally different (they have 2 very different purposes).

Confusing yes, but they are not the same thing nor trying to do the same thing.

The pain point is having two differing @Valid annotations.

Yes I can see that, possibly we should rename the one in http.

[SentryMan]

No I don't think so. They are semantically different and functionally different (they have 2 very different purposes).

Functionally they are pretty much the same. Both the http and the validator generators read them identically.

Yes I can see that, possibly we should rename the one in http.

With the http generator compile warning I see this as less of a problem going forward

[rbygrave]

Functionally they are pretty much the same. Both the http and the validator generators read them identically.

They shouldn't be, they have a different purpose.

Both the http and the validator generators read them identically.

Oh darn, that would be a mistake then actually. Looking ... hmmm, oh yes looks like we've made a mistake there really. Hmm.

[rbygrave]

Ok, so I think the story is something like: the avaje http and avaje validator @Valid started off as different concepts at different times which mostly translates into ... "http @Valid should only be used on controllers (as a marker for the http-generator to hook in a validator for validation of the request prior to invoking the controller method)"

Over time, they started being structurally the same and also actually became interchangable in avaje-validator (which wasn't the original design intent. That is, http valid was never intended to be used outside of controllers).

So yes imo we've got to something that is at least confusing.

Seems like 3 options:

1. See if the avaje-validator warnings work sufficiently well
2. Rename http @Valid to something like say @Validated (where http @Validated is ONLY used by http controllers)
3. Kinda treat them as a single concept / interchangable (but unfortunately I don't think we can't fully remove http valid because jakarta valid doesn't have group so we'd lose functionality).

[SentryMan]

Seems like 3 options:

Seems like only 1 to me, with extra steps to be done much later if desired

1. See if the avaje-validator warnings work sufficiently well

In my eyes this course of action was decided when we merged that http compile warning pr.

2. Rename http @Valid to something like say @Validated (where http @Validated is ONLY used by http controllers)

This is something we can do as a follow-up, but no matter what, a compiler warning must be given as such a change has tremendous impact.

3. Kinda treat them as a single concept / interchangable (but unfortunately I don't think we can't fully remove http valid because jakarta valid doesn't have group so we'd lose functionality).

We already decided against this when we merged the http compiler warning.

[mechite]

If we really accepted breaking changes, what if we did the opposite and you had @Unvalidated/@NonValidated
...and validation on controllers was default instead.

The use case:

• a body etc which is @Valid annotated and uses constraints
• not wanting to validate it, for whatever reason
  ...sounds less common to me?

Is there currently any negative impact to annotating an @Controller which has no validation, with avaje-http @Valid? Do we want to steer this way?

a compiler warning must be given

Overall those two PRs solve the actual issue in my view, we now force the "use case" of either annotation