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.
How Are They Related?⚓︎
Namespaces are prefixes of groupId
s. 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
.