Proposal: Retain the namespaces org.eclipse.microprofile.* for the existing MicroProfile specifications when MicroProfile joins Jakarta EE

[Emily Jiang]

As promised, here is the proposal I put together with some input from my IBM colleagues. I plan to start a ballot in the Jakarta EE platform dev mailinglist next week.

Context
The merger of MicroProfile specifications into Jakarta EE represents a joint community for the Java enterprise ecosystem. However, for this merger to be successful, it is imperative that the org.eclipse.microprofile namespace and artifact names (e.g., microprofile-config) be preserved for all APIs and specifications originating from the MicroProfile community.

This is a strategic necessity to protect the vast existing global investment, ensure backward compatibility, and prevent ecosystem fragmentation. Changing the namespace to jakarta would cause the existing implementers and their customers pain and confusion while negating the very benefits this merger seeks to achieve.

The proposal

Resolved: Retain the namespaces org.eclipse.microprofile.* for the existing MicroProfile specifications when MicroProfile joins Jakarta EE

The basis for this position rests on several pillars: technical, economic, governance, and strategic.

1. Technical Basis: The Unbreakable Contract of Backward Compatibility

· The Maven Coordinate as a Universal Identifier: In modern Java development, a Maven groupId:artifactId (e.g., org.eclipse.microprofile:microprofile-config-api) is a unique, immutable contract. Build tools (Maven, Gradle), CI/CD pipelines, registries (Maven Central, Nexus), and IDEs all rely on this coordinate never changing for a given version of a library.
· Impact: Changing the namespace to jakarta (e.g., jakarta.microprofile.config:config-api) creates a new, incompatible artifact. Every existing application, every line of code import org.eclipse.microprofile.config.*;, and every pom.xml or build.gradle file would require mandatory, invasive changes to migrate. This is not an upgrade; it is a forced, costly, and error-prone rewrite for many production microservices.
· The Jakarta EE Precedent: Jakarta EE itself faced this exact challenge when moving from javax.* to jakarta.*. See the example below for the pain and complexity of this namespace change. It would be regrettable to inflict this same pain on the MicroProfile community.

Example: with the javax-to-jakarta package name switch where customers write application code using only the class name, like @Resource and save, after which the IDE auto-computes the import statements.  The developer spends time and effort trying to figure out why their annotation isn't honored, even going so far as to open support cases, which our support teams spend time and effort trying to debug, before someone eventually figures out that wrong package name is used.  We expect more of the same if microprofile classes are duplicated into jakarta packages, whereas this added cost of development and source of frustration to our users is completely avoided if the package names are left alone. 

2. Economic Basis: Protecting Global Investment

· The Cost of Change for customers: The man-hours required for every development team to replace, test, and redeploy all their services could represent a considerable amount of cost and time. Preserving the namespace protects this global investment, allowing for a seamless transition where new Jakarta EE versions can simply include and enhance the stable MicroProfile artifacts.

· The Cost of Change for implementers: Resources are finite. Time spent by implementers to adapt to the namespace change and helping their users do so means resources not spent on driving the Jakarta / MicroProfile ecosystem forward.

3. Strategic Basis: Unification, Not Absorption

· The Goal is a Bigger Tent: Joining MicroProfile with Jakarta EE provides a more complete programming model for both monolith and microservices architecture.
· The Ecosystem Fragmentation: If the namespace is changed, it will inevitably fragment the community. Some vendors and projects would adopt the new jakarta.microprofile.* artifacts, while others, prioritizing their users' stability, might continue to ship and innovate on the org.eclipse.microprofile.* artifacts. We would end up with two competing sets of identical APIs, undermining the unity this effort is meant to create.

Conclusion and the Path Forward

Considering the advantages and disadvantages of preserving vs. altering the namespace, the most beneficial path is to preserve the microprofile namespace under Jakarta EE. The correct path is to:

• Formalize the Merge in the Jakarta EE Platform.

• Preserve the `org.eclipse.microprofile` Namespace: Keep the existing package names and Maven coordinates.

• Let Runtimes Do the Work: Jakarta EE runtimes will simply bundle the existing MicroProfile JARs, providing a unified platform out-of-the-box.

This approach achieves the ultimate goal—a unified, full-featured platform for enterprise Java—without breaking existing code, and respecting the unique identity and innovation pipeline of the MicroProfile community. The namespace must be preserved.

--

Thanks
Emily

[Ondro Mihályi]

Hello, Emily,

Thank for this proposal, and for including detailed reasoninh in it. For the case of maven artifacts, did you consider aliasing of artifacts which is supported by Maven Central? Even if an artifact is renamed, with this approach, it’s possible to use old artifact coordinates with new versions, and Maven automatically pulls artifacts that have the new coordinates.

Ondro

_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-p...@eclipse.org
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev

[Arjan Tijms]

Hi all,

I'd like to take a moment to emphasize that namespace uniformity defines the platform’s integrity. It’s part of the shared mental model that makes Jakarta EE a platform rather than a collection of unrelated jars.

The current proposal focuses narrowly on short-term migration pain, while I believe we should look at the long-term architectural and cultural cost of fragmentation.
A platform with mixed namespaces is not a coherent API surface. It perpetuates legacy boundaries indefinitely and signals to both developers and vendors that “Jakarta EE is not one thing.” That undermines confidence in the platform’s long-term stewardship.

Let’s not forget that the “we can’t break existing users” argument has been made at every namespace transition since JDK 1.1, from javasoft.* -> javax.* -> jakarta.*.
Time and again, history has shown that each painful break was eventually the right call: it enabled clarity, consolidation, and modernization. To that effect, the goal should be to honor MicroProfile’s contribution by making it a first-class citizen in Jakarta EE, not by isolating it behind a legacy namespace. We want its innovations to live within Jakarta EE’s architecture, not beside it.


We’ve just spent years unifying everything under jakarta.* for consistency and clarity. Re-introducing another external namespace now would re-create the very fragmentation we worked so hard to fix.
Of course, we can and should protect users through transitional compatibility artifacts, but the direction must be clear: the unified platform is Jakarta EE, not a federation of legacy namespaces.


Imagine if the Jakarta platform in 2030 consisted of jakarta.enterprise, org.eclipse.microprofile, com.sun.enterprise, com.oracle, and say org.omnifaces. The platform would no longer feel cohesive. A unified namespace is part of what makes a platform a platform.

Let’s design a path that welcomes MicroProfile’s APIs into the jakarta.* namespace while giving developers time to adapt; just as Jakarta EE itself did successfully.
That’s how we build one unified platform that honors both histories.


My 2 cents,
Arjan Tijms

On Mon, 13 Oct 2025 at 17:58, Lenny Primak via jakartaee-platform-dev <jakartaee-p...@eclipse.org> wrote:

I was thinking this was the case as well, but was not sure. Thanks for confirming Joakim.

I created an issue in Maven: https://github.com/apache/maven/issues/11255

On Oct 13, 2025, at 11:50 AM, Joakim Erdfelt via jakartaee-platform-dev <jakartaee-p...@eclipse.org> wrote:



Ondro, 

What you are referring to is the `<relocation>` element in the Maven Pom.

https://maven.apache.org/pom.html#Relocation

It would exist in old maven coordinates, pointing to the new maven coordinates.

Thing is, this relocation is version specific, it doesn't apply to all versions (now and in the future).

- Joakim

On Mon, Oct 13, 2025 at 10:20 AM Ondro Mihályi via jakartaee-platform-dev <jakartaee-p...@eclipse.org> wrote:

Hello, Emily,

Thank for this proposal, and for including detailed reasoninh in it. For the case of maven artifacts, did you consider aliasing of artifacts which is supported by Maven Central? Even if an artifact is renamed, with this approach, it’s possible to use old artifact coordinates with new versions, and Maven automatically pulls artifacts that have the new coordinates.

Ondro

_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-p...@eclipse.org
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev

[Emily Jiang]

Arjan,

Unfortunately, what you said is applicable to something new but not the existing specs without business interruptions. There was no business need to unify the namespaces. Besides, developers do not type in the package names. These are resolved automatically. With the namespace changes, the automatic resolve on longer works, which is even worse.

Thanks

Emily

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/microprofile/CAGZXXAJqWFFDiJZ35HCnSmKeJAQEP997xo82aGm%2BeuAyaWaymw%40mail.gmail.com.

--

Thanks
Emily

[Arjan Tijms]

Hi,

On Tue, 14 Oct 2025 at 16:34, 'Emily Jiang' via MicroProfile <microp...@googlegroups.com> wrote:

Arjan,

Unfortunately, what you said is applicable to something new but not the existing specs without business interruptions. There was no business need to unify the namespaces.

I think mixed namespaces create long-term maintenance debt and vendor divergence; each implementation must maintain separate integration points indefinitely. That increases cost and risk for customers.

 

Besides, developers do not type in the package names. These are resolved automatically. With the namespace changes, the automatic resolve on longer works,

Exactly, we already saw how that confusion arose during the javax -> jakarta transition. Let’s not set ourselves up to repeat that confusion between Jakarta and MicroProfile. A unified namespace prevents future auto-resolve conflicts and support cases.

Don't get me wrong, I understand the concern about stability and identity. MicroProfile has been successful under its namespace. The goal isn’t to erase that success, but to ensure it’s part of a consistent, stable platform identity for the long term.

Kind regards,

Arjan Tijms

 

To view this discussion visit https://groups.google.com/d/msgid/microprofile/CAECq3A9SO7bxqw-3em0NvmEzTD%3DqXaLanK%2BzR7e%3D%3DeEhARVx_A%40mail.gmail.com.

[Emily Jiang]

Hi Arjan,

Thanks for sharing your thoughts! We have to agree with disagreements which is why I started this proposal and will start a vote soon. 

Thanks

Emily

To view this discussion visit https://groups.google.com/d/msgid/microprofile/CAGZXXAKOrWLRpxyOzZoGGGHkkY_obxGXitq%2BhmzGYWL%2BnK0SoQ%40mail.gmail.com.

--

Thanks
Emily