This seems matched to what I thought we went over, I'm also not sure why
the shape *capabilities : {foo, bar}* necessarily mean the client has to
send all the capabilities with every request. Can the client just decide to
send *capabilities:{foo}* to those endpoints that care about foo?On Tue, May 19, 2026 at 2:54 PM Daniel Weeks <[email protected]> wrote: > Thanks for following up on this, Prashant. > > My recollection of the conversation was not to add a single header that > allows an arbitrary number of capabilities set, but rather to follow the > pattern established with the `x-iceberg-access-delegation' and use specific > headers applicable to endpoints where they would apply. > > I'm not convinced we want to have all the capabilities bundled up and sent > for every request (though this might be easier to implement in some > cases). There may be scenarios where you want to advertise capabilities or > not depending on the client configuration and would make managing the set > of properties more difficult. > > After reviewing the conversation, this doesn't quite correspond to how we > ended the discussion. > > -Dan > > On Tue, May 19, 2026 at 7:06 AM Sung Yun <[email protected]> wrote: > >> Thanks Prashant, I’m supportive of introducing a generic client >> capabilities header. I agree with the direction of treating this primarily >> as capability advertisement for compatibility and response shaping rather >> than as a trust mechanism. >> >> I left a couple comments on the PR. One thing I’m wondering is whether we >> should discuss and define the versioning and compatibility model for >> capability header values as part of this proposal. >> >> Capabilities like `read-restrictions` seem very likely to evolve over >> time in ways that older clients may not be able to safely consume. I’m >> curious whether the community thinks capability values should represent >> versioned compatibility contracts (like read-restrictions.v1) and whether >> we want to define any expectations around cross-version compatibility >> behavior now as we introduce the header. >> >> Sung >> >> On 2026/05/18 18:51:52 Prashant Singh wrote: >> > Hi all, >> > >> > I'd like to propose adding a new HTTP header, >> > X-Iceberg-Client-Capabilities, >> > to the REST catalog spec. This was brought up at the Read Restrictions >> > community sync on May 12, 2026; I'm bringing it to the broader list >> now >> > for >> > wider feedback. >> > >> > PR: https://github.com/apache/iceberg/pull/16394 >> > Recording: https://youtu.be/b9p6mI-k-0I >> > >> > *Context* >> > >> > Iceberg's REST protocol keeps evolving — server-side scan >> > planning, remote signing, and the in-flight ReadRestrictions >> proposal >> > (PR #13879) are all features that catalogs may return but older clients >> > can't handle. Today there's no standard way for a client to declare >> > "I understand X" to the server. One direction discussed at the >> community >> > sync was to introduce a single generic capability header rather than >> > per-feature negotiations; this thread is to gather broader input on >> that >> > proposal. >> > >> > *Proposal* >> > >> > Send X-Iceberg-Client-Capabilities on every catalog request: >> > >> > ex: X-Iceberg-Client-Capabilities: >> > vended-credentials,remote-signing,scan-planning >> > >> > The Java SDK adds it via HTTPClient.baseHeaders — the same path used >> for >> > X-Client-Version and X-Client-Git-Commit-Short today. Other client >> > implementations (PyIceberg, Rust, Go, etc.) can mirror the same enum. >> > >> > Initial capability set for Java SDK: >> > - vended-credentials >> > - remote-signing >> > - scan-planning >> > >> > read-restrictions will be added once PR #13879 lands. >> > >> > >> > * Design notes worth feedback* >> > 1. Forward-compat hint, not security. The header is informational — >> > clients >> > can trivially spoof its value, so servers MUST NOT base trust or >> > authorization decisions on it. Trust establishment (mTLS, OAuth, >> etc.) >> > is out of scope. The spec parameter description states this >> explicitly. >> > >> > 2. enum: constraint on the schema. Mirrors >> X-Iceberg-Access-Delegation. >> > Adding >> > a new capability is a one-line spec edit; generated clients can >> > validate >> > values; servers get a machine-readable closed list of recognized >> > values. >> > >> > 3. Skipped for /v1/oauth/tokens. OAuth token endpoints may be served >> by >> > external IdPs (Okta, Auth0, etc.) where Iceberg-specific headers >> are >> > noise. Mirrors how X-Iceberg-Access-Delegation is handled. >> > >> > *Links* >> > >> > - PR: https://github.com/apache/iceberg/pull/16394 >> > - May 12 sync recording: https://youtu.be/b9p6mI-k-0I >> > - Related: PR #13879 <https://github.com/apache/iceberg/pull/13879> >> > >> > Thanks, >> > Prashant >> > >> >
