You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@iceberg.apache.org by Alex Stephen via dev <de...@iceberg.apache.org> on 2026/01/20 22:59:41 UTC
[DISCUSS] Changing UUID types from String to UUID in REST Catalog
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
Re: [DISCUSS] Changing UUID types from String to UUID in REST Catalog
Posted by Ryan Blue <rd...@gmail.com>.
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 <al...@google.com>
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 <rd...@gmail.com> 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 <
>> dev@iceberg.apache.org> 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
>>>
>>
Re: [DISCUSS] Changing UUID types from String to UUID in REST Catalog
Posted by Alex Stephen via dev <de...@iceberg.apache.org>.
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 <rd...@gmail.com> 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 <
> dev@iceberg.apache.org> 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
>>
>
Re: [DISCUSS] Changing UUID types from String to UUID in REST Catalog
Posted by Ryan Blue <rd...@gmail.com>.
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 <de...@iceberg.apache.org>
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
>