I think our current stance on generators is that we're agnostic. I would prefer not making changes to the spec for generators because I think they are of limited use. Plus, I don't want to get to a place where we worry about changes causing downstream code to fail, as could be the case here if a generator produces a different UUID class in new cases. I'd probably leave this as-is, but I'm not strongly opposed to it.
On Wed, Jan 21, 2026 at 10:05 AM Alex Stephen <[email protected]> wrote: > Yeah, I was viewing this solely through the lens of OpenAPI generators > (and potentially LLMs reading the spec). > > The Java client generator would begin treating those fields as > Java.util.uuid rather than strings. > > On Wed, Jan 21, 2026 at 10:00 AM Ryan Blue <[email protected]> wrote: > >> What would this change do? >> >> The underlying type is still string in both cases, but the >> `UUIDTypeValue` has `format: uuid` and validations (a regex and length >> requirements). It doesn't seem like this would cause any trouble in the >> spec and we expect those validations to be true for all existing uses. If >> this doesn't have any effect, then why change it? I don't think >> documentation is a problem because we haven't had any confusion about these >> fields. So is this just about generated clients running validations? >> >> On Tue, Jan 20, 2026 at 3:00 PM Alex Stephen via dev < >> [email protected]> wrote: >> >>> Hi all, >>> >>> https://github.com/apache/iceberg/pull/15095 >>> >>> We treat UUIDs inconsistently in the REST Catalog Spec. Some fields are >>> simple strings and others are a complex UUIDTypeValue with client-side >>> validations and strong descriptions. I'd like to change the spec so that >>> all UUID fields are treated as UUIDs instead of strings. >>> >>> The additional context is critically important to tools in the OpenAPI >>> ecosystem (documentation + client library generators) that can't make >>> assumptions based on the field name. >>> >>> This is not a breaking change, since these fields were always treated as >>> UUIDs server-side. The change is to make the spec reflect that reality. >>> >>> Please let me know your thoughts. >>> >>> Thank you! >>> >>> -- Alex Stephen >>> >>
