Maven Inheritance, Aggregation & the Effective POM

The diagram below is the layout of POMs for the scratch tidepool build (the layout of one module’s directories is on Philosophy, Coordinates & Directory Layout). Solid arrows point from a child to the POM it inherits from; dashed arrows point from an aggregator to the projects it builds.

tidepool-parent is both the parent of the three modules and their aggregator, which is the usual layout and the reason the two ideas get confused. example-corporate-parent is a parent only: building it builds nothing else. tidepool-all is an aggregator only: it inherits from nothing but the Super POM and exists so that a single command can build the company parent and the project together. All three situations are run below.

Source: Maven guide: Project Inheritance vs Project Aggregation

The company parent is shared by many projects and lives in its own repository. It holds what every project of the company needs: organization, license, the Java release, the pinned plugin versions and where to deploy releases.

(The xsi:schemaLocation attribute and the namespace declaration for xsi were left out of this listing. The deploy target is a local directory; nothing was deployed.) The project parent inherits from it, lists the modules and manages the dependency versions of the project; it sits in tidepool/pom.xml next to the three module directories, with the company parent in a sibling directory corporate/:

(Again without the xsi attributes.) A module is short, because almost everything is inherited. This is the whole tidepool-engine/pom.xml:

The module declares no groupId and no version (both come from the parent), no dependency versions (they come from the parent’s dependencyManagement, see Dependency Management & BOMs) and no relativePath, because the parent is in the default place. The three modules compile and package: mvn -B verify in tidepool/ on Maven 3.10.0 ended with BUILD SUCCESS for the four projects. These POMs are this page’s own lab setup, not examples from the Maven documentation.

<parent> names a POM by its coordinates (groupId, artifactId, version). The child must spell out all three; Maven 3 never infers them (Maven 4 can, see below). The fourth element, relativePath, tells Maven where to look for the parent POM on disk first. Maven looks for the parent in this order:

A file found at relativePath is accepted only when its groupId, artifactId and version match the declaration. An empty <relativePath/> skips step 1 and goes straight to the repositories, which is the right setting for a parent that is always consumed from a repository, for example a company parent that lives in another repository while the directory above the module holds something unrelated. The company parent in the tidepool example is found by the explicit <relativePath>../corporate/pom.xml</relativePath>; in a real repository, where corporate/ does not exist, the setting would be dropped or emptied and the company parent installed into a repository.

Three cases show what Maven does with a path that does not lead to the declared parent. The scratch child declares io.tidepool:wrong-parent:1, while ../pom.xml is io.tidepool:rp-parent:1. With an empty local repository, so that the parent cannot be found anywhere else, mvn -B -N validate on Maven 3.9.16 and 3.10.0 prints (the long message was cut; the Some problems line is printed by Maven itself):

(That output is from 3.9.16. Maven 3.10.0 prints the same warning and the same error, only the reason for the failed download differs: it says the path io/tidepool/wrong-parent/1/wrong-parent-1.pom is not allowed from central, which comes from the repository prefix files that Maven 3.10 loads for Central.) With the same child and wrong-parent:1 installed in the local repository, Maven 3.9.16, 3.10.0 and 4.0.0-rc-7 all warn about the mismatch (Some problems were encountered while building the effective model, or on Maven 4 1 problem was encountered while building the effective model) and then end with BUILD SUCCESS, because the parent was found in step 2. So the warning is not harmless noise: it means "the file you pointed at is not the parent, and I fell back to the repository". When the sibling is not the parent, set relativePath to the right file or to an empty element.

A path to a file that does not exist is treated differently by Maven 3 and Maven 4. The child above with <relativePath>../does-not-exist/pom.xml</relativePath> and the parent installed in the local repository built with BUILD SUCCESS on Maven 3.9.16 and 3.10.0: Maven 3 silently falls back to the repository. On Maven 4.0.0-rc-7 it stops:

Maven 3.10.0 adds validation of the value itself. The release notes say that "relativePath of a parent is validated as well, which no Maven 3.x version did so far". A path with a character that is illegal in file names is now an error. The same child with <relativePath>../par*ent/pom.xml</relativePath> printed on Maven 3.10.0:

and built with BUILD SUCCESS on Maven 3.9.16, which never looked at the value. This is one instance of the stricter POM validation of 3.10: duplicated plugins, malformed snapshot versions and similar mistakes that were warnings in Maven 3.9 now fail the build (see Maven Versions & Release History). A build that fails on a POM that "always worked" after the upgrade is usually this.

The parent POM must also be available to everyone who uses the child as a dependency: a consumer resolves the child’s POM, then its parent’s POM, and so on up the chain. After mvn install on tidepool-all (below) with a scratch local repository, the repository held the POMs of every link in the chain:

(find . -name '*.pom', sorted.) Forgetting to deploy a parent POM is a classic way to publish a library nobody can build against; install and deploy of a pom-packaged parent only publish that single POM. See Install, Deploy & Distribution Management.

Source: Maven guide: Project Inheritance

Source: Maven 3.10.0 release notes: Stricter POM validation

A POM without <parent> is not parentless. Every POM ultimately inherits from the Super POM, which is a file inside the maven-model-builder JAR of the Maven installation (org/apache/maven/model/pom-4.0.0.xml). The Super POM supplies what makes mvn package work with a POM of five lines: the standard directories, the Central repository and the final name. The Super POM of Maven 3.10.0, extracted from lib/maven-model-builder-3.10.0.jar (the license comment and blank lines were removed):

Everything that "convention over configuration" promises is in these 60 lines, together with the lifecycle bindings of the packaging (see Build Lifecycle). The only thing a POM must state is its own coordinates; src/main/java is where sources are because this file says so, and a POM that overrides <sourceDirectory> overrides the Super POM exactly as it would override a parent.

Source: Maven Model Builder: Super POM

The maven-model-builder documentation states the rule in one sentence: every model field is inherited as-is from the parent, with a few exceptions that are intentionally not inherited: modelVersion, artifactId, packaging, profiles (injected in an earlier phase) and prerequisites. In practice, with the elements most POMs use:

The table was checked on a scratch pair of POMs. The parent declares a name, a description, a url, <modules> and two plugins, one of them with <inherited>false</inherited>; the child declares only its artifactId. The values Maven computes for the child, from mvn -B -q -f child/pom.xml help:evaluate -Dexpression=... -DforceStdout for each expression (the blank lines between the answers and the JDK 26 warnings about sun.misc.Unsafe that the plugin’s XML library prints were removed):

project.name equals the artifactId because Maven shows the artifact id when there is no name; the parent’s name "Inheritance parent" did not arrive. The url is the parent’s https://example.org/inh with /inh-child appended. In the effective POM of the child, written with help:effective-pom -pl child, the plugin inherited-plugin is present, the plugin parent-only-plugin (which has <inherited>false</inherited>) is absent, and there is no <modules> element (grep -c printed 0).

Both lists of plugins and the <configuration> of each plugin are XML, and merging two XML trees needs a rule. The default rule is: elements are matched by name, a child element replaces a parent element of the same name, and elements that exist on only one side are kept. For a list (several elements with the same name) the default is therefore "the child’s list replaces the parent’s list", not "the lists are added". Two attributes on the child’s element change that:

The parent from the experiment configures a (fictional) plugin with a list and a map:

Three children configure the same plugin with <stations><station>lagoon</station></stations> and <labels><depth>deep</depth></labels>, with no attribute, with combine.children="append" on stations, and with combine.self="override" on both stations and labels. The merged <configuration> from help:effective-pom (Maven 3.10.0; the plugin is never executed, so it does not have to exist):

This is the actual merged XML for the second child; the attribute is kept in the effective POM:

(Indentation trimmed.) The reference page warns that combine.self="override" wins when both attributes are on one element. Use combine.children="append" for lists you want to extend (compiler arguments, excludes, extra resources directories), and combine.self="override" for the case "the parent configuration must not apply here at all". Anything else is the default merge and is rarely what you meant for a list. The same attributes apply to pluginManagement configuration and to <executions> merged by id; how plugin configuration works in general is on Maven Plugins & Their Configuration.

Source: Maven POM reference: combine.children and combine.self

A POM with <packaging>pom</packaging> and a <modules> list is an aggregator. Every <module> is the path of a directory that holds a pom.xml (or the path to a POM file), relative to the aggregator. When Maven is run on the aggregator it reads the module POMs, builds a reactor with all of them and runs the requested phase on each, in an order decided by their dependencies, not by the order of the list. The tidepool/ aggregator, run with mvn -B validate on Maven 3.10.0, printed:

(The first lines of the reactor listing; the rest of the build was left out.) The aggregator is built first when it is also the parent, because a project cannot be built before its parent is known. The reactor, its flags (-pl, -am, -amd, -rf, -N, -T) and the failure policies are the subject of Multi-Module Builds & the Reactor; the command-line side is on Running Maven from the Command Line.

Because aggregation and inheritance are independent, three layouts are all legal, and all three were run:

A parent that is also the aggregator (the usual case): tidepool/pom.xml above. The modules inherit from it and it lists them.

A parent that aggregates nothing: the company parent. In corporate/, mvn -B validate ran a single project, with no reactor summary (the output was just the project header example-corporate-parent, [ pom ], and BUILD SUCCESS). Nothing in the company parent knows who inherits from it, and it should not.

An aggregator that is nobody’s parent: tidepool-all/pom.xml. It has no <parent>, so it inherits from the Super POM only, and it lists the company parent and the project, both outside its own directory:

mvn -B validate in tidepool-all/ (Maven 3.10.0; the [INFO] prefix and timings were removed from the summary):

The company parent comes first, then the project parent, then the modules, as the parent relations require; the aggregator has nothing that its modules need, so it ends up last. The relativePath of tidepool-parent points at ../corporate/pom.xml, and this is the situation where it matters: both are in the reactor and Maven wires them together. An aggregator like this is the usual way to build several repositories at once in a monorepo or in a CI job, without making any of them the parent of the others. A directory name can also be a module without any <parent> relation in the other direction: modules do not have to declare the aggregator as their parent.

To build only the aggregator and none of its modules, -N (--non-recursive) is used; mvn -B -N validate in tidepool/ printed a single successful project, tidepool-parent.

Source: Maven guide: Project Aggregation

Source: Maven POM reference: A final note on Inheritance v. Aggregation

The reference closes the comparison with a rule of thumb that works well: use inheritance to remove repetition, use aggregation to build things together, and keep them in one POM only when the layout is simple. The tidepool parent does both because the modules live in subdirectories of it. Separate them when the shared configuration is shared by projects that are not built together (the company parent) or when the reactor should include projects that share nothing (tidepool-all). The converse mistake is to add a module to <modules> expecting it to inherit: the module still needs its own <parent>.

Two levels of parent are enough for most organisations.

The company (organisation) parent is a pom-packaged project that is released by itself, often in its own repository and with its own version (7 above), and consumed by every project through <parent>. What belongs in it, because it is the same for all projects and rarely changes:

What does not belong: dependencies that only some projects need (put them in a BOM, see Dependency Management & BOMs), anything that depends on the layout of a particular project, and plugin executions that would run in every project of the company. Because a project has one parent only, a company parent that carries a long dependencyManagement makes it hard to also inherit from a framework’s parent POM; importing a BOM with <scope>import</scope> does not use up the <parent> slot.

The project parent (tidepool-parent) inherits from the company parent, aggregates the modules and holds the project’s own managed dependency versions, the module list and any properties the modules share. A change to it is a change in all the modules at once; the version is the project version, and the modules inherit it, so a release changes one number (see Versions, Snapshots & Ranges for ${revision} and CI-friendly versions that keep that single number out of every file).

The company parent is itself a project to release and deploy, and it must be in a repository before any project builds from outside the repository that holds it. In the example the relativePath is set because everything is in one directory tree; a project that is built on its own from a clean checkout would either drop that line, so that the repository is searched, or install the company parent first.

What Maven does with a build is determined by the effective POM: the Super POM, the chain of parents, the active profiles, the interpolation of every ${...} and the default lifecycle bindings, merged. It is what remains after all the rules of this page have been applied, and the Help plugin prints it:

Without -Doutput the POM is printed to the console (surrounded by log lines, which is why -q and -Doutput are used when you want a file). For tidepool-engine on Maven 3.10.0 the effective POM has 307 lines. A selection, in the order of the file, with the lines that were left out replaced by ...:

Read it for these things: the dependency versions that were not in the module POM (resolved from dependencyManagement), the properties that came from three different places, the distributionManagement that came from the company parent, the plugin version pinned by pluginManagement, and the default-* executions that the packaging added (see Build Lifecycle). The paths in <build> (sourceDirectory, outputDirectory, …​) were written as absolute paths on the machine; they are the Super POM’s ${project.basedir}/src/main/java after interpolation. With -Dverbose=true (a parameter since Help plugin 3.2.0; 3.5.2 was used) the plugin adds a comment to every element with the POM and line that the value came from. The same run (Maven 3.10.0, shortened):

That is the fastest answer to "where does this value come from?": the Java release is on line 30 of the company parent, the version is on line 16 of the project parent, and the output timestamp is the Super POM’s. (Line numbers are those of the scratch files; url and scm values are shown with the appended artifact id and point to the lines of the parent that supplied them.)

The same kind of question exists for settings.xml, which also merges (the global settings, the user settings, and -s and -gs on the command line, see settings.xml & Password Encryption):

With a scratch settings-demo.xml that declares a server corp-releases with ${env.REPO_USER} and ${env.REPO_PASSWORD}, and an active profile fast that sets skipITs, the result on Maven 3.10.0 was (header removed, home directory shortened):

The password is masked as *** by the plugin, which makes the output safe to paste into a ticket. The mirror that blocks plain http:// repositories (HTTP repositories are blocked since Maven 3.8.1) comes from the global conf/settings.xml of the Maven installation, and the default plugin groups from the settings model; neither was in the scratch file, and this listing is the quickest way to see that a mirror exists when a download fails. The ${env.REPO_USER} stayed as it was because that variable was not set in the shell; the placeholders are expanded when the credentials are used. mvn help:active-profiles -pl tidepool-engine printed - fast (source: external) for the same file: the profile that was active for that project and where it was declared.

The effective POM does not say what the profiles that are inactive would add. For that, help:all-profiles lists them, and -P activates one (see Profiles). On the tidepool build help:all-profiles printed the heading and no profile, because the example has none. For a task such as "why is this plugin configured this way", combine the verbose effective POM with mvn -X, which prints the configuration that each mojo actually received (see Troubleshooting & Best Practices). The Maven 3.10 release notes mention that model problems found while building the project are available to plugins in the session, so that a plugin can reject a build that has model warnings; the Enforcer rules in The Enforcer Plugin are the usual place to do that.

Source: Help plugin: help:effective-pom

Source: Help plugin: help:effective-settings

Source: Help plugin: help:active-profiles

Both of the other tools share configuration across projects, with a different mechanism:

The notable difference is that in Maven the parent relation is part of the project’s coordinates and of what is published, whereas a Gradle convention plugin or an Ant import is a build-time detail that consumers never see. The migration view is in Migrating Between Tools.