Configurable Dependency Version Resolution Strategy

[gnodet]

Summary

Currently, Maven's resolver treats direct dependencies (declared in a POM) as absolute version requirements that always override transitive dependencies, even when transitive deps require higher versions. This requires extensive use of <dependencyManagement> blocks to control resolution. This RFE proposes a configurable mechanism to allow more flexible version resolution while maintaining user control.

Motivation

• Current Pain Point: Developers must explicitly manage many transitive dependencies through <dependencyManagement> to avoid version conflicts
• Flexibility Need: Different projects have different requirements—some need strict version control, others prefer automatic upgrades to satisfy transitive requirements
• Control Concern: Any change to default resolution behavior risks breaking builds unexpectedly (e.g., in reactor builds where in-development versions could be downgraded)

Proposed Solution

Introduce an optional directDependencyStrategy attribute at both project and dependency levels to control how direct dependencies participate in version conflict resolution:

<project directDependencyStrategy="flexible">
  <dependencies>
    <!-- Strategy "flexible" applies: allows transitive deps to override this version -->
    <dependency>
      <groupId>com.example</groupId>
      <artifactId>lib-a</artifactId>
      <version>1.0</version>
    </dependency>
  </dependencies>
</project>

Or at the individual dependency level:

<dependency>
  <groupId>com.example</groupId>
  <artifactId>lib-b</artifactId>
  <version>2.0</version>
  <directDependencyStrategy>fixed</directDependencyStrategy>  <!-- This version always wins -->
</dependency>

Strategy Options

• fixed (default): Direct dependency version is absolute; always wins version conflicts (current behavior)
• flexible: Allow the configured version resolver to apply its normal conflict resolution rules (e.g., highest version, nearest) even for direct dependencies, permitting transitive dependencies to override this direct dependency

Configuration

Strategy default can be controlled at multiple levels (lowest precedence to highest):

1. Maven Configuration: maven.resolver.directDependencyStrategy property

   <properties>
     <maven.resolver.directDependencyStrategy>flexible</maven.resolver.directDependencyStrategy>
   </properties>

2. Project Level: <project directDependencyStrategy="..."> in POM

3. Dependency Level: <directDependencyStrategy> within individual <dependency> block

Consumer Behavior

When a direct dependency with non-default strategy is consumed as a transitive dependency:

• The directDependencyStrategy attribute should be removed/not applied
• Resolution follows normal transitive dependency rules using the active conflict resolver
• Consumer POM controls conflict resolution via their own direct dependency strategies

Safeguards

• Build Validation: Maven warns if unexpected downgrades occur during resolution when using flexible strategy
• Reactor Awareness: In-development versions in reactor builds always take precedence over deployed versions
• Explicit Override: Individual dependencies can override project-level strategy setting

Benefits

• Less Configuration: Developers need fewer <dependencyManagement> entries
• Explicit Intent: Clear declaration of whether a version is fixed or flexible
• Gradual Adoption: Backward compatible; defaults preserve current behavior
• Flexibility: Works with any conflict resolver implementation (highest, nearest, etc.)
• Platform Compatibility: Works alongside platform/BOM-based dependency management

Implementation Notes

• Extends ConfigurableVersionSelector to check strategy configuration before applying fixed direct dependency preference
• Requires POM model updates to support directDependencyStrategy attribute
• Consumer POM transformations should strip directDependencyStrategy attributes during publishing
• Strategy resolution follows hierarchy: dependency-level > project-level > Maven property > hardcoded default

[vlsi]

Having directDependencyStrategy at dependency level looks strange.

WDYT of something like:

• dependencyVersionType: strict (select exactly this version), require (accept this or later), reject
• dependencyVersionMode: strict (select exactly this version), require (accept this or later), reject
• versionType: strict (select exactly this version), require (accept this or later), reject. It sounds better for <dependency> tag, however having a top level <project versionType="require"> would look misleading.

    <dependency>
      <groupId>com.example</groupId>
      <artifactId>lib-a</artifactId>
      <version>1.0</version>
      <dependencyVersionType>require</dependencyVersionType>
    </dependency>

    <dependency>
      <groupId>com.example</groupId>
      <artifactId>lib-a</artifactId>
      <version>1.0</version>
      <dependencyVersionMode>require</dependencyVersionMode>
    </dependency>

    <dependency>
      <groupId>com.example</groupId>
      <artifactId>lib-a</artifactId>
      <version>1.0</version>
      <versionType>require</versionType>
    </dependency>

[gnodet]

Having directDependencyStrategy at dependency level looks strange.

WDYT of something like:

• dependencyVersionType: strict (select exactly this version), require (accept this or later), reject

• dependencyVersionMode: strict (select exactly this version), require (accept this or later), reject

• versionType: strict (select exactly this version), require (accept this or later), reject. It sounds better for <dependency> tag, however having a top level <project versionType="require"> would look misleading.

  com.example lib-a 1.0 require com.example lib-a 1.0 require com.example lib-a 1.0 require

What would be the behaviour of the reject value ? Act like require, but fail if the version would change ?

I think we could have a top level dependencyVersionType on project, and a versionType on dependency.

[vlsi]

Consumer POM transformations should strip directDependencyStrategy attributes during publishing

Ah. I missed the idea is to strip the attribute on publishing.

In that regard, it makes no sense to have strict/reject/require version types.

If the new attribute was kept when publishing, then transitive dependencies could bring requirements like require 1.4 & reject [2.0,) below.

---

What would be the behaviour of the reject value ? Act like require, but fail if the version would change ?

My thought was as follows: sometime later the following cases might be helpful for both producers and consumers.

• require 1.4 & reject [2.0,)
  In other words: "I require 1.4", however, if somebody requests 2.1, then the resolution should fail as I know there are incompatibilities.
• strict 1.7
  In other words, "this works with 1.7 only"

In that regard, versionType could control the way conflicts would be resolved.
The initial implementation could be just strict + require (or fixed + flexible).

However, users would require a separate knob for "nearest vs highest" anyways, so their combinations would be as follows:

• strict + nearest: current behavior
• strict + highest: might be helpful for "forced override" of a version. I hope it should rarely be used
• require + highest: solves NoClassDefFoundError caused by nearest. I hope this would become a new default one day
• require + nearest: it is probably the same as strict + nearest. We could issue warning and be done with it

[rmannibucau]

Open question:

• what about consumer pom, think we are still doomed there with this option since we do not want to flatten anymore nor exclude all transitive deps of flattend deps if we go back on flattening
• what if 2 deps use require and have the same transitive deps (= we are in the same state than today, you do resolve it manually, it is just worse cause you have to do it whereas today it just works most of the time)

aren't we looking for something overkilled? Shouldn't we just do an extension which enables to refine dependencies based on a custom criteria like in gradle but not support it by default to encourage consistency and reliability?

[vlsi]

@gnodet , I have read the proposal again, and I do not see user story in it.
In other words, I do not see what would really change for the end-user if they flip the added directDependencyStrategy setting. It would be great if you could clarify the end-to-end flow

[gnodet]

@gnodet , I have read the proposal again, and I do not see user story in it. In other words, I do not see what would really change for the end-user if they flip the added directDependencyStrategy setting. It would be great if you could clarify the end-to-end flow

Given this is a breaking change, the idea is to let the user opt-in by changing using the maven configuration property in .mvn/maven.properties or by setting the directDependencyStrategy="flexible" globally on the project element. The flag could also be changed in ~/.mvn/maven.properties or $MAVEN_HOME/conf/maven.properties to have a global effect for all projects.
A possible (but optional) enhancement would be to make the flag available for each dependency as stated in the original proposal, but this would require much more change (first in the POM object model, then in the resolver), while the global flag should be implementable only in Maven.

Once the user switches to flexible, the direct dependencies would be subject to conflict resolution. They are currently excluded, per the rule that, if the user explicitly specifies a version for a given dependency, that one should be honored. So basically direct dependencies always win during conflict resolution.

So in your original mvn-mediation use case, we have lib-a depending on guice:5.0.1, lib-b depending on guice:3.0, example-application depending on lib-a, lib-b and guice:3.0. With the current behaviour, example-application has a direct dependency on guice:3.0, so that version wins. If the user switches the project to use flexible, the direct dependency suddenly becomes subject to dependency resolution. Changing directDependencyStrategy only would not really change the output of the resolution, since the default version conflict resolution favours the dependencies closer to the top of the tree. However, if the user also changes the conflict resolution to use highest, then, the direct dependency would be subject to higher policy conflict resolution and would be switched to guice:5.0.1.

So this has to be coupled with selecting the highest version, else, there's not much point.

Given the flag only affects direct dependencies, this means that when a library is consumed by another project, the dependencies of the libraries become transitive dependencies, and the flag no longer apply. It thus becomes completely useless, which is a good thing, as it allows Maven to remove it from the consumer POM, since consumer POMs have a 4.0.0 model, and the flag could not be included anyway.

As a first step, I would not include the per-dependency flag, I'm not really it's worth it at the moment. If we don't want to change the model, we could also only use the maven property, just like we have with the highest property for the dependency conflict resolver...

[gnodet]

Actually, I think this comes down to just a different VersionSelector, something like flexible-highest instead of highest. That may be sufficient.

[rmannibucau]

flexible-highest for a common use case which is a downgrade? bom-transitive maybe or unknown to be clear it will look random for end users maybe

[vlsi]

Given this is a breaking change, the idea is to let the user opt-in by changing using the maven configuration property in .mvn/maven.properties or by setting the directDependencyStrategy="flexible" globally on the project element

@gnodet , do you mean activation of the property would automatically switch the resolution from "nearest to highest"?
Otherwise I do not see how directDependencyStrategy=flexible changes anything.

[vlsi]

If you think of a global property that changes the resolution strategy, then what do you think of the following?

1. Global property in maven.properties to configure resolution mode (e.g. maven.dependency.resolution.mode): nearest (default to keep the current behavior), highest
2. Dependency-level property like versionType = strict (default for nearest), require (default for highest)

In that case, there's no need in project-level dependencyVersionType.

[gnodet]

@vlsi I'm thinking that we just need a new strategy in the resolver. We recently introduced highest in the resolver, but that one does not take direct dependencies into account, following the unwritten rule that Maven does not override what the user explicitly stated.

If we relax this rule, assuming the user means "I require at least this version of the lib", we can add a new flexible (or whatever the name will be) strategy that will select the highest version for transitive and direct dependencies.
Compared to my original proposal, it's much simpler, but does not allow to tune a given dependency explicitly.

The question is whether the added complexity (to configure for a given strategy) actually solves a real use case or not.

[vlsi]

but does not allow to tune a given dependency explicitly

How about the following:

1. A new resolver goes with highest and treats default version declaration like require (even directly declared ones)

2. We add a new tag to <dependency> so user could fine-tune if they really need to enforce a specific version (e.g. for testing or whatever purposes)

   <dependency>
     <groupId>com.example</groupId>
     <artifactId>lib-a</artifactId>
     <version>1.0</version>
     <versionType>strict</versionType> <!-- or "require" which could be a default for "highest" resolver -->
   </dependency>

Then all existing projects continue just like they are doing now: nearest resolver, directly declared dependencies win.
A switch to highest resolver could be a single property in .mvn/...properties, and it could flip all deps (including direct) to highest mode. That sounds easy to understand and config to me.

---

The question is whether the added complexity (to configure for a given strategy) actually solves a real use case or not

It would solve the typical pain-points with NoClassDefFoundError which are quite common for Maven users.
A single configuration switch like "use highest dependencies" would have better chances of producing workable classpath than the current "nearest".

[gnodet]

Yes, but this needs a model change, a change in the resolver API to add support for this new field, and the field to be taken into account the resolver strategies, either only highest, but maybe others, with unknown side effects.

Hence my proposal to just add a different strategy, or modify highest to just also affect direct dependencies. This would allow the switch with just a single property in ./mvn/...properties anyway.

It really comes down to whether switching specific dependencies is a real use case or not. Given the problem is not know when the project is created, and mainly appears later when upgrading dependencies, I'm not sure why a user would choose to not follow the strategy for a given set of dependencies. If the user did switch to the new or updated highest strategy, and want to force a given dependency version, I think he can always choose to use a closed range in order to enforce this version. Though if the project is a library to be consumed by other projects, this will bring the constraints down to the consumer.