Discovery (proposal)

The file format on this page is a proposal for any Java tool to adopt, so it may still change as others take it up. Jenesis reads it where jenesis.repository.discovery is set.

A Maven group ID or a Java module name are typically reversed domain names: net.bytebuddy belongs to bytebuddy.net, for example. This proposal lets whoever owns that domain say, in one small file on its website, https://<domain>/.well-known/java-repository.properties, where the artifacts and modules named after it are published. A build that reads the file downloads them from there - a GitHub release, the author's own server, or a Maven repository of the author's choosing - before it asks any central repository.

The file is a plain java.util.Properties file at a fixed address, so any tool can read it with the JDK alone, and it is agnostic to any particularities of a given build tool. Publishing it costs the author a static file; reading it costs a build one request per vendor.

Do you suggest not having a central repository?

No. A central repository that keeps every version ever published, immutable and in one place, has real value, and one account and one upload is a low barrier for a small project. What this proposal questions is that there is only one such repository, and that every library has to pass through it. Today, that is Maven Central - Maven's default repository.

The proposal changes who does what. Authors publish to the ecosystem rather than to one repository. Central repositories, as many as care to run one, collect what authors publish and offer the guarantees an author cannot give to the users who need them.

The trouble with a single repository

Every build looks to Maven Central, and no build replaces it on its own:

  • It is a single point of failure. When Central cannot be reached, neither can any library published nowhere else. Its terms of service state that outages may occur and that Sonatype is under no obligation to store or back up what is published.
  • It is run by one company. Sonatype, a private firm majority-owned by Vista Equity Partners since 2019, decides what Central accepts and may change its terms at any time. The rest of the Java ecosystem is governed by its community: the language through the Java Community Process, the JDK under the OpenJDK bylaws, and Maven at the Apache Software Foundation.
  • Its priorities become the ecosystem's. Java modules have named a library since Java 9 in 2017, yet Central finds an artifact by its coordinate, never by its module name. A build cannot resolve a requires from Central without a mapping kept elsewhere, such as the Jenesis Module Index.

Where the costs lead

Since October 2026, publishing an artifact of a commercial nature requires Sonatype's paid Publisher Pro, and so does publishing beyond monthly quotas on file count, release count and release size. The quotas count every signature, checksum, POM, sources and javadoc jar as a file, per organisation. A release of Byte Buddy publishes about 120 files and close to 70 MB, so a second release in a month passes the size quota. Byte Buddy is exempt, but every community project has to apply for an exemption of its own, an approach that does not scale with the number of projects.

For a company, this puts a price on shipping a Java SDK: Sonatype counts service-dependent SDKs and generated clients as commercial, however few files they hold. npm gives organisations unlimited public packages on its free plan, and NuGet.org publishes from a free account. A company can host its own Maven repository, but only Maven Central is available to every build by default.

An author who nears the quotas can only publish less: merge small modules, release fixes less often, or stop publishing a second project. And publishing more is what lies ahead. Commits to GitHub grew by a quarter in 2025, a pace agent-supported development is likely to raise, and published CVE records by 21% - every fix asks for a release.

Publishing to the ecosystem

With a discovery file, an author releases where they already distribute their work and says so once, on their domain. Every build and every central repository then finds the release by its name, without an upload, an account or a quota. The author decides how finely and how often to publish, and every download their hosting serves is one Central does not.

Some projects already publish outside Central, such as OpenSAML and Jenkins; today a build finds them only once its user configures their repository. Other ecosystems already work this way: Go asks the domain of a module path where its code lives, with a proxy and a checksum database as a cache and a ledger, not as a place every module must be uploaded to.

The file also lets the community adopt new coordinates without waiting for a central repository to support them. A reader ignores the keys it does not know, so a new convention needs only authors who publish it and tools that read it. This proposal already resolves a library by its module name, through the module key. Other conventions could follow, such as a key naming the JBang catalog of a domain's scripts, or one resolving a bundle by its OSGi symbolic name.

A discovery file may name Maven Central itself, so nothing changes for an author who publishes there. And a project can move elsewhere by changing the file, as a website moves to another host without changing its address.

What a central repository adds

Maven Central does two jobs in one: it distributes a release, and it vouches for it. Publishing to the ecosystem separates them. The author distributes; a central repository collects what authors publish, much as a build fetches it, and adds what an author cannot vouch for in their own work:

  • Retention. It keeps every version it has seen, after the author drops it or lets the domain lapse.
  • Immutability. It records each file as first fetched and refuses a later file that does not match, so an artifact cannot be swapped under an existing version.
  • Signature validation. It checks each signature, and notices when a new version is signed with another key - as a release from a lapsed domain bought by someone else would be, the attack MavenGate described in 2024.
  • Scanning. It checks each release for malware and known vulnerabilities, and marks the versions a later CVE affects.
  • Availability. It serves the release when the author's hosting is down.

Who pays for the guarantees

Today, the cost of a central repository falls on whoever publishes to it. Here, it falls on whoever needs its guarantees.

Open-source projects can do most of these checks in their own build - pin checksums, verify signatures, scan dependencies - and pay nothing. Enterprises typically want more: a compliance guarantee from a party that answers for it, and software shipped years ago that still builds from exactly the dependencies it was built with. Keeping old software running is how much software earns its money, and a repository that keeps old versions available, unchanged and vetted sells exactly that.

Anyone could run such a repository, so several could compete on availability, on the checks they run and on price. Not every version then needs to be kept forever for free: an author can drop an outdated version, and a repository that still keeps it can charge for doing so. A build that relies on Byte Buddy 0.1, a pre-release from 2014, would pay a premium to keep it available - an incentive to migrate once the legacy costs too much.

Describing Maven artifacts

The rest of this page is the proposal itself: the file a domain publishes and how a build reads it, starting with Maven artifacts, then modules mapped to Maven, then modules alone, and finally the sources of a release.

A domain publishes the file at https://<domain>/.well-known/java-repository.properties, a well-known location, in UTF-8. Its maven key says where the artifacts named after that domain are, and the name in brackets the artifact it is for:

maven[build.jenesis]=https://github.com/jenesis/jenesis/releases/download/v{version}/{artifactId}-{version}{-classifier}.{type}
maven[build.jenesis].suffixes=none

This file at jenesis.build says that the artifact build.jenesis is attached to the GitHub releases of Jenesis, and that those releases hold no snapshots. A dependency on build.jenesis:build.jenesis:0.15.4 then downloads https://github.com/jenesis/jenesis/releases/download/v0.15.4/build.jenesis-0.15.4.jar. A key without brackets, maven=..., serves every artifact of every group below the domain.

Which file answers

For net.bytebuddy.agent, a tool reads the file of bytebuddy.net - the two labels a vendor owns - and the file of agent.bytebuddy.net only where bytebuddy.net publishes none. The first file found speaks for every name below its domain, so one request answers for all of a vendor's groups, and a key it does not hold is absent rather than asked of a subdomain. A vendor whose subdomains publish files of their own adds delegate=true: those files are then read as well, the most specific one holding a key answers, and the vendor's own entries stand for the rest.

Several projects under one domain

A domain often serves more than one project, each released on its own and with versions of its own. Each key then names the artifacts it is for in brackets, and the keys beside it carry the same selector. jenesis.build serves the build tool, the launcher, the crawler and the modules of Jenesis Repository, all in the group build.jenesis, from the GitHub releases of four repositories:

maven[build.jenesis]=https://github.com/jenesis/jenesis/releases/download/v{version}/{artifactId}-{version}{-classifier}.{type}
maven[build.jenesis].latest=https://github.com/jenesis/jenesis/releases/latest/download/{artifactId}.pom
maven[build.jenesis.launcher]=https://github.com/jenesis/jenesis-launcher/releases/download/v{version}/{artifactId}-{version}{-classifier}.{type}
maven[build.jenesis.launcher].latest=https://github.com/jenesis/jenesis-launcher/releases/latest/download/{artifactId}.pom
maven[build.jenesis.crawler]=https://github.com/jenesis/jenesis-modules/releases/download/v{version}/{artifactId}-{version}{-classifier}.{type}
maven[build.jenesis.crawler].latest=https://github.com/jenesis/jenesis-modules/releases/latest/download/{artifactId}.pom
maven[build.jenesis.repository.*]=https://github.com/jenesis/jenesis-repository/releases/download/v{version}/{artifactId}-{version}{-classifier}.{type}
maven[build.jenesis.repository.*].latest=https://github.com/jenesis/jenesis-repository/releases/latest/download/{artifactId}.pom

maven selects by artifact ID, and module and moduletomaven select by module name. A selector ending in * selects every name that starts with the rest, as maven[build.jenesis.repository.*] does for the modules of Jenesis Repository, all named build.jenesis.repository.*. The exact name wins over the longest such prefix, and either over the key for all. A name that no key of the file selects, in a file without a key for all, is absent from it.

Roots and templates

A location takes one of two forms:

  • A root is a URI without placeholders: a traditional Maven repository such as Maven Central, a Nexus or an Artifactory, or any web server holding files in the Maven layout. It is read with its checksums, and its maven-metadata.xml is merged with that of the usual repositories, so a version range sees the versions of both - maven=https://maven-repository.example.com/releases/.
  • A template names each file through placeholders, which suits a flat list of downloads such as the assets of a GitHub release. Where a template names {type}, each file is checked against the .sha512, .sha256 or .sha1 beside it, the strongest one present, and a mismatch fails the build.

A Maven template fills in {groupId} (net.bytebuddy), {groupPath} (net/bytebuddy), {artifactId}, {version}, {-classifier} (-sources, or nothing for the plain jar) and {type} (jar, pom, jar.asc, jar.sha256). A template without {-classifier} or {type} serves only the plain jar, so a sources jar or a signature is never answered with the jar itself.

Which versions a key serves

Two keys beside a key restrict the versions it serves, and leave every other version to the usual repositories:

  • <key>.since=<version> names the first version, so an author can move downloads to a new place from one release on. Versions are ordered as Maven orders them: 1.2.3-rc.1 comes before 1.2.3, 1.10.0 after it.
  • <key>.suffixes=<suffix>[,<suffix>...] lists the qualifiers it serves - the part of a version after its first dash, matched by its leading word, ignoring case. none names a version without one; without the key, every version is served.

With maven.since=0.16.0 and maven.suffixes=none, 1.2.3 is served, while 1.2.3-SNAPSHOT and everything before 0.16.0 is not. The metadata of a root lists only the versions its key serves.

The newest version

A template cannot list versions, so "the newest release" comes from a link beside it, <key>.latest. A tool sends the link a HEAD request, follows no redirect, and reads the version from where it redirects to, matched against the template:

maven[build.jenesis].latest=https://github.com/jenesis/jenesis/releases/latest/download/{artifactId}.pom

GitHub redirects releases/latest/download/<name> to releases/download/v<version>/<name> of the newest release, whatever <name> is, so the link names the version without downloading anything. The version is then checked like any other, and the template answers Maven metadata naming it, merged with that of the usual repositories.

A link may instead name a maven-metadata.xml, so that the files come from one place and the versions from a Maven repository - a release's assets, say, and the list of what was published that a privately hosted Maven repository keeps:

maven[build.jenesis].latest=https://maven-repository.example.com/releases/{groupPath}/{artifactId}/maven-metadata.xml

A link ending in /maven-metadata.xml is downloaded rather than sent a HEAD request. Its release, among the versions the key serves, is the newest version, and the template answers the file's versions, limited to those it serves, as its metadata - so a version range sees them too.

Reading the files with Jenesis

Jenesis reads the files where jenesis.repository.discovery is set, on the command line or in jenesis.properties. It asks about every Maven group before any configured repository, asks each domain once, however many modules and artifacts it serves, and resolves what no file names as it always has.

What a domain answered - its file, or a 404 or 410 saying it publishes none - is kept in the local module repository, under well-known/ in ~/.jenesis or where jenesis.module.local points, for 24 hours, so the builds of that day ask it nothing. Where jenesis.module.local is empty, the answers are kept in the project's .jenesis/artifacts instead. jenesis.discovery.ttl sets the hours, and 0 keeps nothing. Only the command line or your own ~/.jenesis/jenesis.properties may set it. No setting asks a domain again sooner: delete well-known/ for that. A build with jenesis.repository.offline=true asks no domain and reads what is kept, however old.

A domain is asked once, without the retries a repository is given, and has five seconds to connect and to answer each read, which jenesis.discovery.timeout sets in milliseconds. A file that cannot be fetched counts as absent: a host that does not exist, one a proxy cannot reach, one that does not answer in time, or one that resets or refuses the TLS handshake. Such a failure is not kept, since the domain may answer the next build. A certificate that does not verify, or that names another host, fails the build instead.

To rely on the files alone, empty the repositories beside them, so that nothing falls back:

jenesis.repository.discovery=true
jenesis.maven.uri=
jenesis.module.uri=

A location over plain http is followed only where jenesis.repository.insecure allows it.

From modules to Maven artifacts

A module that is published as a Maven artifact is mapped to it by the moduletomaven key, whose value is a Maven coordinate, <groupId>:<artifactId>[:<extension>[:<classifier>]], without its version:

moduletomaven=build.jenesis:{module}

{module} is the module's name, so this one line maps every module below jenesis.build to the artifact of the same name in the group build.jenesis. The artifact then resolves as any Maven dependency does - through the maven key of the previous chapter and the usual Maven repositories - and a request without a version takes the newest release its Maven metadata names. A domain that publishes both keys needs no entry in a module index.

Where artifact names follow another pattern, {-suffix} follows it. It is the part of the module's name below the file's domain, its labels joined by dashes after a leading one: nothing for net.bytebuddy, -agent for net.bytebuddy.agent. One line maps every Byte Buddy module:

moduletomaven=net.bytebuddy:byte-buddy{-suffix}

A module whose suffix names no artifact, such as net.bytebuddy.utility, finds nothing and resolves as if the file did not name it. A coordinate without placeholders belongs to one module only - the one whose own domain publishes the file - unless its key selects a module. An artifact that follows no pattern is then named for its module in the same file:

moduletomaven[com.example.legacy]=com.example:example-classic

A build that resolves modules through Maven, reading their POMs, asks moduletomaven first. In Jenesis that is the modular_to_maven layout, the one a module-info.java gets by default.

Pure module repositories

A module that is not published to Maven, or a build that resolves modules on the module path alone, uses the module key. Its value is a location, in the same two forms:

  • A template names each module file. {module}, {-suffix}, {version}, {-classifier} and {type} are filled in, and files are checked against their checksums as for Maven.
  • A root is a Jenesis module service, such as https://repo.jenesis.build/, asked as a configured module repository is.
module[build.jenesis]=https://github.com/jenesis/jenesis/releases/download/v{version}/{module}-{version}{-classifier}.{type}
module[build.jenesis].latest=https://github.com/jenesis/jenesis/releases/latest/download/{module}.jar
module[build.jenesis].suffixes=none

A build that resolves a module from its jar and the requires of its module-info asks module first - in Jenesis, the modular layout - and so downloads build.jenesis-<version>.jar with no POM and no Maven at all. module.latest names the newest version for a requires that no pin names. A Jenesis module service may serve as the latest link too, https://repo.jenesis.build/module/{module}/{module}.jar: it names the version in a Jenesis-ModuleVersion header, which is read before the redirect.

A key that does not answer leaves the request to the other, so a domain that publishes both module and moduletomaven serves either kind of build.

The sources of a release

A release's sources belong to it as much as its jar does, so the file names them too. Maven Central asks for a sources jar beside every artifact; here, the domain names an archive of the sources of each version instead, typically the one a code host keeps of every tag, as GitHub keeps an archive of every release:

sources[build.jenesis]=https://github.com/jenesis/jenesis/archive/refs/tags/v{version}.zip

sources is a template that names {version}, and it takes the placeholders of maven for a Maven dependency and those of module for a module. It is selected like the other keys, so a domain with several projects names the archive of each, and .since and .suffixes limit the versions it answers for. Jenesis lists the archive in the CycloneDX SBOM of a build, as the source-distribution reference of each dependency the file answers for, so whoever reads the SBOM finds the code each jar was built from.

Publishing everything a build may ask for

One release can serve every kind of build at once: the module path, a module resolved through Maven, and a Maven dependency, each with its signatures and checksums. Jenesis does so itself. Its release stages a Maven repository, and JReleaser attaches the jar and the POM to the GitHub release. JReleaser signs every file it attaches, and checksum.individual has it upload a .sha256 beside each, as in this excerpt of Jenesis's own jreleaser.yml:

signing:
  active: ALWAYS
  pgp:
    armored: true
    mode: MEMORY

release:
  github:
    owner: jenesis
    name: jenesis
    tagName: 'v'

checksum:
  individual: true

files:
  artifacts:
    - path: 'target/stage/maven/output/build/jenesis/build.jenesis//build.jenesis-.jar'
    - path: 'target/stage/maven/output/build/jenesis/build.jenesis//build.jenesis-.pom'

Every release then holds build.jenesis-<version>.jar and .pom, each with an .asc and a .sha256, and one file at https://jenesis.build/.well-known/java-repository.properties points every kind of request at them:

module[build.jenesis]=https://github.com/jenesis/jenesis/releases/download/v{version}/{module}-{version}{-classifier}.{type}
module[build.jenesis].latest=https://github.com/jenesis/jenesis/releases/latest/download/{module}.jar
module[build.jenesis].suffixes=none
moduletomaven=build.jenesis:{module}
maven[build.jenesis]=https://github.com/jenesis/jenesis/releases/download/v{version}/{artifactId}-{version}{-classifier}.{type}
maven[build.jenesis].latest=https://github.com/jenesis/jenesis/releases/latest/download/{artifactId}.pom
maven[build.jenesis].suffixes=none
A build asks for Answered by Downloads
requires build.jenesis on the module path module build.jenesis-<version>.jar
requires build.jenesis, resolved through Maven moduletomaven, then maven build.jenesis-<version>.pom, then the jar
the Maven dependency build.jenesis:build.jenesis:<version> maven the POM, then the jar
a signature module or maven .jar.asc, .pom.asc
a checksum, to check each download the same template .jar.sha256, .pom.sha256
its sources sources nothing: the archive GitHub keeps of the release's tag
the newest version module.latest, maven.latest nothing: a HEAD request that GitHub redirects

The same file holds such keys for the launcher, the crawler and Jenesis Repository, which are released from repositories of their own, as Several projects under one domain shows.

The module template names files by module name, which works because Jenesis's artifact ID is its module name. Where the two differ, name the files the way the artifacts are named instead, with {-suffix} - .../byte-buddy{-suffix}-{version}{-classifier}.{type} - or publish moduletomaven alone.

Attaching the files to earlier releases

A release made before its POM was attached leaves that POM to the usual repositories, if the build has any. github-backfill.sh attaches what such releases lack, for any project on GitHub whose artifacts a Maven repository holds. It needs gh, signed in to an account that may edit the releases, curl, sha1sum and sha256sum:

./github-backfill.sh --repository=jenesis/jenesis --artifact=build.jenesis:build.jenesis
./github-backfill.sh --repository=jenesis/jenesis --artifact=build.jenesis:build.jenesis --apply

For every release whose tag matches --tag (v{version} by default), or for the versions named, it downloads the jar and the POM of each --artifact with their .asc signatures, checks each against its .sha1, and attaches them with a .sha256. The first command only lists what it would upload; --apply uploads it. A file already on a release must be identical to the repository's copy, and a signature is copied, never made. The repositories are read from MAVEN_REPOSITORY_URI as Jenesis reads it, or from --maven, so the files can come from a mirror such as Google's.

--sources and --javadoc add those jars, but neither is needed, and the releases of the Jenesis tools attach neither. Sources and javadoc are not really repository artifacts: GitHub already publishes the source code of every release as an archive, and javadoc jars seem rather outdated - Central accepts placeholders for both, and Jenesis can stage an intentionally empty one.

Implementing a client

This chapter is for the authors of tools that read the file.

The grammar

The file is read as java.util.Properties reads one, with # comments and \ continuations, in UTF-8. Of a key named twice the last value counts, and a key a reader does not know is ignored, so the format can grow:

file          = *( entry / delegate )
entry         = key "=" value
delegate      = "delegate=" ( "true" / "false" )     ; false, the default: no subdomain is read
key           = kind [ "[" selector "]" ] [ ".since" / ".suffixes" / ".latest" ]
kind          = "module" / "moduletomaven" / "maven" / "sources"
selector      = 1*( ALPHA / DIGIT / "_" / "." / "-" ) [ "*" ] ; an artifact ID for maven, a module name
                                                     ; otherwise, or the start of one before "*"
module        = location
moduletomaven = coordinate
maven         = location
sources       = location                             ; a template naming {version}
latest        = https-uri                            ; beside a template naming {version}: a redirecting
                                                     ; link, or one ending in "/maven-metadata.xml"
coordinate    = groupId ":" artifactId [ ":" extension [ ":" classifier ] ]
location      = https-uri                            ; names "://": a root, or a template with placeholders
placeholder   = "{" ( "groupId" / "groupPath" / "artifactId" / "module" / "-suffix"
                    / "version" / "-classifier" / "type" ) "}"
since         = version
suffixes      = suffix *( "," suffix )
suffix        = 1*( ALPHA / DIGIT )                  ; "none" names a version without one
Placeholder maven module moduletomaven sources
{groupId}, {groupPath}, {artifactId} yes for a Maven dependency
{module}, {-suffix} yes yes for a module
{version} yes yes yes
{-classifier}, {type} yes yes

Finding a key

To find a key for a module name, or for a group ID and an artifact ID:

  1. Skip a name that cannot be a domain: one label, or a label with anything but letters, digits, _ and -.
  2. Reverse the labels into domains, shortest first, from two labels to all of them: net.bytebuddy.agent gives bytebuddy.net, then agent.bytebuddy.net.
  3. Fetch each domain's file once per run, remembering an absent file as well as a present one. A file that cannot be fetched - a 404, an unknown host, a proxy that cannot reach it, a TLS handshake that is reset or refused - is absent. A tool may keep what a domain answered for longer than a run.
  4. Skip a domain without a file. In a file, take the key that selects the module name or artifact ID exactly, else the one whose selector is the longest prefix of it, else the key for all. That key becomes the answer, unless it is the key for all, its value a coordinate without placeholders, and the domain shorter than the name's own.
  5. Stop after the first file found, unless it says delegate=true; the last answer found counts.

Answering a request

  1. Choose the keys: maven for a Maven request; for a module, module then moduletomaven on the module path, or the other way round when resolving through Maven.
  2. For a request without a version against a template, read its latest link. A link ending in /maven-metadata.xml is downloaded, and its release among the versions the key serves is the version; a Maven metadata request is answered with its versions, limited the same way. Any other link is sent a HEAD request without following redirects: a 404 names no version, and otherwise take the Jenesis-ModuleVersion or Jenesis-MavenVersion header, or match the Location against the template up to the end of the path segment holding {version}.
  3. Check the version against .since and .suffixes; a request still without a version passes over a key that restricts versions.
  4. Resolve: expand a coordinate and resolve it as a Maven artifact; ask a root as a repository, listing only the versions the key serves; fill in a template, download the file, and check it against the strongest checksum beside it.
  5. Check the name a module's jar declares, in its module-info or as its Automatic-Module-Name, against the module name that was asked for, whichever key answered.
  6. Where a key does not answer, try the next one, then the configured repositories.

Failing and trusting

A tool fails, naming the file, on a key without a value, a selector that is no name or prefix, a suffix that is not a word, a delegate that is neither true nor false, an unknown placeholder, a coordinate that names no artifact, a coordinate in module or a location in moduletomaven, a sources that is no template naming {version}, a latest link beside a root, a coordinate or a template without {version}, a latest link that leads elsewhere or names no version, and a module jar that declares another name than the one asked for, or none.

Every location is read over https once its placeholders are filled in, and a redirect is followed only to http or https, so no file can make a tool read a local file: or jar: URI. A certificate that does not verify, or that names another host, fails the build. A domain answers only for names below it, and checking the name a downloaded module declares keeps it from answering for one of them with another module, which a coordinate in moduletomaven could otherwise name. The file only says where a file comes from: a pinned checksum or a declared signature still decides what is accepted. A domain that changes hands passes its file to the new owner, so for every version a build pinned, the new owner can break the build but never change what it accepts; a version the build did not pin is only as trustworthy as the domain's owner, unless a declared signature names who must have produced it.