In a Maven repository, how is an artifact's file path built from its groupId, artifactId, version, classifier and extension?
answer
- coordinates become a path
- only the groupId's dots split
- artifactId and version directories
- classifier joins the file name
- checksum files sit beside it
basics
~10 sA Maven repository turns coordinates into a path: the groupId with dots replaced by slashes, then artifactId and version directories, and a file named artifactId-version[-classifier].extension, with .md5 and .sha1 checksum files beside it.
solid answer
~40 sThe layout is a pure function of the coordinates. The `groupId` has its dots replaced by slashes, the `artifactId` and the version add two more directories, and the file inside is `${artifactId}-${version}.${extension}`, or `${artifactId}-${version}-${classifier}.${extension}` when a classifier is present. So `com.example.billing:invoice-core:2.1.0:sources:jar` lives at `com/example/billing/invoice-core/2.1.0/invoice-core-2.1.0-sources.jar`. Beside every file sit checksum files (`.md5` and `.sha1` by default) and, optionally, a `.asc` PGP signature, while `maven-metadata.xml` sits one level up in the artifactId directory and lists the versions. Because the client computes every path itself, any static HTTP server can serve the repository without directory listing, and a file uploaded off-layout cannot be addressed by coordinates at all.
code
http · 5 linesGET /repository/maven-releases/com/example/billing/invoice-core/2.1.0/invoice-core-2.1.0-sources.jar HTTP/1.1
Host: repo.example.com
GET /repository/maven-releases/com/example/billing/invoice-core/2.1.0/invoice-core-2.1.0-sources.jar.sha1 HTTP/1.1
Host: repo.example.comgo deeper
Be able to write the path for any coordinates on a whiteboard: groupId dots to slashes, then artifactId and version directories, then the file name with the optional classifier.
Explain why the layout lets any static HTTP server act as a Maven repository, and where checksums, signatures and the artifactId-level maven-metadata.xml sit relative to the artifact.
Use the layout to debug: compute the expected URL for a failing resolve, request it directly, and tell a missing file from a wrong path, a wrong classifier or an integrity failure.
Treat the layout as a contract every tool in the ecosystem shares; anything that writes into a repository outside it, such as a hand-rolled upload script, creates files no build can address.
## What the layout is for A **Maven repository** is, at bottom, a tree of files served over a file-oriented protocol: `file://`, `http://` or `https://`, read with `GET` and written with `PUT`. The format defines no query API. A client that wants an artifact does not ask the server "where is it?"; it **computes the path** from the artifact's coordinates and requests that URL. The rule that does this is the **repository layout** (called "maven2" or "default"; the older Maven 1 layout is no longer supported). This design has two consequences worth saying out loud in an interview: - **The server needs no logic.** Any static file server can be a Maven repository, and it does not even need directory listing, because Maven never lists a directory to find a file. - **A file that is off-layout is not addressable.** If something uploads a JAR to a path the rule would never produce, no `groupId:artifactId:version` maps to it, so no build can resolve it. ## The transformation, step by step The coordinates are `groupId`, `artifactId`, `version`, an optional `classifier` and an `extension`. Only one of them is transformed: | Coordinate | Transformation | Example | |---|---|---| | `groupId` | every `.` becomes `/` | `com.example.billing` -> `com/example/billing` | | `artifactId` | none (dots stay dots) | `invoice-core` | | `version` | none | `2.1.0` | | `classifier` | none; appended to the file name | `sources` | | `extension` | none | `jar` | Building the path: 1. Start with the groupId as directories: `com/example/billing/`. 2. Add the artifactId directory: `invoice-core/`. 3. Add the version directory: `2.1.0/`. 4. Add the file name: `invoice-core-2.1.0.jar`, or with a classifier, `invoice-core-2.1.0-sources.jar`. So `com.example.billing:invoice-core:2.1.0:sources:jar` resolves to `com/example/billing/invoice-core/2.1.0/invoice-core-2.1.0-sources.jar`. The classifier never gets a directory of its own, and a dot inside an artifactId is never split. ## What sits beside the artifact The version directory holds more than the JAR: - **The POM**, `invoice-core-2.1.0.pom`, which the client reads for the artifact's dependencies. - **Checksum files** next to each file, named by appending the algorithm: `.md5` and `.sha1` by default. They detect corruption in transit or storage. They are fetched from the same server over the same transport, so on their own they do **not** prove who published the file. - **An optional `.asc` file**, a detached PGP signature. Some repositories, such as Maven Central, require it. One level up, in the artifactId directory, sits **`maven-metadata.xml`** with its own checksums. It lists the versions of that artifact (`<versions>`, `<latest>`, `<release>`, `<lastUpdated>`) and is how a client discovers versions without listing directories. A groupId directory can also hold one, used only to map plugin prefixes. The repository root may carry extras such as `archetype-catalog.xml` or a `.index` directory, a content index built by Maven Indexer; resolving a dependency needs neither. ## Where the classifier and extension come from The groupId, artifactId and version come from the POM; the other two depend on when you look: - **At publication**, the plugins that build artifacts decide them. A plain JAR build attaches an artifact with extension `jar` and no classifier; a sources or test build attaches extra files with a classifier such as `sources`. - **At use**, a dependency's `<type>` (default `jar`) implies the extension and a default classifier, and `<classifier>` overrides the classifier. A dependency that names the wrong type therefore asks for a file name nobody published. ## SNAPSHOT versions bend the rule slightly For a `-SNAPSHOT` version, the **directory** uses the base version, for example `2.2.0-SNAPSHOT/`. In a remote repository each deployment can store the **file** under an effective version in which `SNAPSHOT` is replaced by a timestamp and counter (`YYYYMMDD.HHMMSS-${counter}`). A version-level `maven-metadata.xml` in that directory maps the base version to the timestamped files. This is the one place the file name and the directory name disagree. ## Debugging a failed resolve with the layout When a build reports that an artifact cannot be found, the layout turns guesswork into a check: 1. Write out the coordinates exactly as the build asked for them, including the classifier and the extension that the dependency's type implies. 2. Compute the path by hand and request the URL directly from the repository. 3. If it returns 404, list what *is* in the version directory through the repository manager's UI: a wrong classifier, a typo in the groupId or a file deployed under the wrong path shows up at once. 4. If the file is there but the checksum request fails or disagrees, the problem is integrity, not location. ## Common misreadings - Treating the classifier as a subdirectory under the version. - Splitting a dotted artifactId into directories as if it were part of the groupId. - Assuming Maven lists the version directory to see which files exist. - Reading the `.sha1` file as proof that the publisher is trusted.
- Why does a SNAPSHOT file name differ from its directory name in a remote Maven repository?The directory uses the base version, such as `2.2.0-SNAPSHOT`, while each deployment to a remote repository can store the file under an effective version where `SNAPSHOT` is replaced by a timestamp and counter (`YYYYMMDD.HHMMSS-${counter}`). A version-level `maven-metadata.xml` in that directory maps the base version to the timestamped files, and the client reads it to choose one.
- Do the .sha1 and .md5 files beside a Maven artifact prove it is trustworthy?No. They come from the same repository over the same transport, so they only detect corruption. Anyone able to replace the JAR can replace its checksum too. Trust needs a separate mechanism, such as verifying the optional `.asc` signature against a known key or comparing against checksums the build already expects from a trusted source.
- What happens to a file uploaded to a Maven repository at a path the layout would never produce?Whether the server stores it depends on the server, but no coordinates map to that path, so no build can request it by groupId, artifactId and version. The layout documentation calls such a file not addressable. A hand-written upload script with one path segment wrong produces exactly this: a file that exists and never resolves.
A library call number tells you the floor, shelf and position of a book, so you walk straight to it without asking the librarian. A Maven path works the same way: the coordinates are the call number, and a book shelved under the wrong number simply cannot be found.
- The classifier gets its own directory under the version directory.
- Dots in the artifactId are turned into slashes as well.
- Maven lists the version directory to find out which files exist.
- The .sha1 file proves the JAR came from a trusted publisher.
- Every release version directory carries its own maven-metadata.xml.