Maven

This is a reference for the Maven project descriptor used in Maven.

An XSD is available at:

<project>
  <extend/>
  <pomVersion/>
  <groupId/>
  <artifactId/>
  <id/>
  <name/>
  <currentVersion/>
  <shortDescription/>
  <description/>
  <url/>
  <logo/>
  <issueTrackingUrl/>
  <inceptionYear/>
  <gumpRepositoryId/>
  <siteAddress/>
  <siteDirectory/>
  <distributionSite/>
  <distributionDirectory/>
  <mailingLists>
    <mailingList>
      <name/>
      <subscribe/>
      <unsubscribe/>
      <post/>
      <archive/>
      <otherArchives/>
    </mailingList>
  </mailingLists>
  <developers>
    <developer>
      <id/>
      <name/>
      <email/>
      <url/>
      <organization/>
      <organizationUrl/>
      <roles/>
      <timezone/>
      <properties/>
    </developer>
  </developers>
  <contributors>
    <contributor>
      <name/>
      <email/>
      <url/>
      <organization/>
      <organizationUrl/>
      <roles/>
      <timezone/>
      <properties/>
    </contributor>
  </contributors>
  <licenses>
    <license>
      <name/>
      <url/>
      <distribution/>
      <comments/>
    </license>
  </licenses>
  <versions>
    <version>
      <name/>
      <tag/>
      <id/>
    </version>
  </versions>
  <branches>
    <branch>
      <tag/>
    </branch>
  </branches>
  <packageGroups>
    <packageGroup>
      <title/>
      <packages/>
    </packageGroup>
  </packageGroups>
  <reports/>
  <repository>
    <connection/>
    <developerConnection/>
    <url/>
  </repository>
  <organization>
    <name/>
    <url/>
    <logo/>
  </organization>
  <properties/>
  <packageName/>
  <build>
    <nagEmailAddress/>
    <sourceDirectory/>
    <unitTestSourceDirectory/>
    <aspectSourceDirectory/>
    <integrationUnitTestSourceDirectory/>
    <sourceModifications>
      <sourceModification>
        <className/>
        <property/>
        <directory/>
        <includes/>
        <excludes/>
      </sourceModification>
    </sourceModifications>
    <unitTest>
      <resources>
        <resource>
          <targetPath/>
          <filtering/>
          <directory/>
          <includes/>
          <excludes/>
        </resource>
      </resources>
      <includes/>
      <excludes/>
    </unitTest>
    <defaultGoal/>
    <resources>
      <resource>
        <targetPath/>
        <filtering/>
        <directory/>
        <includes/>
        <excludes/>
      </resource>
    </resources>
  </build>
  <dependencies>
    <dependency>
      <id/>
      <groupId/>
      <artifactId/>
      <version/>
      <url/>
      <jar/>
      <type/>
      <properties/>
    </dependency>
  </dependencies>
</project>

project

The <project> element is the root of the descriptor. The following table lists all of the possible child elements.

Element Description Since
extend The location of the parent project, if one exists. Values from the parent project will be the default for this project if they are left unspecified. The path may be absolute, or relative to the current project.xml file. For example, <extend>${basedir}/../project.xml</extend>. 3.0.0
pomVersion Declares to which version of project descriptor this POM conforms. The only valid value is 3. 3.0.0
groupId A universally unique identifier for a project. It is normal to use a fully-qualified package name to distinguish it from other projects with a similar name (eg. org.apache.maven). 3.0.0
artifactId The identifier for this artifact that is unique within the group given by the group ID. An artifact is something that is either produced or used by a project. Examples of artifacts produced by Maven for a project include: JARs, source and binary distributions, and WARs. 3.0.0
id Deprecated. When used, this sets both the groupId and artifactId elements if they were previously empty. 3.0.0
name The full name of the project. 3.0.0
currentVersion The current version of the artifact produced by this project. 3.0.0
shortDescription A short description of the project. The short description should be limited to a single line. 3.0.0
description A detailed description of the project, used by Maven whenever it needs to describe the project, such as on the web site. While this element can be specified as CDATA to enable the use of HTML tags within the description, it is discouraged to allow plain text representation. If you need to modify the index page of the generated web site, you are able to specify your own instead of adjusting this text. 3.0.0
url The URL to the project's homepage. 3.0.0
logo The URL of the project's logo image. This can be an URL relative to the base directory of the generated web site, (e.g., /images/project-logo.png) or an absolute URL (e.g., http://my.corp/project-logo.png). This is used when generating the project documentation. 3.0.0
issueTrackingUrl The URL of the project's issue tracking system. 3.0.0
inceptionYear The year of the project's inception, specified with 4 digits. This value is used when generating copyright notices as well as being informational. 3.0.0
gumpRepositoryId This is the repository identifier in Gump that this project is part of. 3.0.0
siteAddress The hostname of the web server that hosts the project's web site. This is used when the web site is deployed. 3.0.0
siteDirectory The directory on the web server where the public web site for this project resides. This is used when the web site is deployed. 3.0.0
distributionSite The server where the final distributions will be published. This is used when the distributions are deployed. If this isn't defined, the central repository is used instead as determined by maven.repo.central and maven.repo.central.directory. 3.0.0
distributionDirectory The directory on the web server where the final distributions will be published. This is used when the distributions are deployed. 3.0.0
mailingLists Contains information about a project's mailing lists. 3.0.0
developers Describes the committers of a project. 3.0.0
contributors Describes the contributors to a project that are not yet committers. 3.0.0
licenses This element describes all of the licenses for this project. Each license is described by a license element, which is then described by additional elements. Projects should only list the license(s) that applies to the project and not the licenses that apply to dependencies. If multiple licenses are listed, it is assumed that the user can select any of them, not that they must accept all. 3.0.0
versions Contains information on previous versions of the project. 3.0.0
branches Contains information on SCM branches of the project. 3.0.0
packageGroups Package groups required for complete javadocs. 3.0.0
reports This element includes the specification of reports to be included in a Maven-generated site. These reports will be run when a user executes maven site. All of the reports will be included in the navigation bar for browsing in the order they are specified. 3.0.0
repository Specification for the SCM used by the project, such as CVS, Subversion, etc. 3.0.0
organization This element describes various attributes of the organization to which the project belongs. These attributes are utilized when documentation is created (for copyright notices and links). 3.0.0
properties Project properties that will be used by various plugins. The format is <name>value</name>. 3.0.0
packageName The Java package name of the project. This value is used when generating JavaDoc. 3.0.0
build Information required to build the project. 3.0.0
dependencies This element describes all of the dependencies associated with a project. These dependencies are used to construct a classpath for your project during the build process. They are automatically downloaded from the repositories defined in this project. See the dependency mechanism for more information. 3.0.0

mailingList

This element describes all of the mailing lists associated with a project. The auto-generated site references this information.

Element Description Since
name The name of the mailing list. 3.0.0
subscribe The email address or link that can be used to subscribe to the mailing list. If this is an email address, a mailto: link will automatically be created when the documentation is created. 3.0.0
unsubscribe The email address or link that can be used to unsubscribe to the mailing list. If this is an email address, a mailto: link will automatically be created when the documentation is created. 3.0.0
post The email address or link that can be used to post to the mailing list. If this is an email address, a mailto: link will automatically be created when the documentation is created. 3.0.0
archive The link to a URL where you can browse the mailing list archive. 3.0.0
otherArchives The link to alternate URLs where you can browse the list archive. 3.0.0

developer

Information about one of the committers on this project.

Element Description Since
id The unique ID of the developer in the SCM. 3.0.0
name The full name of the contributor. 3.0.0
email The email address of the contributor. 3.0.0
url The URL for the homepage of the contributor. 3.0.0
organization The organization to which the contributor belongs. 3.0.0
organizationUrl The URL of the organization. 3.0.0
roles The roles the contributor plays in the project. Each role is described by a role element, the body of which is a role name. This can also be used to describe the contribution. 3.0.0
timezone The timezone the contributor is in. This is a number in the range -11 to 12. 3.0.0
properties Properties about the contributor, such as an instant messenger handle. 3.0.0

contributor

Description of a person who has contributed to the project, but who does not have commit privileges. Usually, these contributions come in the form of patches submitted.

Element Description Since
name The full name of the contributor. 3.0.0
email The email address of the contributor. 3.0.0
url The URL for the homepage of the contributor. 3.0.0
organization The organization to which the contributor belongs. 3.0.0
organizationUrl The URL of the organization. 3.0.0
roles The roles the contributor plays in the project. Each role is described by a role element, the body of which is a role name. This can also be used to describe the contribution. 3.0.0
timezone The timezone the contributor is in. This is a number in the range -11 to 12. 3.0.0
properties Properties about the contributor, such as an instant messenger handle. 3.0.0

license

Describes the licenses for this project. This is used to generate the license page of the project's web site, as well as being taken into consideration in other reporting and validation. The licenses listed for the project are that of the project itself, and not of dependencies.

Element Description Since
name The full legal name of the license. 3.0.0
url The official url for the license text. 3.0.0
distribution The primary method by which this project may be distributed.
repo
may be downloaded from the Maven repository
manual
user must manually download and install the dependency.
 3.0.0
comments Addendum information pertaining to this license. 3.0.0

version

This element describes each of the previous versions of the project. Each version is described by a version element

Element Description Since
name The external version number under which this release was distributed. Examples include: 1.0, 1.1-alpha1, 1.2-beta, 1.3.2 etc. 3.0.0
tag The name given in the SCM (e.g. CVS) used by the project for the source code associated with this version of the project. 3.0.0
id A unique identifier for a version. This is usually identical to the name. 3.0.0

branch

Contains information on the SCM branches of the project.

Element Description Since
tag The branch tag in the version control system (e.g. cvs) used by the project for the source code associated with this branch of the project. 3.0.0

packageGroup

A JavaDoc package group.

Element Description Since
title The title to use for the package group. 3.0.0
packages The packages in the group 3.0.0

repository

No description.

Element Description Since
connection The source control management system URL that describes the repository and how to connect to the repository. For more information, see the URL format and list of supported SCMs. This connection is read-only. 3.0.0
developerConnection Just like connection, but for developers, i.e. this scm connection will not be read only. 3.0.0
url The URL to the project's browsable SCM repository, such as ViewVC or Fisheye. 3.0.0

organization

Specifies the organization that produces this project.

Element Description Since
name The full name of the organization. 3.0.0
url The URL to the organization's home page. 3.0.0
logo The URL to the organization's logo image. This can be an URL relative to the base directory of the generated web site, (e.g., /images/org-logo.png) or an absolute URL (e.g., http://my.corp/logo.png). This value is used when generating the project documentation. 3.0.0

build

No description.

Element Description Since
nagEmailAddress An address to which notifications regarding the status of builds for this project can be sent. This is intended for use by tools which do unattended builds, for example those providing for continuous integration. 3.0.0
sourceDirectory This element specifies a directory containing the source of the project. The generated build system will compile the source in this directory when the project is built. The path given is relative to the project descriptor. 3.0.0
unitTestSourceDirectory This element specifies a directory containing the unit test source of the project. The generated build system will compile these directories when the project is being tested. The path given is relative to the project descriptor. 3.0.0
aspectSourceDirectory This element specifies a directory containing Aspect sources of the project. The generated build system will compile the Aspects in this directory when the project is built if Aspects have been enabled. The path given is relative to the project descriptor. 3.0.0
integrationUnitTestSourceDirectory This element specifies a directory containing integration test sources of the project. This element is not known to be used. 3.0.0
sourceModifications This element describes all of the sourceModifications associated with a project. These modifications are used to exclude or include various source depending on the environment the build is running in. 3.0.0
unitTest This element specifies unit tests associated with the project. 3.0.0
defaultGoal The default goal (or phase in Maven 2) to execute when none is specified for the project. 3.0.0
resources This element describes all of the classpath resources such as properties files associated with a project. These resources are often included in the final package. 3.0.0

sourceModification

This element describes all of the source modifications associated with a project. These modifications are used to exclude or include various source depending on the environment the build is running in.

Element Description Since
className If the class with this name can not be loaded, then the includes and excludes specified below will be applied to the contents of the sourceDirectory. 3.0.0
property If the property with this name is not set, then the includes and excludes specified below will be applied to the contents of the sourceDirectory. 3.0.0
directory Describe the directory where the resources are stored. The path is relative to the POM. 3.0.0
includes A list of patterns to include, e.g. **/*.xml. 3.0.0
excludes A list of patterns to exclude, e.g. **/*.xml 3.0.0

unitTest

No description.

Element Description Since
resources The classpath resources to use when executing the unit tests. 3.0.0
includes A list of patterns to include, e.g. **/*.xml. 3.0.0
excludes A list of patterns to exclude, e.g. **/*.xml 3.0.0

resource

This element describes all of the classpath resources associated with a project or unit tests.

Element Description Since
targetPath Describe the resource target path. For example, if you want that resource to appear in a specific package (org.apache.maven.messages), you must specify this element with this value: org/apache/maven/messages. This is not required if you simply put the resources in that directory structure at the source, however. 3.0.0
filtering Whether resources are filtered to replace tokens with parameterised values or not. The values are taken from the properties element and from the properties in the files listed in the filters element. The default value is false. 3.0.0
directory Describe the directory where the resources are stored. The path is relative to the POM. 3.0.0
includes A list of patterns to include, e.g. **/*.xml. 3.0.0
excludes A list of patterns to exclude, e.g. **/*.xml 3.0.0

resource

This element describes all of the classpath resources associated with a project or unit tests.

Element Description Since
targetPath Describe the resource target path. For example, if you want that resource to appear in a specific package (org.apache.maven.messages), you must specify this element with this value: org/apache/maven/messages. This is not required if you simply put the resources in that directory structure at the source, however. 3.0.0
filtering Whether resources are filtered to replace tokens with parameterised values or not. The values are taken from the properties element and from the properties in the files listed in the filters element. The default value is false. 3.0.0
directory Describe the directory where the resources are stored. The path is relative to the POM. 3.0.0
includes A list of patterns to include, e.g. **/*.xml. 3.0.0
excludes A list of patterns to exclude, e.g. **/*.xml 3.0.0

dependency

No description.

Element Description Since
id Deprecated. Please use groupId and artifactId together instead. 3.0.0
groupId The project group that produced the dependency, e.g. org.apache.maven. 3.0.0
artifactId The unique id for an artifact produced by the project group, e.g. maven-artifact. 3.0.0
version The version of the dependency, e.g. 3.2.1. In Maven 2, this can also be specified as a range of versions. 3.0.0
url This url will be provided to the user if the jar file cannot be downloaded from the central repository. 3.0.0
jar Literal name of the artifact in the repository. Used to override the calculated artifact name. 3.0.0
type The type of dependency. This defaults to jar. While it usually represents the extension on the filename of the dependency, that is not always the case. Some examples are jar, war, and plugin. A dependency of type plugin is loaded as a Maven plugin and not added to the project build classpath. The default value is jar. 3.0.0
properties Properties about the dependency. Various plugins allow you to mark dependencies with properties. For example the war plugin looks for a war.bundle property, and if found will include the dependency in WEB-INF/lib. 3.0.0