Sorry for the late reply. I guess I'm not sure what your proposal is. You are suggesting we go with the Java annotation-based approach and generate the OpenAPI yaml from the Java code, right? That's the code-first (or bottom-up) approach.
I get the awkwardness of the spec-first approach, but IMO, it's less awkward than having to reconcile two specs after the fact, which is what we'd have to do in the bottom-up approach to ensure compliance with the Iceberg spec. Yes, we have to run the tests anyway to ensure behavior is correct, but runtime testing is both slower than compile-time checking and also, IME, doesn't drive the actual development process like interface changes do. E.g., optional parameters can simply be ignored during the integration tests, whereas they actually cause someone to make a conscious choice about handling them when the interface definition changes. One of the alternative tools that validates spec compliance seems like it would fill the gap, as Alex says, but TBH, I don't see the point. I guess I just don't feel as awkward with the spec-first approach. As I mentioned, I'm not tied to any particular tool for the code generation, so if there is an alternative that is less verbose or solve some particular problem better, I'd be open to hear it, but as for abandoning the code generation entirely, I feel there would need to be a strong technical reason to go that route more than just "general awkwardness". Mike On Tue, Feb 17, 2026 at 11:11 AM Dmitri Bourlatchkov <[email protected]> wrote: > Hi Michael, > > I actually side with your sentiment about the spec-first approach, but let > me clarify my concern here. > > Specs should certainly be developed before implementation is finalized. > > However, automating server-side code generation from the OpenAPI yaml has > some technical awkwardness (as I described in my fist email on this > thread). > > The alternative I'm proposing here is to avoid the intermediate stub > generation step and code endpoint implementation to match the existing > Iceberg REST API spec by leverating annotations and support from the > framework (Quarkus). > > I believe this approach provides more flexibility on the implementation > side and the amount of hand-written code is roughly the same whether we use > generated stubs or not. > > Compliance with the Iceberg spec is to be validated by running TCK / > Integration tests in CI. The integration tests could still use Iceberg > OpenAPI yaml for generating clients in whatever language is convenient for > them. Compliance tests are required even with generated server stubs, > because we cannot be completely sure the generated code is correct. > > Using different / more advanced tooling for server stub generation is going > to require more effort than manually adjusting java annotations to match > Iceberg spec changes. My assessment of this is grounded in the fact that > current hand-written code in Polaris has to adjust to spec changes in any > case. Any behaviour changes will require a thought process to adjust > server-side implementations, this part is hardly automatable in the current > Polaris build framework. > > When we're talking about Polaris' own APIs (Management, Generic Tables) we > could generate the Open API yaml from the endpoint annotations, as Robert > suggested. With this approach we can still review and settle on the spec > before implementation is plugged in. The only conceptual difference is that > the "source" for the spec will be code annotations (java) rather than > OpenAPI yaml. > > That said, we can probably consider moving the spec "source" to java > annotations as stage two, if the community is fine with removing generated > server stubs in general. > > WDYT? > > Thanks, > Dmitri. > > On Sat, Feb 14, 2026 at 1:25 PM Michael Collado <[email protected]> > wrote: > > > While I’m not particular about the tools, I’m pretty strongly in favor of > > the spec first approach. While the management APIs have the freedom to be > > code-first, the Iceberg catalog APIs are subject to a spec outside of our > > control. Adding in tools later to ensure compatibility feels > unnecessarily > > complex and just adds another thing we have to know about and maintain. > I’d > > be in favor of evaluating simpler, less verbose generators. > > > > Mike > > > > On Fri, Feb 13, 2026 at 2:25 PM Romain Manni-Bucau < > [email protected]> > > wrote: > > > > > What about moving to JSON-B? 🤔 > > > I know it can look like it misses fun feature but there is no technical > > > reason you don't manage to do all you want with it. > > > Will be more consistent with microprofile and more future friendly IMHO > > for > > > the project. > > > > > > Romain Manni-Bucau > > > @rmannibucau <https://x.com/rmannibucau> | .NET Blog > > > <https://dotnetbirdie.github.io/> | Blog < > https://rmannibucau.github.io/ > > > > > > | Old > > > Blog <http://rmannibucau.wordpress.com> | Github > > > <https://github.com/rmannibucau> | LinkedIn > > > <https://www.linkedin.com/in/rmannibucau> | Book > > > < > > > > > > https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064 > > > > > > > Javaccino founder (Java/.NET service - contact via linkedin) > > > > > > > > > Le ven. 13 févr. 2026 à 16:03, Alexandre Dutra <[email protected]> a > > > écrit : > > > > > > > Hi Robert, > > > > > > > > Good point about Jackson 3, I agree that we should migrate ahead of > > > > Quarkus if possible, and that a code-first approach would make things > > > > easier. > > > > > > > > That said, it seems that support for Jackson 3 is now deferred to > > Quarkus > > > > 4 [1]. > > > > > > > > Thanks, > > > > Alex > > > > > > > > [1]: https://github.com/quarkusio/quarkus/issues/52036 > > > > > > > > On Fri, Feb 13, 2026 at 3:18 PM Robert Stupp <[email protected]> wrote: > > > > > > > > > > Another aspect, although strictly speaking unrelated, is Jackson 3. > > All > > > > > custom Jackson 2 serializers are incompatible with Jackson 3, and > > some > > > > > annotations are different. It is possible to use both Jackson 2 + 3 > > > > > annotations in the "code first" approach, and it works fine with > > > > Immutables. > > > > > > > > > > I'd expect Jackson 3 to become a necessity in the near future. For > > > > Quarkus, > > > > > it was already on the list of ideas for 3.31, but thankfully moved > > out. > > > > > A "code first" approach would save us that headache in the JAX-RS > > > > context. > > > > > > > > > > Side note: it's possible to use both Jackson 2 and Jackson 3 in the > > > same > > > > > code base - they can work side by side. > > > > > > > > > > > > > > > On Fri, Feb 13, 2026 at 3:00 PM Jean-Baptiste Onofré < > > [email protected]> > > > > > wrote: > > > > > > > > > > > Hi Dmitri, > > > > > > > > > > > > Thanks for starting this discussion. > > > > > > > > > > > > While I have a preference for the code-first approach, I wonder > if > > we > > > > can > > > > > > easily support the Iceberg REST Spec using this method. I would > > like > > > > to use > > > > > > JaxRS annotations, but it might be tricky to cleanly leverage the > > > > Iceberg > > > > > > REST Spec. > > > > > > > > > > > > Just my $0.01 > > > > > > > > > > > > Regards, > > > > > > JB > > > > > > > > > > > > On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov < > > > [email protected]> > > > > > > wrote: > > > > > > > > > > > > > Hi All, > > > > > > > > > > > > > > I believe OpenAPI (REST) interface definitions that Polaris > > > provides > > > > are > > > > > > > very useful for end users and machine clients. > > > > > > > > > > > > > > However, I see that server-side code generation leads to > > > duplication > > > > > > > between generated code and hand-written code. For example, > > > > > > > `PolarisCatalogsApi` is generated, but most of the method > > > signatures > > > > in > > > > > > > `PolarisServiceImpl` have to be written by hand to match the > > > > generated > > > > > > > code. > > > > > > > > > > > > > > I wonder what people think about using direct hand-written > > service > > > > > > classes > > > > > > > to connect to REST endpoints via Rs-Api (Jakarta) annotations? > > > > > > > > > > > > > > I can see that generating service stubs might appear helpful to > > > > ensure > > > > > > that > > > > > > > all API endpoints have code that matches OpenAPI specs. > However, > > we > > > > have > > > > > > to > > > > > > > make tests to verify correct behaviour anyway. Those tests > could > > be > > > > made > > > > > > > with a generated client and will automatically ensure correct > > > > > > hand-written > > > > > > > code assuming coverage is good. > > > > > > > > > > > > > > WDYT? > > > > > > > > > > > > > > Thanks, > > > > > > > Dmitri. > > > > > > > > > > > > > > > > > > > > > > >
