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
