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 > > >
