Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 41 ยท The POM

Coordinates: groupId, artifactId, version

Learn Maven GAV coordinates: naming rules for groupId and artifactId, how versions are ordered, SNAPSHOT versus release, and why version ranges are risky.

Every Maven artifact in the world is identified by three values: a groupId, an artifactId and a version. Together they are called the coordinates, or GAV. A library you depend on is named by its coordinates, a project you build is named by its coordinates, and the repository files you download are stored in folders derived from them.

This lesson explains what each part means, how to choose good names, how Maven compares versions, what SNAPSHOT really means, and why version ranges look attractive but usually cause trouble. The runnable examples are stand-ins: a simplified version comparator and a version range matcher, both in Java.

Three values, one identity

groupId Who made it. Reverse domain.
artifactId What it is. Lowercase name.
version Which release of it.

Written as groupId:artifactId:version.

1 / 2

The three parts

XML
<groupId>com.example.shop</groupId>
<artifactId>shop-core</artifactId>
<version>2.3.1</version>

groupId names the organization or project family that owns the artifact. By convention it is a reversed domain name that you control, such as org.apache.commons or com.example.shop. This avoids clashes: two companies can both publish a library called utils, because their groupIds differ. If you do not own a domain, use a name tied to something you do own, such as io.github.yourname, which is also what Maven Central accepts for GitHub users.

artifactId is the name of the specific project or library inside the group. Use lowercase letters, digits and hyphens: shop-core, commons-lang3. Avoid spaces, uppercase and underscores. The artifactId becomes the first part of the JAR file name, so it appears in many places.

version says which release this is. The text is free-form, but conventions are strong. Most projects follow semantic versioning: MAJOR.MINOR.PATCH, where a patch fixes bugs, a minor adds features compatibly, and a major may break compatibility. Maven does not enforce this; it only compares the strings.

The three together read as com.example.shop:shop-core:2.3.1. You may also see a fourth and fifth part when needed: the packaging (jar, pom) and a classifier (such as sources or javadoc), which name alternative files of the same artifact. A plain dependency does not mention them.

The groupId does not have to match your Java package names, but many projects keep them aligned so the identity is easy to remember. Changing a project's coordinates later forces every user to update their POM, so choose carefully at the start.

Naming conventions at a glance

Part Do Avoid
groupId com.example.shop, org.apache.maven MyCompany, names you do not own
artifactId shop-core, user-service Shop Core, shop_core, ShopCore
version 1.0.0, 2.3.1-SNAPSHOT latest, dates as the only information

How versions are compared

Maven needs to decide which of two versions is newer. It does not simply compare text, because as text 1.10 comes before 1.9. Instead it splits the version into numbers and qualifiers and compares part by part.

The important rules:

  • Numbers compare as numbers: 1.10 is newer than 1.9.
  • Trailing zeros do not matter: 1.0 equals 1.0.0.
  • A qualifier after a hyphen makes a version older than the plain release, in this order: alpha < beta < milestone < rc < SNAPSHOT < (release, no qualifier) < sp (service pack).
  • Qualifiers that Maven does not know are treated as newer than the release and compare as text.

So the sequence 1.0-alpha-1, 1.0-beta-1, 1.0-rc-1, 1.0-SNAPSHOT, 1.0, 1.0-sp-1, 1.0.1 is in increasing order. These rules matter when Maven chooses between two versions of a library that your dependencies both want; see Transitive Dependencies and Mediation.

SNAPSHOT versus release

A version ending in -SNAPSHOT means "development version heading toward this release". It is a moving target: each time the team publishes a new snapshot build of 1.5.0-SNAPSHOT, it replaces the previous one under the same coordinates, and Maven can check the repository for a newer one (by default once a day).

A release version, with no SNAPSHOT, is meant to be immutable. Once 1.4.2 is published, its contents must never change, and Maven Central enforces this: you cannot overwrite a release. This guarantee is what makes builds reproducible. If your build uses lib:1.4.2 today, it gets the same bytes in two years.

The usual flow is:

  1. Develop on 1.5.0-SNAPSHOT.
  2. When ready, release 1.5.0 (a permanent, tagged build).
  3. Move on to 1.5.1-SNAPSHOT or 1.6.0-SNAPSHOT.

Practical consequences: never depend on a SNAPSHOT of someone else's library in a release build (the build is no longer reproducible), and do not publish a release that depends on snapshots. Releasing is covered in Publishing and Release Workflows.

Version ranges, and why to avoid them

Maven lets a dependency name a range instead of a single version, using interval notation:

Range Meaning
[1.0] exactly 1.0
[1.0,2.0) 1.0 or higher, below 2.0
(,1.5] anything up to and including 1.5
[1.0,) 1.0 or higher, no upper limit

Square brackets include the end; round brackets exclude it. A range makes Maven resolve the highest matching version available when it builds.

That sounds convenient, and it is the problem. The build result now depends on what has been published today. On Monday the build might pick 1.7.0; on Tuesday someone publishes 1.8.0 and your untouched project suddenly uses it, possibly breaking. Two developers can get different versions, and a CI build from last year cannot be reproduced. Ranges also slow down resolution, since Maven has to read repository metadata.

The professional approach is to pin exact versions, keep them in one place with properties or a BOM (Managing Versions), and upgrade deliberately, optionally with a tool that proposes updates (Dependency Security). Treat any range in a real project as a warning sign. The special words LATEST and RELEASE are deprecated in the same spirit.

Stand-in: comparing versions

The real comparison happens inside Maven's ComparableVersion class. The model below is a simplified version of the rules above: it handles numbers, trailing zeros and the common qualifiers, but not every unusual format. It sorts a shuffled list so you can see the order.

Java A simplified version comparator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The last three lines show the point of the exercise: 1.0 and 1.0.0 are equal (0), 1.10 beats 1.9 as a version (positive), but plain text comparison puts 1.10 before 1.9 (negative). The model ignores several details of the real algorithm, such as letters glued to digits (1.0b2) and a few special qualifier spellings.

Stand-in: ranges pick different versions on different days

The second model parses range syntax and shows the reproducibility problem: the same range picks a different version after a new release appears. For brevity it compares plain numeric versions only.

Java Version ranges are a moving target

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Look at the row for [1.0,2.0): it resolves to 1.7.0 on Monday and 1.8.0 on Tuesday, though nobody touched the project. The exact version [1.0] never changes, which is why pinning is the safe default. The real Maven reads these lists from each repository's maven-metadata.xml file instead of a fixed list.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which groupId follows Maven's naming convention?

    A groupId is a reversed domain name you control, in lowercase, such as com.example.shop.
  2. 2. How does Maven treat the versions 1.10 and 1.9?

    Maven splits versions into numbers, so 10 is greater than 9. Plain text comparison would give the wrong answer.
  3. 3. What is true of a release version such as 1.4.2 on Maven Central?

    Releases are meant to be permanent. Central does not allow replacing them, which makes builds reproducible.
  4. 4. Why are version ranges such as [1.0,2.0) discouraged?

    The build picks the highest matching version available at that moment, so the same POM can produce different results on different days.
  5. 5. Which version is the oldest?

    The qualifier order is alpha, beta, milestone, rc, SNAPSHOT, release, sp. So 1.0-beta-1 is older than 1.0-SNAPSHOT, which is older than 1.0.

Summary

  • Coordinates groupId:artifactId:version identify every Maven artifact; groupId is a reversed domain, artifactId is a lowercase hyphenated name.
  • Maven compares versions numerically with qualifier rules: alpha < beta < milestone < rc < SNAPSHOT < release < sp; 1.0 equals 1.0.0.
  • A -SNAPSHOT version is a moving development build; a release is immutable.
  • Version ranges resolve differently over time; pin exact versions and upgrade on purpose.
  • Pick coordinates carefully: changing them later affects everyone who depends on you.

Next, reusable values and build settings: Properties and Build Settings.