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 <[email protected]> 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 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 < > [email protected]> 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 structured follow-up and, >> per >> the discussion, are out of scope for the read path. >> >> [1] Catalog Sync Recording: https://www.youtube.com/watch?v=lCTV-Rhiwyc >> [2] Spec Proposal doc: >> https://docs.google.com/document/d/1aj-6JlfBiMYEEVtNuh5WLMOrRQiMCcyYUGbouPM4hXI/edit?tab=t.0#heading=h.2w0kmp1v1gwv >> [3] Spec PR: https://github.com/apache/iceberg/pull/15750 >> >> Best, >> Andrei >> >
