Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Kevin Liu]

Thanks for working on this, Andrei. I left a few small comments on the spec
PR, mostly around wording. Please take a look when you get a chance.

I also went back through the earlier discussions and syncs. My read is that
most of the contention is really about how labels might get used, and the
second-order effects of those choices, rather than the spec change itself.
I actually like that the use cases are left unspecified. A vendor could use
labels for governance, for example, but that may also make that
implementation less interoperable with the rest of the ecosystem.

One use case we’ve been thinking about at Microsoft is exposing business
metadata that already exists elsewhere in the Fabric platform. Different
systems can create and manage this context, and it is separate from
Iceberg’s own table metadata in the object store. This is similar to
namespace metadata today, which is also stored and served by the catalog
implementation.

IRC is one of the ways we want to expose this metadata to clients. For
example, we already have our own CRUD APIs for things like table and column
descriptions. Those APIs aren’t part of the IRC spec. They update the
business context stored by the platform.

Being able to return that context through IRC gives clients a standard way
to consume it alongside the table. That could be useful for user-facing
experiences, other tools in the ecosystem, or just giving agents more
context about the data they’re working with. It also lets us expose useful
platform metadata without Iceberg having to define all the ways that
metadata might be used.

TL;DR: I support the proposal. My hope is that as implementations build on
top of labels, we keep interoperability in mind so the broader ecosystem
can benefit from it.

Best,
Kevin Liu

On Wed, Sep 2, 2026 at 12:38 AM Andrei Tserakhau via dev <
dev@iceberg.apache.org> wrote:

> Thanks Prashant!
>
> I think we're actually pretty close on the logging / AI context point.
>
> Agree that statement "meant to be surfaced, logged, joined against" was a
> bit too broad. I don't think the spec should say that labels are always
> safe to log, but I also don't think we should prohibit logging them or
> using them as AI context. This seems ultimately like a client-side decision.
>
> Labels carry a similar kind of context as table / column names and
> descriptions: depending on the catalog and the particular metadata,
> sometimes it is perfectly fine to expose or log them, and sometimes it
> isn't. "config" is somewhat different here because it carries FileIO/client
> configuration and can contain credentials, so we have a much stronger
> reason to treat it as sensitive by default.
>
> I think we tighter this by adding an explicit expectation in the label
> description:
>
> «Clients should treat label contents as opaque unless they understand the
> semantics of a particular label.»
>
> On the structured metadata question / multiple values: I think this is
> exactly where I would prefer not to make the current field more specific.
>
> The current definition already deliberately says that labels are
> catalog-provided metadata and doesn't prescribe how they are produced,
> stored, persisted, or versioned. I don't mind expanding this where there
> are concrete ambiguities, but I'd like to preserve that degree of freedom.
>
> And to clarify what I meant by "designing in a vacuum": I don't mean that
> tags themselves are novel or that there aren't established tag models we
> can learn from. The vacuum I'm concerned about is how this abstraction will
> actually be used through Iceberg REST Catalog.
>
> Tags and catalog metadata are also a major area of differentiation and
> innovation between catalogs. I think we need to be extra careful when
> standardizing a structured entity here: if we define the abstraction too
> tightly before we understand the usage patterns, we may unintentionally
> constrain that innovation space or force catalog-specific models into an
> abstraction that doesn't fit them well.
>
> That's the rationale for starting with the minimal common denominator on
> the read path. Let catalogs expose the metadata they already have without
> requiring Iceberg to standardize its full semantics. Once we see patterns
> of usage across implementations, we'll be in a much better position to
> decide which parts of the tag model are actually common and should be
> standardized, and which parts should deliberately remain vendor-specific.
>
> For example, whether "point of contact" should be one value, multiple
> values, have identity of its own, inheritance semantics, etc. is exactly
> the kind of thing I'd rather learn from real usage before making it part of
> the Iceberg contract. A flat K/V representation doesn't prevent catalogs
> from having richer models behind it, and a structured entity can be added
> later once we have a clearer interoperability boundary to standardize.
>
> So I'd propose adding the client guidance above, keeping the read 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Andrei Tserakhau via dev]

Thanks Prashant!

I think we're actually pretty close on the logging / AI context point.

Agree that statement "meant to be surfaced, logged, joined against" was a
bit too broad. I don't think the spec should say that labels are always
safe to log, but I also don't think we should prohibit logging them or
using them as AI context. This seems ultimately like a client-side decision.

Labels carry a similar kind of context as table / column names and
descriptions: depending on the catalog and the particular metadata,
sometimes it is perfectly fine to expose or log them, and sometimes it
isn't. "config" is somewhat different here because it carries FileIO/client
configuration and can contain credentials, so we have a much stronger
reason to treat it as sensitive by default.

I think we tighter this by adding an explicit expectation in the label
description:

«Clients should treat label contents as opaque unless they understand the
semantics of a particular label.»

On the structured metadata question / multiple values: I think this is
exactly where I would prefer not to make the current field more specific.

The current definition already deliberately says that labels are
catalog-provided metadata and doesn't prescribe how they are produced,
stored, persisted, or versioned. I don't mind expanding this where there
are concrete ambiguities, but I'd like to preserve that degree of freedom.

And to clarify what I meant by "designing in a vacuum": I don't mean that
tags themselves are novel or that there aren't established tag models we
can learn from. The vacuum I'm concerned about is how this abstraction will
actually be used through Iceberg REST Catalog.

Tags and catalog metadata are also a major area of differentiation and
innovation between catalogs. I think we need to be extra careful when
standardizing a structured entity here: if we define the abstraction too
tightly before we understand the usage patterns, we may unintentionally
constrain that innovation space or force catalog-specific models into an
abstraction that doesn't fit them well.

That's the rationale for starting with the minimal common denominator on
the read path. Let catalogs expose the metadata they already have without
requiring Iceberg to standardize its full semantics. Once we see patterns
of usage across implementations, we'll be in a much better position to
decide which parts of the tag model are actually common and should be
standardized, and which parts should deliberately remain vendor-specific.

For example, whether "point of contact" should be one value, multiple
values, have identity of its own, inheritance semantics, etc. is exactly
the kind of thing I'd rather learn from real usage before making it part of
the Iceberg contract. A flat K/V representation doesn't prevent catalogs
from having richer models behind it, and a structured entity can be added
later once we have a clearer interoperability boundary to standardize.

So I'd propose adding the client guidance above, keeping the read path
intentionally minimal, and continuing the structured entity discussion as
the next step.

And thanks for clarifying that this isn't a VOTE blocker <3.

Best,
Andrei

вт, 1 сент. 2026 г., 23:03 Prashant Singh :

> Thanks for the response, Ryan!
>
> > This is needlessly dangerous. Config is used for a different purpose and
> we do not want to mix user-controlled properties into catalog-controlled
> configuration!
>
> I understand that *config* is currently used for catalog-controlled
> configuration. However, looking at the config spec [1], it is essentially a
> bag of K/V pairs with some special defined keys. The spec doesn't
> explicitly state who configures them or exactly what the content must be.
>
> As I understand the current labels proposal, they are also just bags of
> K/V pairs that the catalog tracks, with no attached semantic meaning or
> requirement for the client to act on them. If labels are strictly
> informational K/V pairs, the client can always filter out keys they don't
> want to show from config. I raised this question because I couldn't find
> a prior conclusion on this specific point. We might be approaching this
> from different angles regarding the separation of concerns, but ultimately,
> both approaches result in writing a bag of K/V pairs in the spec that are
> not part of table metadata.
>
> > For instance, we voted to add the function list and load endpoints
> first. What is the rationale for waiting on other endpoints in this case,
> when there are clear use cases for exchanging labels, but the need to
> modify them is considerably less clear?
>
> To clarify my earlier point, I am not asking to hold the spec until
> update/create endpoints are added. My suggestion is to define the
> structured entity first. We did this for the load endpoint for function,
> even before the REST spec, we discussed how function metadata should handle
> overload conflicts, renames, and whether it should be part of a namespace
> or a 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Prashant Singh]

Thanks for the response, Ryan!

> This is needlessly dangerous. Config is used for a different purpose and
we do not want to mix user-controlled properties into catalog-controlled
configuration!

I understand that *config* is currently used for catalog-controlled
configuration. However, looking at the config spec [1], it is essentially a
bag of K/V pairs with some special defined keys. The spec doesn't
explicitly state who configures them or exactly what the content must be.

As I understand the current labels proposal, they are also just bags of K/V
pairs that the catalog tracks, with no attached semantic meaning or
requirement for the client to act on them. If labels are strictly
informational K/V pairs, the client can always filter out keys they don't
want to show from config. I raised this question because I couldn't find a
prior conclusion on this specific point. We might be approaching this from
different angles regarding the separation of concerns, but ultimately, both
approaches result in writing a bag of K/V pairs in the spec that are not
part of table metadata.

> For instance, we voted to add the function list and load endpoints first.
What is the rationale for waiting on other endpoints in this case, when
there are clear use cases for exchanging labels, but the need to modify
them is considerably less clear?

To clarify my earlier point, I am not asking to hold the spec until
update/create endpoints are added. My suggestion is to define the
structured entity first. We did this for the load endpoint for function,
even before the REST spec, we discussed how function metadata should handle
overload conflicts, renames, and whether it should be part of a namespace
or a catalog-level API.My ask is simply that we conclude on what the tags
metadata will look like before closing this out. For example, we should
consider: Can there be multiple values for labels (e.g., multiple points of
contact)? If so, do we use a List or just comma-separated strings ?


Thanks for the response, Andrei!

> while labels are meant to be surfaced, logged, joined against

Since AI context is one of the proposed use cases for labels, ai-summary
field might say, "The table contains data from US / China / Mexico."
Logging this exposes which country's data belongs to the table. Similarly,
logging which columns are sensitive exposes an attack surface. Because of
this, I don't think catalog metadata can always be safely logged; we should
leave it to the client's better judgment to decide what is appropriate to
log.

> designing the entity model before the simple surface exists and has
adoption means designing it in a vacuum

Because TAGs are a well-established industry standard, I respectfully
disagree that we are designing in a vacuum.

*Last question:*

> Are these things you want on record, or are you opposing the addition?

I wanted to have a detailed community discussion on how people plan to use
this and to look at reference implementations for catalog-to-catalog sync.
I am not convinced the current K/V approach is sufficient for governance
use cases, though I agree it works fine for others.

If the question is whether I will veto this proposal during a VOTE, I will
not. I respect the effort you have all put into this. Although my
preference remains to define clear consumption guidelines before
introducing another K/V protocol, if the general consensus is to proceed, I
am happy to let the community vote decide the path forward

[1]
https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml#L3861

Best,

Prashant Singh

On Mon, Aug 31, 2026 at 4:06 PM Ryan Blue  wrote:

> > Why do we even need labels when *config* exists then?
>
> This is needlessly dangerous. Config is used for a different purpose and
> we do not want to mix user-controlled properties into catalog-controlled
> configuration!
>
> > Why not do the structured entity first?
>
> Catalogs already maintain this metadata and there are useful reasons to
> expose it without shoving it into table properties (or config). I like the
> idea of standardizing a way to modify this. But, I see no compelling reason
> to hold back a read-only implementation that can immediately address the
> cases where these are sent through table properties.
>
> We've used similar approaches for other new features. For instance, we
> voted to add the function list and load endpoints first. What is the
> rationale for waiting on other endpoints in this case, when there are clear
> use cases for exchanging labels, but the need to modify them is
> considerably less clear?
>
> Ryan
>
> On Mon, Aug 31, 2026 at 10:01 AM Andrei Tserakhau via dev <
> dev@iceberg.apache.org> wrote:
>
>> Hi Prashant,
>>
>> Thanks for the questions. Let me take them in order.
>>
>> On governance: I hear the concerns, but governance isn't the scope of
>> this proposal, and the proposal doesn't require any particular
>> implementation. Labels are a mechanism to expose catalog metadata; what a
>> 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Ryan Blue]

> Why do we even need labels when *config* exists then?

This is needlessly dangerous. Config is used for a different purpose and we
do not want to mix user-controlled properties into catalog-controlled
configuration!

> Why not do the structured entity first?

Catalogs already maintain this metadata and there are useful reasons to
expose it without shoving it into table properties (or config). I like the
idea of standardizing a way to modify this. But, I see no compelling reason
to hold back a read-only implementation that can immediately address the
cases where these are sent through table properties.

We've used similar approaches for other new features. For instance, we
voted to add the function list and load endpoints first. What is the
rationale for waiting on other endpoints in this case, when there are clear
use cases for exchanging labels, but the need to modify them is
considerably less clear?

Ryan

On Mon, Aug 31, 2026 at 10:01 AM Andrei Tserakhau via dev <
dev@iceberg.apache.org> wrote:

> Hi Prashant,
>
> Thanks for the questions. Let me take them in order.
>
> On governance: I hear the concerns, but governance isn't the scope of this
> proposal, and the proposal doesn't require any particular implementation.
> Labels are a mechanism to expose catalog metadata; what a consumer does
> with it, governance included, is out of scope here. If someone wants to
> propose a formal
> governance spec built on labels for Iceberg, that's the right place to
> work out attachment, inheritance, and cross-system reconciliation. This
> proposal mandates none of it.
>
> On config: IRC already separates k/v by scope rather than using one bag,
> e.g. table properties, namespace properties, the /v1/config endpoint,
> table-level config on load, storage credentials, and remote-signing
> settings. Each is its own carrier because it has its own scope, ownership,
> and lifecycle. Labels are catalog-object metadata, a distinct scope, so
> they follow the same pattern: their own field.
>
> Config specifically is client configuration, not metadata. Most Iceberg
> clients merge the load-table config into the properties used to build the
> session and FileIO, they don't read it as metadata: Java [1][2], Rust [3],
> Go [4]. It also carries secrets (session tokens, s3.secret-access-key) that
> must be hidden from the user, while labels are meant to be surfaced,
> logged, joined against. Opposite exposure requirements, you don't want
> classification metadata and credentials in the same map with the same
> handling. And catalogs already shipping non-standard keys through config is
> the fragmentation this fixes.
>
> On "why not structured first": there are many different tag/label
> implementations across catalogs, each with its own model. The point of the
> read path is to keep that complexity out of the REST spec while still
> letting
> catalogs differentiate above it. The read path is the substrate the
> structured entity projects onto, so it comes first by construction;
> designing the entity model before the simple surface exists and has
> adoption means designing it in a vacuum, and it's a much larger
> cross-vendor effort. Same sequencing IRC already uses, a read surface
> before the write path: functions expose only list and load today, no
> create/update/drop [5]. The structured entity lands additively later, not
> as a change to the read path.
>
> Overall, these read as the same concerns raised in the sync discussions.
> Are these things you want on record, or are you opposing the addition? If
> it's not a blocker, I'd like to move forward with a vote.
>
> Regards,
> Andrei
>
> [1] RESTSessionCatalog: config fed into the table auth session
>
> https://github.com/apache/iceberg/blob/7f7c0023b1faff6162cc864d3819393ce024d66a/core/src/main/java/org/apache/iceberg/rest/RESTSessionCatalog.java#L531-L534
> [2] RESTCatalogProperties: config used for table-level client overrides
> (scan-planning-mode)
>
> https://github.com/apache/iceberg/blob/7f7c0023b1faff6162cc864d3819393ce024d66a/core/src/main/java/org/apache/iceberg/rest/RESTCatalogProperties.java#L50
> [3] iceberg-rust: load-table config chained with client props into
> load_file_io
>
> https://github.com/apache/iceberg-rust/blob/d6d06f3c4a60e5f3a6d3d789a43513a919d9eacb/crates/catalog/rest/src/catalog.rs#L1181-L1187
> [4] iceberg-go: response Config merged into props, then used to build
> FileIO
>
> https://github.com/apache/iceberg-go/blob/e9a0d3bfd5499b1f089d156bfc6bb4b3f9c1b311/catalog/rest/rest.go#L1272
> [5] IRC functions: read-only surface (list + load), no create/update/drop
>
> https://github.com/apache/iceberg/blob/7f7c0023b1faff6162cc864d3819393ce024d66a/open-api/rest-catalog-open-api.yaml#L625-L664
>
> On Mon, Aug 31, 2026 at 4:40 AM Prashant Singh 
> wrote:
>
>> Hi Andrei,
>>
>> Thanks for bringing this back to the dev list and the detailed writeup. I
>> understand the motivating case is catalog-to-catalog / federation.
>>
>> My concerns are mostly when 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Andrei Tserakhau via dev]

Hi Prashant,

Thanks for the questions. Let me take them in order.

On governance: I hear the concerns, but governance isn't the scope of this
proposal, and the proposal doesn't require any particular implementation.
Labels are a mechanism to expose catalog metadata; what a consumer does
with it, governance included, is out of scope here. If someone wants to
propose a formal
governance spec built on labels for Iceberg, that's the right place to work
out attachment, inheritance, and cross-system reconciliation. This proposal
mandates none of it.

On config: IRC already separates k/v by scope rather than using one bag,
e.g. table properties, namespace properties, the /v1/config endpoint,
table-level config on load, storage credentials, and remote-signing
settings. Each is its own carrier because it has its own scope, ownership,
and lifecycle. Labels are catalog-object metadata, a distinct scope, so
they follow the same pattern: their own field.

Config specifically is client configuration, not metadata. Most Iceberg
clients merge the load-table config into the properties used to build the
session and FileIO, they don't read it as metadata: Java [1][2], Rust [3],
Go [4]. It also carries secrets (session tokens, s3.secret-access-key) that
must be hidden from the user, while labels are meant to be surfaced,
logged, joined against. Opposite exposure requirements, you don't want
classification metadata and credentials in the same map with the same
handling. And catalogs already shipping non-standard keys through config is
the fragmentation this fixes.

On "why not structured first": there are many different tag/label
implementations across catalogs, each with its own model. The point of the
read path is to keep that complexity out of the REST spec while still
letting
catalogs differentiate above it. The read path is the substrate the
structured entity projects onto, so it comes first by construction;
designing the entity model before the simple surface exists and has
adoption means designing it in a vacuum, and it's a much larger
cross-vendor effort. Same sequencing IRC already uses, a read surface
before the write path: functions expose only list and load today, no
create/update/drop [5]. The structured entity lands additively later, not
as a change to the read path.

Overall, these read as the same concerns raised in the sync discussions.
Are these things you want on record, or are you opposing the addition? If
it's not a blocker, I'd like to move forward with a vote.

Regards,
Andrei

[1] RESTSessionCatalog: config fed into the table auth session
https://github.com/apache/iceberg/blob/7f7c0023b1faff6162cc864d3819393ce024d66a/core/src/main/java/org/apache/iceberg/rest/RESTSessionCatalog.java#L531-L534
[2] RESTCatalogProperties: config used for table-level client overrides
(scan-planning-mode)
https://github.com/apache/iceberg/blob/7f7c0023b1faff6162cc864d3819393ce024d66a/core/src/main/java/org/apache/iceberg/rest/RESTCatalogProperties.java#L50
[3] iceberg-rust: load-table config chained with client props into
load_file_io
https://github.com/apache/iceberg-rust/blob/d6d06f3c4a60e5f3a6d3d789a43513a919d9eacb/crates/catalog/rest/src/catalog.rs#L1181-L1187
[4] iceberg-go: response Config merged into props, then used to build FileIO
https://github.com/apache/iceberg-go/blob/e9a0d3bfd5499b1f089d156bfc6bb4b3f9c1b311/catalog/rest/rest.go#L1272
[5] IRC functions: read-only surface (list + load), no create/update/drop
https://github.com/apache/iceberg/blob/7f7c0023b1faff6162cc864d3819393ce024d66a/open-api/rest-catalog-open-api.yaml#L625-L664

On Mon, Aug 31, 2026 at 4:40 AM Prashant Singh 
wrote:

> Hi Andrei,
>
> Thanks for bringing this back to the dev list and the detailed writeup. I
> understand the motivating case is catalog-to-catalog / federation.
>
> My concerns are mostly when labels are used for governance. I have
> raised these in the spec PR already linking them as well :
>
> - Attachment / inheritance semantics:
> https://github.com/apache/iceberg/pull/15750#discussion_r3647710626
> - Nested-field label conflicts:
> https://github.com/apache/iceberg/pull/15750#discussion_r3648060761
> - Stable id for cross-catalog sync:
> https://github.com/apache/iceberg/pull/15750#discussion_r3648112804
> In a nutshell, these boil down to:
>
> 1. Why do we even need labels when *config* exists then ?
>
> *LoadTableResult#config* is already a string map that catalogs ship
> non-standard keys through. The use cases listed -
> ownership and point of contact, cost attribution, retention / TTL / GDPR
> cleanup, discovery - can all be carried there today.
>
> 2. Why not do the structured entity first?
>
> "Flat now, structured later" why not do structured entities first then ?
> Federation / Catalog Sync is where I expect it to matter
> most: I cannot tell inherited from direct, and a renamed label leaves me
> nothing stable to bind policy to.
>
> I could be convinced otherwise, but I would rather we work these out here
> than 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Prashant Singh]

Hi Andrei,

Thanks for bringing this back to the dev list and the detailed writeup. I
understand the motivating case is catalog-to-catalog / federation.

My concerns are mostly when labels are used for governance. I have
raised these in the spec PR already linking them as well :

- Attachment / inheritance semantics:
https://github.com/apache/iceberg/pull/15750#discussion_r3647710626
- Nested-field label conflicts:
https://github.com/apache/iceberg/pull/15750#discussion_r3648060761
- Stable id for cross-catalog sync:
https://github.com/apache/iceberg/pull/15750#discussion_r3648112804
In a nutshell, these boil down to:

1. Why do we even need labels when *config* exists then ?

*LoadTableResult#config* is already a string map that catalogs ship
non-standard keys through. The use cases listed -
ownership and point of contact, cost attribution, retention / TTL / GDPR
cleanup, discovery - can all be carried there today.

2. Why not do the structured entity first?

"Flat now, structured later" why not do structured entities first then ?
Federation / Catalog Sync is where I expect it to matter
most: I cannot tell inherited from direct, and a renamed label leaves me
nothing stable to bind policy to.

I could be convinced otherwise, but I would rather we work these out here
than defer them to the structured follow-up, since the read path is what
implementers will build against. Looking forward to hearing from
other community members as well on their take on this scenario.

Thanks,
Prashant

On Wed, Aug 26, 2026 at 2:04 PM Andrei Tserakhau via dev <
dev@iceberg.apache.org> wrote:

> Hi all!
>
> Coming back from vacation, I want to re-iterate and close the loop over the
> catalog community sync [1], where Labels in IRC [2] were the main topic of
> discussion.
>
> Thanks to everyone who joined and participated, this was a good discussion.
>
> I want to bring focus back to the proposal and SPEC change [3] that's
> actually on the table: a single optional `labels` field on the load
> response, flat k/v the catalog already owns, read-only, backward
> compatible,
> with no interpretation or enforcement defined by the spec.
>
> This is a deliberate choice to keep it minimal. Iceberg always leans toward
> standardizing the least common thing to enable value, while keeping the
> rest
> as innovation space for others (in this case, catalogs).
>
> This proposal leans into openness and exposes catalog metadata that drives
> many capabilities like policy enforcement, lifecycle management, data
> governance, attribution, etc. The mechanics of these capabilities are well
> outside of Iceberg's main function, but critical for systems managing
> Iceberg data.
>
> There's a lot of confusion between implementations and what the spec
> enables, but where the room converged was:
>
> - Labels are catalog-owned metadata exposed at load time. The catalog
>   presents what it knows about an object when the object is loaded, nothing
>   more. Labels are similar to table properties, but expose data owned by
> the
>   catalog rather than by table metadata.
>
> - It is not a coordination protocol. Renames / x-system sync / identity and
>   lineage / semantics of a label across catalogs are questions that live
>   outside this protocol. The protocol's goal is only to present the current
>   view at the current moment in time.
>
> - Labels are not competing with Read Restrictions, they are complementary
>   tools. Read Restrictions is server-side enforcement (the catalog
> evaluates
>   policy), while Labels are client-side (the catalog exposes context, but
>   consumers/engines decide what to do with it). Read Restrictions are
>   especially good when you are fully a client of another catalog, while
>   Labels can be useful when you consume another catalog and apply your own
>   policies without a trust relationship. We need both of these approaches
> in
>   IRC.
>
> - Governance is one use case, not the whole point. Most of the discussion
>   was centered around ABAC/TBAC, but the value is broader: ownership and
>   point of contact, cost attribution, retention / TTL / GDPR cleanup,
>   attribute-based maintenance, discovery and AI context. None of these need
>   enforcement, identity, or a tag-entity model to be useful.
>
> - The structured entity for tags (stable identity, rename semantics,
>   inheritance, x-catalog lineage) is an important follow-up, but the goal
>   here is to unblock value while we discuss the full entity model. This is
> a
>   similar pattern to what we already have in IRC: a dedicated entity API is
>   richer than exposure through another API. I will keep driving the
>   structured tag entity further.
>
> I would like to move to a VOTE on the read path.
>
> If there are concrete concerns about the spec as proposed, the field, the
> shape, or compatibility, let's discuss them in this thread.
>
> Use-case-specific coordination (x-system tag sync, rename semantics,
> identity binding) are the main topics for the 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Andrei Tserakhau via dev]

Hi all,

Quick recap from the June 29 labels sync [2 ],
and a call for review
on the spec PR [1 ].

We're converging on the read path. The representation is stable
-- the consolidated `labels: { table, columns }` shape has landed
on the PR -- so the most useful next step is reviewer engagement
on the PR itself. PMC and committer eyes especially welcome to
flag anything still needed on the read representation.

What the sync covered:

- Hot-path discipline softened: Ryan Blue and Daniel Weeks
  pushed back on latency requirements in the spec - latency is
  implementation-defined, and IRC sets no latency requirements
  elsewhere. The design doc now frames this as implementation
  guidance, not a normative requirement.

- E-Tag unchanged: the spec defines the minimum for E-Tag
  invalidation (table metadata). Whether catalogs fold labels
  into their E-Tag logic is left to implementation.

- Read path first: labels stay scoped to flat, attribute-level
  metadata exchange on LoadTableResponse -- the catalog surfaces
  its context, the consumer reads it. Same sequencing precedent
  as UDFs (list/load before CRUD); the write path (CRUD) is the
  natural follow-up and shouldn't block read-path review.

- Structured tags -- follow-up track: a richer structured model
  (identity, lifecycle, inheritance, cross-catalog semantics) is
  a real need for catalogs with first-class tag entities. A flat
  read view can't reconstruct that richness -- and for the read
  path it shouldn't try to; flat is the right shape here, and a
  structured layer builds on top. Prashant Singh raised this
  from the consumer side (comparisons to Gravitino). It's the
  focus of a dedicated follow-up sync rather than something to
  resolve on the read path.

Next steps:

- Read path: review the spec PR [1
] -- this is the ask.
- Structured tags + column-level policy management (Sung Yun):
  dedicated follow-up sync, date to follow.

Thanks to everyone who joined.

Andrei

[1] https://github.com/apache/iceberg/pull/15750
[2] https://youtu.be/arQVMl-fnxM

On Mon, Jun 29, 2026 at 5:32 PM Prashant Singh 
wrote:

> Hey Folks,
> This meeting is not open to everyone ? Have been waiting for some time in
> the waiting room
> Can someone let me in ?
>
> On Fri, Jun 26, 2026 at 7:59 AM Andrei Tserakhau via dev <
> dev@iceberg.apache.org> wrote:
>
>> Hi all,
>>
>> Next labels sync is scheduled for Monday, June 29, 2026, 8am PT /
>> 5pm CET. Earlier US-time slot to accommodate European attendees.
>>
>> Meet link: [https://meet.google.com/ezz-bvff-wjt]
>>
>> Agenda:
>>
>>- Updates since last sync (May 28)
>>- Labels / Tag boundary, topic from EJ Wang
>>- Write-path sketch walk-through
>>- ETag-based caching and concurrency (new topic, surfaced at the
>>recent IRC catalog community sync)
>>- Path to VOTE on the read API
>>
>> Concrete changes in the proposal [1] and spec PR [2] since the
>> May 28 recap:
>>
>>- Schema consolidated: labels and column-labels merged into a
>>single Labels object with table and columns sub-properties
>>(per Daniel Weeks' May 28 review). Resolves the "two fields
>>representing the same thing" feedback on the PR. JSON example
>>and appendix updated.
>>- Hot-Path Discipline added: LoadTableResponse latency MUST NOT
>>increase due to labels; how catalogs meet this is
>>implementation-defined (caching, freshness trade-offs,
>>filtering). Added in response to Christian Thiel's design doc
>>comment.
>>- Governance scope clarified: labels carry context, not
>>enforcement decisions. Enforcement semantics and policy vocabulary
>>live
>>in other spec layers (Read Restrictions, PR #13879 [3]).
>>- Open Questions cleaned up: write path summarized with ETag-based
>>optimistic concurrency + two-class distinction (catalog-managed
>>vs externally-managed keys); structured classification layer
>>reframed as the future authoring companion to labels as the
>>read surface.
>>
>> Goal on Monday: walk through the updated proposal, work through
>> remaining concerns on the read API, and identify what's needed to
>> move toward a VOTE.
>>
>> Thanks,
>> Andrei
>>
>> [1]
>> https://docs.google.com/document/d/1aj-6JlfBiMYEEVtNuh5WLMOrRQiMCcyYUGbouPM4hXI/edit
>> [2] https://github.com/apache/iceberg/pull/15750
>> [3] https://github.com/apache/iceberg/pull/13879
>>
>> On Fri, Jun 12, 2026 at 3:56 AM EJ Wang 
>> wrote:
>>
>>> Thanks Andrei for the recap. I want to clarify one point on the
>>> labels-vs-Tag boundary, mostly to avoid having the labels discussion
>>> pre-decide questions that belong in the parallel Tag discussion.
>>>
>>> I agree with the use cases motivating labels: exposing catalog-managed
>>> context such as ownership, domain, cost attribution, classification hints,
>>> and semantic hints in REST responses can be useful 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Prashant Singh]

Hey Folks,
This meeting is not open to everyone ? Have been waiting for some time in
the waiting room
Can someone let me in ?

On Fri, Jun 26, 2026 at 7:59 AM Andrei Tserakhau via dev <
dev@iceberg.apache.org> wrote:

> Hi all,
>
> Next labels sync is scheduled for Monday, June 29, 2026, 8am PT /
> 5pm CET. Earlier US-time slot to accommodate European attendees.
>
> Meet link: [https://meet.google.com/ezz-bvff-wjt]
>
> Agenda:
>
>- Updates since last sync (May 28)
>- Labels / Tag boundary, topic from EJ Wang
>- Write-path sketch walk-through
>- ETag-based caching and concurrency (new topic, surfaced at the
>recent IRC catalog community sync)
>- Path to VOTE on the read API
>
> Concrete changes in the proposal [1] and spec PR [2] since the
> May 28 recap:
>
>- Schema consolidated: labels and column-labels merged into a
>single Labels object with table and columns sub-properties
>(per Daniel Weeks' May 28 review). Resolves the "two fields
>representing the same thing" feedback on the PR. JSON example
>and appendix updated.
>- Hot-Path Discipline added: LoadTableResponse latency MUST NOT
>increase due to labels; how catalogs meet this is
>implementation-defined (caching, freshness trade-offs,
>filtering). Added in response to Christian Thiel's design doc
>comment.
>- Governance scope clarified: labels carry context, not
>enforcement decisions. Enforcement semantics and policy vocabulary
>live
>in other spec layers (Read Restrictions, PR #13879 [3]).
>- Open Questions cleaned up: write path summarized with ETag-based
>optimistic concurrency + two-class distinction (catalog-managed
>vs externally-managed keys); structured classification layer
>reframed as the future authoring companion to labels as the
>read surface.
>
> Goal on Monday: walk through the updated proposal, work through
> remaining concerns on the read API, and identify what's needed to
> move toward a VOTE.
>
> Thanks,
> Andrei
>
> [1]
> https://docs.google.com/document/d/1aj-6JlfBiMYEEVtNuh5WLMOrRQiMCcyYUGbouPM4hXI/edit
> [2] https://github.com/apache/iceberg/pull/15750
> [3] https://github.com/apache/iceberg/pull/13879
>
> On Fri, Jun 12, 2026 at 3:56 AM EJ Wang 
> wrote:
>
>> Thanks Andrei for the recap. I want to clarify one point on the
>> labels-vs-Tag boundary, mostly to avoid having the labels discussion
>> pre-decide questions that belong in the parallel Tag discussion.
>>
>> I agree with the use cases motivating labels: exposing catalog-managed
>> context such as ownership, domain, cost attribution, classification hints,
>> and semantic hints in REST responses can be useful for engines and clients.
>> The part I am less sure about is whether those use cases require a separate
>> Labels concept in the spec, or whether they should be modeled as projected
>> metadata from a structured Tag/classification model.
>>
>> My concern is dependency direction. If we introduce labels as a flat
>> generic primitive first, and later add structure for identity, lifecycle,
>> allowed values, inheritance, field-id attachment, visibility, and reverse
>> lookup, then we may end up reconstructing a Tag model around labels. That
>> feels less clear than defining the structured model directly and allowing
>> catalogs to project the relevant assignments into REST responses where
>> useful.
>>
>> In other words, I don't think the interesting question is only whether
>> labels should be flat or structured. I think the question is whether labels
>> should be a separate primitive at all, or whether the read-response use
>> cases can be covered by a projected view of structured tag/classification
>> assignments.
>>
>> Where I'd be especially careful is the phrase that tags are
>> "catalog-internal structured concepts." I agree that the full Tag
>> discussion is outside the scope of Labels V1, but I would not want Labels
>> V1 to pre-decide that structured tagging/classification semantics are only
>> catalog-internal and not an IRC concept. That is exactly the separate
>> question being explored in the Tag thread.
>>
>> The factoring I'd prefer to evaluate is:
>>
>>- Tag (structured) classification: authoring, lifecycle, identity,
>>field-id attachment, inheritance, visibility, and lookup semantics
>>- REST response projection: optional metadata returned to clients,
>>potentially derived from structured tag assignments
>>- read-restrictions: enforcement result delivered to engines
>>
>> That framing may reduce the need for a separate Labels primitive while
>> still preserving the read-response use cases that motivated the labels
>> proposal.
>>
>> I realize this may be a bigger factoring question than Labels V1 intended
>> to answer, but I think it is worth making explicit before the two threads
>> diverge. If the community wants one logical concept rather than both labels
>> and tags, I think we should at least evaluate the direction where the
>> 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Andrei Tserakhau via dev]

Hi all,

Next labels sync is scheduled for Monday, June 29, 2026, 8am PT /
5pm CET. Earlier US-time slot to accommodate European attendees.

Meet link: [https://meet.google.com/ezz-bvff-wjt]

Agenda:

   - Updates since last sync (May 28)
   - Labels / Tag boundary, topic from EJ Wang
   - Write-path sketch walk-through
   - ETag-based caching and concurrency (new topic, surfaced at the
   recent IRC catalog community sync)
   - Path to VOTE on the read API

Concrete changes in the proposal [1] and spec PR [2] since the
May 28 recap:

   - Schema consolidated: labels and column-labels merged into a
   single Labels object with table and columns sub-properties
   (per Daniel Weeks' May 28 review). Resolves the "two fields
   representing the same thing" feedback on the PR. JSON example
   and appendix updated.
   - Hot-Path Discipline added: LoadTableResponse latency MUST NOT
   increase due to labels; how catalogs meet this is
   implementation-defined (caching, freshness trade-offs,
   filtering). Added in response to Christian Thiel's design doc
   comment.
   - Governance scope clarified: labels carry context, not
   enforcement decisions. Enforcement semantics and policy vocabulary live
   in other spec layers (Read Restrictions, PR #13879 [3]).
   - Open Questions cleaned up: write path summarized with ETag-based
   optimistic concurrency + two-class distinction (catalog-managed
   vs externally-managed keys); structured classification layer
   reframed as the future authoring companion to labels as the
   read surface.

Goal on Monday: walk through the updated proposal, work through
remaining concerns on the read API, and identify what's needed to
move toward a VOTE.

Thanks,
Andrei

[1]
https://docs.google.com/document/d/1aj-6JlfBiMYEEVtNuh5WLMOrRQiMCcyYUGbouPM4hXI/edit
[2] https://github.com/apache/iceberg/pull/15750
[3] https://github.com/apache/iceberg/pull/13879

On Fri, Jun 12, 2026 at 3:56 AM EJ Wang 
wrote:

> Thanks Andrei for the recap. I want to clarify one point on the
> labels-vs-Tag boundary, mostly to avoid having the labels discussion
> pre-decide questions that belong in the parallel Tag discussion.
>
> I agree with the use cases motivating labels: exposing catalog-managed
> context such as ownership, domain, cost attribution, classification hints,
> and semantic hints in REST responses can be useful for engines and clients.
> The part I am less sure about is whether those use cases require a separate
> Labels concept in the spec, or whether they should be modeled as projected
> metadata from a structured Tag/classification model.
>
> My concern is dependency direction. If we introduce labels as a flat
> generic primitive first, and later add structure for identity, lifecycle,
> allowed values, inheritance, field-id attachment, visibility, and reverse
> lookup, then we may end up reconstructing a Tag model around labels. That
> feels less clear than defining the structured model directly and allowing
> catalogs to project the relevant assignments into REST responses where
> useful.
>
> In other words, I don't think the interesting question is only whether
> labels should be flat or structured. I think the question is whether labels
> should be a separate primitive at all, or whether the read-response use
> cases can be covered by a projected view of structured tag/classification
> assignments.
>
> Where I'd be especially careful is the phrase that tags are
> "catalog-internal structured concepts." I agree that the full Tag
> discussion is outside the scope of Labels V1, but I would not want Labels
> V1 to pre-decide that structured tagging/classification semantics are only
> catalog-internal and not an IRC concept. That is exactly the separate
> question being explored in the Tag thread.
>
> The factoring I'd prefer to evaluate is:
>
>- Tag (structured) classification: authoring, lifecycle, identity,
>field-id attachment, inheritance, visibility, and lookup semantics
>- REST response projection: optional metadata returned to clients,
>potentially derived from structured tag assignments
>- read-restrictions: enforcement result delivered to engines
>
> That framing may reduce the need for a separate Labels primitive while
> still preserving the read-response use cases that motivated the labels
> proposal.
>
> I realize this may be a bigger factoring question than Labels V1 intended
> to answer, but I think it is worth making explicit before the two threads
> diverge. If the community wants one logical concept rather than both labels
> and tags, I think we should at least evaluate the direction where the
> structured Tag/classification model is the source of truth and lightweight
> REST response metadata is a projection from it, before standardizing labels
> as an independent primitive.
>
> -ej
>
> On Thu, Jun 11, 2026 at 11:53 AM Andrei Tserakhau via dev <
> dev@iceberg.apache.org> wrote:
>
>> Hi all,
>>
>> Recap from the dedicated labels sync held on May 28, 2026

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[EJ Wang]

Thanks Andrei for the recap. I want to clarify one point on the
labels-vs-Tag boundary, mostly to avoid having the labels discussion
pre-decide questions that belong in the parallel Tag discussion.

I agree with the use cases motivating labels: exposing catalog-managed
context such as ownership, domain, cost attribution, classification hints,
and semantic hints in REST responses can be useful for engines and clients.
The part I am less sure about is whether those use cases require a separate
Labels concept in the spec, or whether they should be modeled as projected
metadata from a structured Tag/classification model.

My concern is dependency direction. If we introduce labels as a flat
generic primitive first, and later add structure for identity, lifecycle,
allowed values, inheritance, field-id attachment, visibility, and reverse
lookup, then we may end up reconstructing a Tag model around labels. That
feels less clear than defining the structured model directly and allowing
catalogs to project the relevant assignments into REST responses where
useful.

In other words, I don't think the interesting question is only whether
labels should be flat or structured. I think the question is whether labels
should be a separate primitive at all, or whether the read-response use
cases can be covered by a projected view of structured tag/classification
assignments.

Where I'd be especially careful is the phrase that tags are
"catalog-internal structured concepts." I agree that the full Tag
discussion is outside the scope of Labels V1, but I would not want Labels
V1 to pre-decide that structured tagging/classification semantics are only
catalog-internal and not an IRC concept. That is exactly the separate
question being explored in the Tag thread.

The factoring I'd prefer to evaluate is:

   - Tag (structured) classification: authoring, lifecycle, identity,
   field-id attachment, inheritance, visibility, and lookup semantics
   - REST response projection: optional metadata returned to clients,
   potentially derived from structured tag assignments
   - read-restrictions: enforcement result delivered to engines

That framing may reduce the need for a separate Labels primitive while
still preserving the read-response use cases that motivated the labels
proposal.

I realize this may be a bigger factoring question than Labels V1 intended
to answer, but I think it is worth making explicit before the two threads
diverge. If the community wants one logical concept rather than both labels
and tags, I think we should at least evaluate the direction where the
structured Tag/classification model is the source of truth and lightweight
REST response metadata is a projection from it, before standardizing labels
as an independent primitive.

-ej

On Thu, Jun 11, 2026 at 11:53 AM Andrei Tserakhau via dev <
dev@iceberg.apache.org> wrote:

> Hi all,
>
> Recap from the dedicated labels sync held on May 28, 2026
> (recording [1]).
>
> Summary of the discussion:
>
>-
>
>Strong consensus to land the read API first, with the write API
>as a separate follow-up proposal (Ryan, Sung, Kevin, Christian
>aligned). Christian raised a concern that the write half could
>lag behind (Trino views precedent); to address this, the
>proposal will document the write-path direction alongside the
>read API.
>-
>
>Labels remain flat key-value pairs, no internal structure.
>Kubernetes labels precedent invoked — flat shape, conventions
>via well-known prefixes, no spec-defined vocabulary.
>Namespace-as-attribute (raised by Uladzimir Makaranka, Polaris)
>discussed and set aside in favor of prefix conventions.
>-
>
>Labels-vs-Tag boundary: labels are the wire-protocol mechanism
>for cross-catalog metadata exchange (this proposal); tags are
>catalog-internal structured concepts (Snowflake, UC, Polaris
>each have their own shape). Standardizing Tag itself as a
>first-class spec entity is a separate effort, not in scope for
>V1. EJ Wang's parallel Tag proposal on dev@ [2] is in that
>direction.
>-
>
>Governance scope: Prashant Singh raised concerns about
>positioning labels as a governance protocol — provenance,
>identity mapping across IDPs, inheritance semantics. Room
>aligned that labels are broader than governance — semantic
>metadata exchange is the load-bearing case; governance remains
>a valid use case among many, and whether to use labels for
>governance is a catalog-level decision rather than a spec
>mandate. Policy decisions and enforcement live in read
>restrictions (PR #13879 [3]) — a parallel and complementary
>track.
>-
>
>Write API shape converging on an independent CRUD endpoint
>(UpdateLabels-style verb) with a transactional path for atomic
>table+label operations at create/alter time. Two-class
>distinction (catalog-authored vs externally-managed labels)
>reaffirmed; Ryan noted not all labels 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Andrei Tserakhau via dev]

Hi all,

Recap from the dedicated labels sync held on May 28, 2026
(recording [1]).

Summary of the discussion:

   -

   Strong consensus to land the read API first, with the write API
   as a separate follow-up proposal (Ryan, Sung, Kevin, Christian
   aligned). Christian raised a concern that the write half could
   lag behind (Trino views precedent); to address this, the
   proposal will document the write-path direction alongside the
   read API.
   -

   Labels remain flat key-value pairs, no internal structure.
   Kubernetes labels precedent invoked — flat shape, conventions
   via well-known prefixes, no spec-defined vocabulary.
   Namespace-as-attribute (raised by Uladzimir Makaranka, Polaris)
   discussed and set aside in favor of prefix conventions.
   -

   Labels-vs-Tag boundary: labels are the wire-protocol mechanism
   for cross-catalog metadata exchange (this proposal); tags are
   catalog-internal structured concepts (Snowflake, UC, Polaris
   each have their own shape). Standardizing Tag itself as a
   first-class spec entity is a separate effort, not in scope for
   V1. EJ Wang's parallel Tag proposal on dev@ [2] is in that
   direction.
   -

   Governance scope: Prashant Singh raised concerns about
   positioning labels as a governance protocol — provenance,
   identity mapping across IDPs, inheritance semantics. Room
   aligned that labels are broader than governance — semantic
   metadata exchange is the load-bearing case; governance remains
   a valid use case among many, and whether to use labels for
   governance is a catalog-level decision rather than a spec
   mandate. Policy decisions and enforcement live in read
   restrictions (PR #13879 [3]) — a parallel and complementary
   track.
   -

   Write API shape converging on an independent CRUD endpoint
   (UpdateLabels-style verb) with a transactional path for atomic
   table+label operations at create/alter time. Two-class
   distinction (catalog-authored vs externally-managed labels)
   reaffirmed; Ryan noted not all labels should be editable via
   CRUD since many are produced by the catalog through inheritance,
   classification, or automated paths.
   -

   Bulk APIs surfaced as a real need for both read (inverted index
   — finding tables/columns matching given labels) and write
   (applying labels at scale, classifier batch operations). Scoped
   for inclusion in the write API proposal.
   -

   Pattern for adding new first-class REST concepts (labels, UDFs,
   indexes, etc.): independent CRUD endpoint per concept, paired
   with a transactional path for atomic operations alongside table
   create/alter. Useful reference shape for future spec additions.

Post-sync follow-ups already in motion:

   -

   Hot-path discipline added to the proposal in response to
   Christian Thiel's doc comment: LoadTableResponse latency MUST
   NOT increase due to labels; how catalogs meet this is
   implementation-defined (caching, freshness trade-offs,
   filtering). Capability negotiation — parallel to the work on
   PR #13879 [3] — is a future direction.
   -

   Use case split (high-confidence cross-catalog: semantic, domain,
   classification, sensitivity vs platform-specific: owner,
   principals, anything identity-bound) agreed after offline
   follow-up with Prashant; will be reflected in the next proposal
   revision.
   -

   A separate [DISCUSS] thread will land the substrate framing
   publicly.

Next sync approximately three / four weeks out. Tentative agenda:
labels/Tag boundary update, write-path sketch walk-through, path
to VOTE on the read API.

Thanks to everyone who joined and to those continuing to engage
on the design doc [4] and spec PR #15750 [5].

Best,
Andrei

[1] https://youtu.be/P4NOQASNtPA
[2] https://lists.apache.org/thread/r5r3vpmrfy9wmmb4sdybwcjz1c4wld5b
[3] https://github.com/apache/iceberg/pull/13879
[4]
https://docs.google.com/document/d/1aj-6JlfBiMYEEVtNuh5WLMOrRQiMCcyYUGbouPM4hXI/edit
[5] https://github.com/apache/iceberg/pull/15750

On Wed, May 27, 2026 at 12:12 AM Andrei Tserakhau <
andrei.tserak...@databricks.com> wrote:

> Quick update on this on:
> we'll cover this on the Dedicated Sync this Thursday (10-11am US / 7-8pm
> CET). Thanks to Daniel Weeks for getting it on the calendar.
>
> Last time labels was on the sync was 2026-04-15. Plenty of productive
> offline discussion since then, mostly in the gdoc comment threads. Thanks
> to everyone who engaged:
>
>- *Daniel Weeks* — for the IRC-spec-vs-table-spec framing that now
>anchors the Alternatives section
>- *Fokko Driesprong* — for challenging motivation on the cost-based
>defense and driving the ownership reframe
>- *Yufei Gu* — for the structure debate that landed us on the split
>shape
>- *Sung Yun* — for the early consumption-pattern and addressing
>questions
>- *Maninder Parmar* — for the properties-relationship probing
>- *Christian Thiel* — for pushing on the write API direction
>
> Concrete changes 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Andrei Tserakhau via dev]

Quick update on this on:
we'll cover this on the Dedicated Sync this Thursday (10-11am US / 7-8pm
CET). Thanks to Daniel Weeks for getting it on the calendar.

Last time labels was on the sync was 2026-04-15. Plenty of productive
offline discussion since then, mostly in the gdoc comment threads. Thanks
to everyone who engaged:

   - *Daniel Weeks* — for the IRC-spec-vs-table-spec framing that now
   anchors the Alternatives section
   - *Fokko Driesprong* — for challenging motivation on the cost-based
   defense and driving the ownership reframe
   - *Yufei Gu* — for the structure debate that landed us on the split shape
   - *Sung Yun* — for the early consumption-pattern and addressing questions
   - *Maninder Parmar* — for the properties-relationship probing
   - *Christian Thiel* — for pushing on the write API direction

Concrete changes in-doc since April:

   - Problem Statement reframed around catalog-owned metainformation as the
   load-bearing concept.
   - Alternatives Considered rewritten with the IRC-spec-vs-table-spec
   boundary instead of cost arguments.
   - Structure debate closed on a split shape: labels (flat k/v at the
   table level, k8s-style) + column-labels (array with field-id). Labels
   type itself is flat — no internal structure. Same shape applies on
   LoadViewResponse and namespaces.
   - CRUD companion as a second tab in the same gdoc — UpdateLabels REST
   verb, two-class distinction for catalog-managed vs externally-managed keys,
   optimistic concurrency with ETags.
   - Working Trino prototype at
   https://github.com/laskoviymishka/irc-labels/pull/1 — native ALTER TABLE
   ... SET LABEL DDL translating end-to-end.

Parallel work to flag: EJ Wang's first-class Tag concept
 proposal
on dev@. We've agreed to coordinate as paired proposals — Tag as a separate
first-class REST concept, labels as the lower-level attachment substrate.
Both efforts share the cross-cutting interop question.

Goal on Thursday is to walk through the current state, confirm the
split-shape lands cleanly, and identify what's needed to move toward a VOTE
on the read API. Anyone reading along is welcome to join.

Doc (current state):
https://docs.google.com/document/d/1aj-6JlfBiMYEEVtNuh5WLMOrRQiMCcyYUGbouPM4hXI/edit

Thanks,
Andrei

On Tue, Mar 24, 2026 at 9:35 PM Andrei Tserakhau <
andrei.tserak...@databricks.com> wrote:

> Thanks Ryan!
>
> Your point about avoiding first-class metadata requirements is exactly the
> design principle here. Labels let each catalog surface what it knows
> without the spec dictating what catalogs must track.
>
> To build on this, I put together a POC showing the approach works across
> the ecosystem.
>
> Key design principles that held up in practice:
>
> - No new requirements on catalogs. Labels are optional in the response. A
> catalog that doesn't serve labels returns the same response as today.
>
> - Catalog-scoped, not table state. Every catalog we tried already has
> internal metadata separate from Iceberg properties — Polaris has
> internalProperties, UC has uc_properties, Lakekeeper has namespace
> properties in PostgreSQL. Labels just give this existing metadata a
> standard way through the protocol.
>
> - No property overriding. Labels are explicitly separate from table
> properties. Properties configure behavior, labels describe context. Engines
> know which is which.
>
> What built:
>
> - Spec change: https://github.com/apache/iceberg/pull/15750
> - PyIceberg client: https://github.com/apache/iceberg-python/pull/3191
>
> Catalog implementations:
> - Polaris: https://github.com/apache/polaris/pull/4048 (labels from
> internalProperties)
> - Unity Catalog OSS:
> https://github.com/unitycatalog/unitycatalog/pull/1417 (labels from
> uc_properties)
> - Lakekeeper: https://github.com/lakekeeper/lakekeeper/pull/1676 (labels
> from namespace properties)
>
> Full demo: https://github.com/laskoviymishka/irc-labels
>
> Three catalogs, two languages (Java + Rust), 40-95 lines each. The pattern
> is the same everywhere, each catalog already has internal metadata that
> doesn't belong in table properties. Labels give it a standard way out
> through the protocol.
>
> The Polaris implementation also addresses
> https://github.com/apache/polaris/issues/3222 - the community has been
> asking for a way to surface business metadata alongside table loads. Labels
> solve this without adding any requirements beyond an optional field.
>
> Beyond ownership and classification, the demo also shows labels enabling
> AI agent table selection (agents reason about tables using semantic labels
> instead of guessing from column names) and governance via trusted engine
> (ClickHouse reading sensitivity labels to auto-generate masking policies).
>
> Happy to discuss the spec design or any of the implementation details.
>
> Andrei
>
> On Fri, Mar 6, 2026 at 11:25 PM Ryan Blue  wrote:
>
>> I think that this is a reasonable way to 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Andrei Tserakhau via dev]

Thanks Ryan!

Your point about avoiding first-class metadata requirements is exactly the
design principle here. Labels let each catalog surface what it knows
without the spec dictating what catalogs must track.

To build on this, I put together a POC showing the approach works across
the ecosystem.

Key design principles that held up in practice:

- No new requirements on catalogs. Labels are optional in the response. A
catalog that doesn't serve labels returns the same response as today.

- Catalog-scoped, not table state. Every catalog we tried already has
internal metadata separate from Iceberg properties — Polaris has
internalProperties, UC has uc_properties, Lakekeeper has namespace
properties in PostgreSQL. Labels just give this existing metadata a
standard way through the protocol.

- No property overriding. Labels are explicitly separate from table
properties. Properties configure behavior, labels describe context. Engines
know which is which.

What built:

- Spec change: https://github.com/apache/iceberg/pull/15750
- PyIceberg client: https://github.com/apache/iceberg-python/pull/3191

Catalog implementations:
- Polaris: https://github.com/apache/polaris/pull/4048 (labels from
internalProperties)
- Unity Catalog OSS: https://github.com/unitycatalog/unitycatalog/pull/1417
(labels from uc_properties)
- Lakekeeper: https://github.com/lakekeeper/lakekeeper/pull/1676 (labels
from namespace properties)

Full demo: https://github.com/laskoviymishka/irc-labels

Three catalogs, two languages (Java + Rust), 40-95 lines each. The pattern
is the same everywhere, each catalog already has internal metadata that
doesn't belong in table properties. Labels give it a standard way out
through the protocol.

The Polaris implementation also addresses
https://github.com/apache/polaris/issues/3222 - the community has been
asking for a way to surface business metadata alongside table loads. Labels
solve this without adding any requirements beyond an optional field.

Beyond ownership and classification, the demo also shows labels enabling AI
agent table selection (agents reason about tables using semantic labels
instead of guessing from column names) and governance via trusted engine
(ClickHouse reading sensitivity labels to auto-generate masking policies).

Happy to discuss the spec design or any of the implementation details.

Andrei

On Fri, Mar 6, 2026 at 11:25 PM Ryan Blue  wrote:

> I think that this is a reasonable way to solve some persistent issues that
> we've seen.
>
> Many catalogs track additional metadata that is not part of the table spec
> (or others) like "owner", and right now there is no way to exchange or
> share that information. I'm also hesitant to start including it as
> first-class metadata because that puts additional requirements on catalogs
> that may not align. For instance, Tabular had no concept of a table "owner"
> and instead used default grants at the schema level. I like that this
> solution allows catalogs to provide information in a generic way that
> doesn't add requirements in the REST spec. And it is an alternative to
> overriding table properties with catalog-managed information, which I think
> is an anti-pattern.
>
> Thanks, Andrei! I think this is a good idea.
>
> On Thu, Mar 5, 2026 at 2:04 PM Andrei Tserakhau via dev <
> dev@iceberg.apache.org> wrote:
>
>> Hi all,
>>
>> `LoadTableResponse` returns table metadata — schema, snapshots, file
>> locations — but catalogs have operational context about tables that has no
>> standard place to go: cost attribution, ownership, governance hints,
>> semantic metadata. Right now catalogs have two options:
>>
>> 1. Properties — durable, commit-versioned table state. Good for
>> persistent metadata; wrong for ephemeral catalog context.
>> 2. Custom fields — catalog-specific extensions with no interoperability.
>> Each catalog invents its own structure; engines have no basis to read them.
>>
>> The community has already identified this gap. Polaris opened an issue
>> [1] requesting a standard extension point in the IRC protocol for
>> catalog-managed metadata. Two earlier threads [2][3] explored column-level
>> metadata, though in the context of table format changes.
>>
>> We propose adding an optional `labels` field to `LoadTableResponse` for
>> catalog-managed metadata. Labels are string key-value pairs generated
>> per-request from the catalog's internal systems; nothing is written to
>> table files. Engines may use or ignore them entirely. Labels give catalog
>> providers a standard channel to surface context to any client without
>> bilateral custom integrations for every catalog-engine pair.
>>
>> Details:
>> - GitHub Issue: apache/iceberg#15521
>> - Design Document: [4]
>>
>> Please review the proposal and share your feedback.
>>
>> Thanks,
>> Andrei
>>
>> [1]: https://github.com/apache/polaris/issues/3222
>> [2]: https://lists.apache.org/thread/vwrc3m534gfyfjnsfflwtgkg158yzrb4
>> [3]: 

Re: [DISCUSS] Table and Column Label Metadata in Iceberg REST Catalog

[Ryan Blue]

I think that this is a reasonable way to solve some persistent issues that
we've seen.

Many catalogs track additional metadata that is not part of the table spec
(or others) like "owner", and right now there is no way to exchange or
share that information. I'm also hesitant to start including it as
first-class metadata because that puts additional requirements on catalogs
that may not align. For instance, Tabular had no concept of a table "owner"
and instead used default grants at the schema level. I like that this
solution allows catalogs to provide information in a generic way that
doesn't add requirements in the REST spec. And it is an alternative to
overriding table properties with catalog-managed information, which I think
is an anti-pattern.

Thanks, Andrei! I think this is a good idea.

On Thu, Mar 5, 2026 at 2:04 PM Andrei Tserakhau via dev <
dev@iceberg.apache.org> wrote:

> Hi all,
>
> `LoadTableResponse` returns table metadata — schema, snapshots, file
> locations — but catalogs have operational context about tables that has no
> standard place to go: cost attribution, ownership, governance hints,
> semantic metadata. Right now catalogs have two options:
>
> 1. Properties — durable, commit-versioned table state. Good for persistent
> metadata; wrong for ephemeral catalog context.
> 2. Custom fields — catalog-specific extensions with no interoperability.
> Each catalog invents its own structure; engines have no basis to read them.
>
> The community has already identified this gap. Polaris opened an issue [1]
> requesting a standard extension point in the IRC protocol for
> catalog-managed metadata. Two earlier threads [2][3] explored column-level
> metadata, though in the context of table format changes.
>
> We propose adding an optional `labels` field to `LoadTableResponse` for
> catalog-managed metadata. Labels are string key-value pairs generated
> per-request from the catalog's internal systems; nothing is written to
> table files. Engines may use or ignore them entirely. Labels give catalog
> providers a standard channel to surface context to any client without
> bilateral custom integrations for every catalog-engine pair.
>
> Details:
> - GitHub Issue: apache/iceberg#15521
> - Design Document: [4]
>
> Please review the proposal and share your feedback.
>
> Thanks,
> Andrei
>
> [1]: https://github.com/apache/polaris/issues/3222
> [2]: https://lists.apache.org/thread/vwrc3m534gfyfjnsfflwtgkg158yzrb4
> [3]: https://lists.apache.org/thread/yflg8w1h87qgwc4s3qtog4l8nx8nk8m0
> [4]:
> https://docs.google.com/document/d/1aj-6JlfBiMYEEVtNuh5WLMOrRQiMCcyYUGbouPM4hXI/edit?usp=sharing
>