5.3 CAR order (content type parameter)
The order parameter allows clients to specify the desired block order in the
response. It supports the following values:
dfs: Depth-First Search
order, enables streaming responses with minimal memory usage.unk (or missing): Unknown order, which serves as the implicit default when the order
parameter is unspecified. In this case, the client cannot make any assumptions
about the block order: blocks may arrive in a random order or be a result of
a custom DAG traversal algorithm.
A Gateway SHOULD always return explicit order in CAR's Content-Type response header.
A Gateway MAY skip order in CAR response if no order was explicitly requested
by the client and the default order is unknown.
A Client MUST assume implicit order=unk when order is missing, unknown, or empty.
5.4 CAR dups (content type parameter)
The dups parameter specifies whether duplicate blocks (the same block
occurring multiple times in the requested DAG) will be present in the CAR
response. Useful when a deterministic block order is used.
It accepts two values:
y: Duplicate blocks MUST be sent every time they occur during the DAG walk.n: Duplicate blocks MUST be sent only once.
When set to y, light clients are able to discard blocks after
reading them, removing the need for caching in-memory or on-disk.
Setting to n allows for more efficient data transfer of certain types of
data, but introduces additional resource cost on the receiving end, as each
block needs to be kept around in case its CID appears again.
If the dups parameter is absent from the Accept request header, the
behavior is unspecified. In such cases, a Gateway should respond with dups=n
if it has control over the duplicate status, or without dups parameter if it
does not.
Defaulting to the inclusion of duplicate blocks (dups=y) SHOULD only be
implemented by Gateway systems that exclusively support dups=y and do not
support any other behavior.
A Client MUST not assume any implicit behavior when dups is missing.
If the dups parameter is absent from the Content-Type response header, the
behavior is unspecified, and the CAR response includes an arbitrary list of
blocks. In this unknown state, the client MUST assume duplicates are not sent,
but also MUST ignore duplicates and other unexpected blocks if they are present.
A Gateway MUST always return dups in Content-Type response header
when the duplicate status is known at the time of processing the request.
A Gateway SHOULD not return dups if determining the duplicate status is not
possible at the time of processing the request.
A Gateway MUST NOT include virtual blocks identified by identity CIDs
(multihash with 0x00 code) in CAR responses. This exclusion applies regardless
of their presence in the DAG or the value assigned to the "dups" parameter, as
the raw data is already present in the parent block that links to the identity
CID.
5.5 meta (content type parameter)
The meta parameter allows clients to request the server to include additional metadata about the CAR along with the response body.
The value of this parameter includes both the location where the metadata is given (e.g. eof) as well as the type of data received (e.g. json) separated by a +, to give a value such as meta=eof+json
When the location parameter is set to eof, which is currently the only supported value, the server SHOULD respond with the following response body:
The only supported value for the data type parameter is json. This signifies that the metadata MUST be a JSON object.
This parameter MUST only be used with CAR version=1.
When the parameter is not set or does not equal eof+json, the server SHOULD not add any extra blocks to the response, neither the 0x00 byte nor any metadata.
When meta=eof+json, the JSON object SHOULD conform to the following JSON schema.
The properties object can include any fields that the server would like to implement. The following JSON schema explicitly mentions certain properties fields in order to reach a convention on their definition as they have existing use cases.
