Make IPFS HTTP Gateway responses easier to reason about by not requiring IPLD Data Model translations
When sending an Accept header or format query parameter to specify the response format of a request, the IPFS HTTP Gateway specs allow translation of the requested content into the IPLD Data Model.
This adds significant complexity to HTTP Gateway implementations, since they need to be able to translate between arbitrary data types and handle all the various failure states.
The conversions are also lossy due to differences in supported data types across different formats so lack general-purpose utility and are ultimately something that could be done on an interested client if required.
When the block's CID codec matches the requested response format,
implementations MAY return the block as-is without parsing or validating it.
This is effectively equivalent to requesting ?format=raw but with a
codec-specific Content-Type header.
When the CID codec does not match the requested format, the gateway SHOULD return a 406 Not Acceptable unless the server provides cross-codec conversion as an extra feature outside of this specification.
For example, requesting a DAG-JSON block with the application/cbor format
would result in a 406 response.
Where a human-readable rendering of the data is desired, the text/html format
can be requested. This would allow browsing DAG-PB data, for example.
A 400 may be returned if the request was invalid (for example an unsupported format was requested).
A 500 may be returned in other circumstances.
Simplifying the HTTP Gateway spec to remove these format translations and the additional logic required makes it more straightforward to create new implementations, and makes the returned data more transparent and so easier to understand since the data is not modified to fit the output format.
Clients that wish to translate between different data formats may request raw blocks and do the translation themselves.
For gateway operators and implementers, removing the requirement to perform codec conversions server-side significantly reduces implementation complexity.
For end users and application developers, the change makes gateway behavior
easier to reason about: a request either returns data deserialized according
to the rules of the CID's original codec, or fails with 406. This moves
conversion to userland, encouraging users to fetch raw blocks with
?format=raw and convert client-side, putting the application in full control
and producing deterministic results regardless of which gateway is used.
This matters in practice because codec libraries do not behave identically. Cross-library dag-cbor tests (2026) show each implementation differs on edge cases like float handling, map key ordering, and encoding strictness. Relying on server-side conversion means the output depends on whichever library the gateway happens to use, which is not a foundation for robust software.
Formally this is a breaking change: server-side IPLD Data Model translations between codecs are removed.
In practice, nobody could build reliable software
on top of conversion logic that behaved non-deterministically across gateways
written in different languages. Clients that needed data in a different
format often chose to fetch ?format=raw and convert client-side already.
This IPIP standardizes that robust real-world pattern and removes an unreliable niche feature that has seen limited use.
?format= usage on ipfs.io and dweb.linkA 24-hour sample of traffic on the ipfs.io and dweb.link public gateways
(Feb 2026) shows that only 4.5% of all requests use the ?format= query
parameter, and the vast majority ask for json:
?format= value |
% of requests with format= |
|---|---|
json |
99.11% |
raw |
0.86% |
dag-json |
0.02% |
car |
0.01% |
| other | <0.01% |
Note: ipfs.io and dweb.link serve deserialized responses. Trustless
verifiable requests (?format=raw, ?format=car) are redirected to
trustless-gateway.link, which is why those formats appear so rarely here.
Looking at what those ?format=json requests actually point at tells the
real story. The CID codec of the requested blocks breaks down as follows:
| CID codec of requested block | % of ?format=json |
|---|---|
dag-pb (CIDv0 Qm...) |
60.0% |
dag-pb (CIDv1 bafy...) |
21.4% |
raw (bafk...) |
18.6% |
100% of ?format=json requests are for blocks with dag-pb or raw codec.
None target the json codec (0x0200). In other words, these clients are
reading regular JSON files stored as UnixFS, not asking the gateway to convert
between IPLD codecs. The gateway serves them as plain HTTP file responses,
which is covered by the UnixFS interop exception described later in this IPIP.
The remaining formats (dag-json and car) together account for less than
0.04% of ?format= requests and do not depend on cross-codec conversion
either, since they request data in the block's native codec.
json and dag-json independenceapplication/json and application/vnd.ipld.dag-json are now treated as
independent formats, each matching only their respective CID codec (json
0x0200 and dag-json 0x0129). The old behavior where application/json was
an alias for application/vnd.ipld.dag-json (falling back to dag-json
conversion) no longer applies.
Accept: application/jsonNote: the codec match requirement and 406 behavior described above do not
apply to deserialized UnixFS file responses. Users commonly store valid JSON
as UnixFS files (with dag-pb or raw codec), and serving those files with
Accept: application/json is regular HTTP content serving, not codec
conversion. See the application/json entry in the
Accept request header
section of the Path Gateway spec for normative requirements.
Implementations MAY offer an opt-in configuration flag to restore the old codec conversion behavior for backward compatibility.
?format=json / Accept: application/json on non-json-codec
content (like dag-pb UnixFS files).No security implications. This change restricts gateway behavior (returning 406 instead of converting), which reduces attack surface.
Implementers can run the gateway-conformance test suite v0.10 or later. The following behaviors are verified by the test suite:
dag-pb block with ?format=dag-json) returns HTTP 406.?format=raw works for any codec.Accept: text/html) of DAG-JSON/DAG-CBOR blocks is not
codec conversion and remains part of the spec.Copyright and related rights waived via CC0.
We gratefully acknowledge the following individuals for their valuable contributions, ranging from minor suggestions to major insights, which have shaped and improved this specification.
