Discovery (proposal)
jenesis.repository.discovery is set.
A Maven group ID or a Java module name are typically reversed domain names: net. belongs to
bytebuddy., for example.
This proposal lets whoever owns that domain say, in one small file on its website,
https:/, 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.
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
requiresfrom 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:/, 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. says that the artifact build. is attached to the GitHub releases of
Jenesis, and that those releases hold no snapshots. A dependency on build. then
downloads https:/. A key without
brackets, maven=, serves every artifact of every group below the domain.
Which file answers
For net., a tool reads the file of bytebuddy. - the two labels a vendor owns - and the
file of agent. only where bytebuddy. 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=:
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.
serves the build tool, the launcher, the crawler and the modules of Jenesis Repository, all in the group
build., 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. does for the modules of
Jenesis Repository, all named build.. 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.is merged with that of the usual repositories, so a version range sees the versions of both -xml 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 .orsha256 .beside it, the strongest one present, and a mismatch fails the build.sha1
A Maven template fills in {groupId} (net.), {groupPath} (net/), {artifactId},
{version}, {-classifier} (-sources, or nothing for the plain jar) and {type} (jar, pom, jar.,
jar.). 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>.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:since= <version> 1.comes before2. 3-rc. 1 1.,2. 3 1.after it.10. 0 <key>.lists the qualifiers it serves - the part of a version after its first dash, matched by its leading word, ignoring case.suffixes= <suffix>[,<suffix>. . . ] nonenames a version without one; without the key, every version is served.
With maven. and maven., 1. is served, while 1. and everything
before 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>.. 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/ to releases/ 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., 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 / 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. is set, on the command line or in
jenesis.. 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 ~/ or where jenesis. points, for 24 hours, so the
builds of that day ask it nothing. Where jenesis. is empty, the answers are kept in the project's
. instead. jenesis. sets the hours, and 0 keeps nothing. Only
the command line or your own ~/ may set it. No setting asks a domain again sooner:
delete well-known/ for that. A build with jenesis. 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. 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. 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. to the artifact of the
same name in the group build.. 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., -agent for
net.. One line maps every Byte Buddy module:
moduletomaven=net.bytebuddy:byte-buddy{-suffix}
A module whose suffix names no artifact, such as net., 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_ layout, the one a module-info. 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:/, asked as a configured module repository is./ repo. jenesis. build/
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. with no POM and no Maven at all.
module. names the newest version for a requires that no pin names. A Jenesis module service may serve
as the latest link too, https:/: 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 . and . 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.
has it upload a . beside each, as in this excerpt of Jenesis's own
jreleaser.:
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. and ., each with an . and a ., and one file at
https:/ 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. on the module path |
module |
build. |
requires build., resolved through Maven |
moduletomaven, then maven |
build., then the jar |
the Maven dependency build. |
maven |
the POM, then the jar |
| a signature | module or maven |
., . |
| a checksum, to check each download | the same template | ., . |
| its sources | sources |
nothing: the archive GitHub keeps of the release's tag |
| the newest version | module., maven. |
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} -
. - 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. 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 . signatures, checks each against its ., and attaches
them with a .. 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_ 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. 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:
- Skip a name that cannot be a domain: one label, or a label with anything but letters, digits,
_and-. - Reverse the labels into domains, shortest first, from two labels to all of them:
net.givesbytebuddy. agent bytebuddy., thennet agent..bytebuddy. net - 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. - 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.
- Stop after the first file found, unless it says
delegate=; the last answer found counts.true
Answering a request
- Choose the keys:
mavenfor a Maven request; for a module,modulethenmoduletomavenon the module path, or the other way round when resolving through Maven. - For a request without a version against a template, read its latest link. A link ending in
/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 amaven-metadata. xml HEADrequest without following redirects: a404names no version, and otherwise take theJenesis-ModuleVersionorJenesis-MavenVersionheader, or match theLocationagainst the template up to the end of the path segment holding{version}. - Check the version against
.andsince .; a request still without a version passes over a key that restricts versions.suffixes - 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.
- Check the name a module's jar declares, in its
module-infoor as itsAutomatic-Module-Name, against the module name that was asked for, whichever key answered. - 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.