IPIP-0523: Prefer format request param over Accept header

Browsers will always send an Accept header so if present the format
request param should take priority, not the other way round as the
spec currently says.

Author: achingbrain

src/http-gateways/path-gateway.md

@@ -240,7 +240,7 @@ These are the equivalents:
 - `format=ipns-record` → `Accept: application/vnd.ipfs.ipns-record`
 
 When both `Accept` HTTP header  and `format` query parameter are present,
-`Accept` SHOULD take precedence.
+`format` SHOULD take precedence.
 
 A Client SHOULD include the `format` query parameter in the request URL, in
 addition to the `Accept` header. This provides the best interoperability and

src/ipips/ipip-0523.md

@@ -0,0 +1,83 @@
+---
+title: "IPIP-0523: Prefer format request param over Accept header"
+date: 2025-11-26
+ipip: proposal
+editors:
+  - name: Alex Potsides
+    github: achingbrain
+    url: https://achingbrain.net
+    affiliation:
+        name: Shipyard
+        url: https://ipshipyard.com
+relatedIssues:
+  - https://github.com/ipfs/specs/issues/521
+order: 523
+tags: ['ipips']
+---
+
+## Summary
+
+Prefer the `format` request param over the Accept header
+
+## Motivation
+
+The [Accept](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept)
+header can be sent with an HTTP request to provide a prioritized list of
+response formats the client will accept for a given resource.
+
+The [format](https://specs.ipfs.tech/http-gateways/path-gateway/#format-request-query-parameter)
+request query parameter can also be sent to an IPFS HTTP Gateway to provide the
+same information, and is typically done when sending an HTTP header is difficult
+or impractical, for example in a browser.
+
+The existing [Path Gateway](https://specs.ipfs.tech/http-gateways/path-gateway/#format-request-query-parameter) and [Trustless Gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/#format-request-query-parameter) specs say:
+
+> When both the Accept header and format parameter are present, a specific Accept value (e.g., application/vnd.ipld.raw) SHOULD take precedence over format.
+
+This makes it impossible for browsers to use the `format` request query
+parameter, since they will always send an `Accept` header which would then cause
+the `format` request query parameter to be ignored.
+
+## Detailed design
+
+The priority of `format` vs `Accept` should be reversed, so as to always prefer
+`format` over `Accept` if it is present.
+
+## Design rationale
+
+Browsers will always send an `Accept` header that contains specific values so it
+cannot be allowed to take priority over the `format` request query parameter.
+
+### User benefit
+
+Users will be able to use the `format` request query parameter to control the
+response type of requests made from browser address bars.
+
+### Compatibility
+
+This is a breaking change, though several implementations implement this part of
+the spec incorrectly, already favouring `format` over `Accept` so the impact
+should be minimal.
+
+### Security
+
+It is highly advised to implement validation conformance tests using the fixtures
+included at the end of this IPIP.
+
+### Alternatives
+
+None.
+
+## Test fixtures
+
+:::note
+
+Implementers can either write own test that prefers the format query param over
+any present Accept header, or run the [gateway-conformance](https://github.com/ipfs/gateway-conformance/)
+test suite, which includes tests for this scenario since [gateway-conformance/pull/252](https://github.com/ipfs/gateway-conformance/pull/252).
+
+:::
+
+### Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).