Skip to content

What is the difference between a groupId and a namespace?⚓︎

"groupId" and "Namespace" are similar terms that are used frequently throughout this documentation.

groupId⚓︎

"groupId" comes from Maven's coordinates. Specifically, it is the groupId part of groupId:artifactId:version (GAV). Users will most often encounter GAV coordinates in their build tool's dependency management. These coordinates tell the build tool which files specifically to download from Maven Central and other similar repositories.

As a publisher, your groupId differentiates your com.example:artifact:0.1.0 project from another artifact project. This is in contrast with some ecosystems that do not have this concept and can only have one artifact project published to their repository.

A groupId is also an effective tool for organizing related artifacts together in a way that provides clarity to end-users. A user can research a framework and see at a glance the difference between a compatible first-party library and a third-party library.

Namespace⚓︎

A namespace is relevant primarily to users who are publishing to Maven Central. Specifically, namespaces exist to manage permissions for publishers. Before publishing, a user must register a namespace. Namespaces are tied to either a domain name or source repository.

The purpose of tying namespaces to DNS and source repositories is to allow end-users to have a level of trust that the artifacts on Maven Central come from a particular project or organization. For DNS-based namespaces, hosting a corresponding website is not a requirement, but we are of the opinion that it is a useful tool for projects to provide a curated entrypoint to end-users that directs them to documentation, examples, source code, forums, etc. Although not a replacement for PGP signatures, a namespace also provides some assurance to end-users that the same publishers that released one version of an artifact were the ones to release another, even as individuals come and go from projects. For additional details, see the FAQ on why namespaces are tied to DNS.

Namespace Families / Parent and Child Namespaces⚓︎

Publishers with larger projects may have their namespaces organized into namespace families. The typical structure of a namespace family involves one parent namespace (e.g. com.example) and one or more child namespaces (e.g. com.example.child). Any publisher that is authorized to a parent namespace is implicitly authorized to all children of that namespace.

Namespace families are only needed if your project has a complex permissions model (e.g. you have a project that should have publishing access to com.example.child, but you want to prevent some of the publishers from accessing the broader com.example namespace). For most small to medium size projects, a single namespace will suffice.

Namespaces are prefixes of groupIds. If you are authorized to publish on the com.example namespace, you may publish a groupId of com.example, com.example.child, com.example.child.subproject, or any other namespace that begins with com.example. However, if you are only authorized on com.example.child, you cannot publish to com.example. You would be able to publish on com.example.child, com.example.child.subproject, com.example.child.subproject.nested, or any other namespace that begins with com.example.child.