351

I'm currently in the process of moving some project from Ant to Maven. Conformist as I am, I want to use well-established conventions for finding groupId and artifactId, but I can't find any detailed conventions (there are some, but they don't cover the points I'm wondering about).

Take this project for instance, first the Java package: com.mycompany.teatimer

Tea timer is actually two words, but the Java package naming conventions forbid the insertion of underscores or hyphens, so I'm writing it all together.

I chose the groupId identical to the package ID because I think that's a good idea. Is it?

Finally, I have to pick an artifactId, I currently went for teatimer. But when I look at other Maven projects, they use hyphens to split words in artifactIds, like this: tea-timer. But it does look weird when concatenated to the groupId: com.mycompany.teatimer.tea-timer.

How would you do this?

Another example:

Package name: com.mycompany.awesomeinhouseframework

groupId: com.mycompany.awesomeinhouseframework (?)

artifactId: awesome-inhouse-framework (?)

Gerold Broser
  • 14,080
  • 5
  • 48
  • 107
Noarth
  • 3,981
  • 6
  • 23
  • 16

4 Answers4

285

Weirdness is highly subjective, I just suggest to follow the official recommendation:

Guide to naming conventions on groupId, artifactId and version

  • groupId will identify your project uniquely across all projects, so we need to enforce a naming schema. It has to follow the package name rules, what means that has to be at least as a domain name you control, and you can create as many subgroups as you want. Look at More information about package names.

    eg. org.apache.maven, org.apache.commons

    A good way to determine the granularity of the groupId is to use the project structure. That is, if the current project is a multiple module project, it should append a new identifier to the parent's groupId.

    eg. org.apache.maven, org.apache.maven.plugins, org.apache.maven.reporting

  • artifactId is the name of the jar without version. If you created it then you can choose whatever name you want with lowercase letters and no strange symbols. If it's a third party jar you have to take the name of the jar as it's distributed.

    eg. maven, commons-math

  • version if you distribute it then you can choose any typical version with numbers and dots (1.0, 1.1, 1.0.1, ...). Don't use dates as they are usually associated with SNAPSHOT (nightly) builds. If it's a third party artifact, you have to use their version number whatever it is, and as strange as it can look.

    eg. 2.0, 2.0.1, 1.3.1

Community
  • 1
  • 1
Pascal Thivent
  • 562,542
  • 136
  • 1,062
  • 1,124
  • 10
    I know these conventions, but they don't really say how the artifact name should be made up (there are no JAR naming conventions) and what to do if it would be the same as the groupId - I haven't seen a single POM where that is the case. – Noarth Sep 16 '10 at 10:34
  • @Noarth 1. The artifact name is at your discretion (but using hyphens in the name is a common practice). 2. You're looking for an absolute "rule" that doesn't exist (what if your *awesome inhouse framework* is made of several modules?). See for example the Spring, Maven, Hibernate, etc artifacts. – Pascal Thivent Sep 16 '10 at 10:55
  • No, no I don't have any modules, just simple projects. In fact, we don't have a project called "awesome inhouse framework" :) – Noarth Sep 16 '10 at 12:11
  • 11
    What about `package`? What's the difference to groupId? – KonstantinK Apr 26 '15 at 07:31
  • 1
    Is the artifactId allowed to have numbers in it? – theonlygusti Mar 08 '17 at 08:10
  • 1
    @PascalThivent I have no company. I create a maven project in IntelliJ for [SDP course project](https://github.com/al2helal/TextPad). Is there any recommendation to choose these for personal project? I am new in Maven. – alhelal Oct 13 '17 at 16:16
  • What about "work for hire" situations? Should I choose `groupId` as `com.client.website` or `com.my.website`? According to this answer it should be `com.my.website` since I don't control the client website... but I feel it should be the "site" of the real owner of the code which would mean using `com.client.website` instead. – Giacomo Alzetta Oct 04 '18 at 13:59
  • @KonstantinK I believe a package is a collection of modules/artifacts. With juts one module in a project, the main package of that project would be the same artifact that one module produces. For multiple modules in one project, the package would include all modules and their artifacts. – Paul-Sebastian Manole Nov 21 '18 at 10:36
167

Your convention seems to be reasonable. If I were searching for your framework in the Maven repo, I would look for awesome-inhouse-framework-x.y.jar in com.mycompany.awesomeinhouseframework group directory. And I would find it there according to your convention.

Two simple rules work for me:

  • reverse-domain-packages for groupId (since such are quite unique) with all the constrains regarding Java packages names
  • project name as artifactId (keeping in mind that it should be jar-name friendly i.e. not contain characters that maybe invalid for a file name or just look weird)
Dmitry Timofeev
  • 329
  • 2
  • 10
Henryk Konsek
  • 9,016
  • 5
  • 32
  • 41
  • 1
    I find the mixture of non-hyphen (awesomeinhouseframework) and hyphen (awesome-inhouse-framework) spelling a bit strange. Since the groupid does not allow hyphens I would stick with the non hyphen spelling for the artifactid as well. – Michael Küller Aug 23 '17 at 11:52
  • 4
    Please clarify what do you mean by "jar-name friendly" ? – vikramvi Nov 24 '17 at 09:56
  • The official documentation agrees with you: "Hyphens are perfectly acceptable in groupIds, and you would not need to change your Java package name to match it." https://central.sonatype.org/publish/requirements/coordinates/ – Ellen Spertus Jun 25 '23 at 17:47
114

Consider the following for building a basic first Maven application:

groupId

  • com.companyname

artifactId

  • project

version

  • 0.0.1
double-beep
  • 5,031
  • 17
  • 33
  • 41
Manwal
  • 23,450
  • 12
  • 63
  • 93
  • As a work for hire should I use `com.my.company.project` as `groupId` or `com.client.company.project`? – Giacomo Alzetta Oct 04 '18 at 14:02
  • @GiacomoAlzetta you can use any of formate suits you better. Some examples ‘com.companyName.hirePortal’ or ‘org.compnayName.hirePortal’. – Manwal Oct 04 '18 at 15:41
  • 8
    groupId should be com.companyname not com.companyname.project – Kamil Nękanowicz Oct 16 '18 at 11:34
  • Not really how it was designed, Apache encourages to add the project/module name in the groupId: https://maven.apache.org/guides/mini/guide-naming-conventions.html – Olix Jul 11 '23 at 10:12
-1

However, I disagree the official definition of Guide to naming conventions on groupId, artifactId, and version which proposes the groupId must start with a reversed domain name you control.

com means this project belongs to a company, and org means this project belongs to a social organization. These are alright, but for those strange domain like xxx.tv, xxx.uk, xxx.cn, it does not make sense to name the groupId started with "tv.","cn.", the groupId should deliver the basic information of the project rather than the domain.

Stephen Rauch
  • 47,830
  • 31
  • 106
  • 135
Tommy.Tang
  • 147
  • 7
  • 6
    This convention is preventing developers using maven due to that you must possess a domain before deploying your artifacts to the central maven repository. It is ridiculous. Possessing a domain could be a pretty cost year by year. – Tommy.Tang Oct 28 '18 at 03:54
  • 5
    There is ***no* requirement to actually own a registration** for that domain name. The only requirement is that your group Id, which will be your Java package name, not conflict with any other such name when deployed. This convention is certainly *not* preventing developers from using Maven. – Basil Bourque Mar 28 '20 at 04:44
  • 9
    A good practice is to derive package names from the repository URL. If you're using GitHub, your account is called `myuser` and your repository is called `myrepo`, then simply use the package name `com.github.myuser.myrepo`. That's free and still unique. – fxnn May 14 '20 at 20:27
  • The administrators of Maven Central now require using a reversed domain name. https://central.sonatype.org/publish/requirements/coordinates/ – Ellen Spertus Jun 25 '23 at 17:46