Canonical JSON

[sudo-bmitch]

The spec currently recommends canonical JSON. That has the following requirement:

The members production in object must consist of keys in lexicographically sorted order.

However, a majority of the implementations use Go's encoding/json package which outputs fields in the order they are included in the struct. Should the spec be updated to align with the common behavior, and call out the OCI provided Go structs as the recommended order of the fields?

[tianon]

I'd honestly just axe that whole section -- JSON isn't supposed to be order-dependent (even though it is in practice).

[sudo-bmitch]

I have an ideal goal of reproducible JSON, even if it doesn't follow the official canonical spec. Reproducible images today, when implemented, often depend on using the same builder, sometimes even the same version of that builder. If we can get to the point of different tools being able to reproduce each other's output, that would improve security in the ecosystem, detecting issues not just with a build host, but an issue with the build tooling itself. I'm hoping the spec can give those implementations a way to interoperate.

[tianon]

If we say our structs are the "canonical order", then 1) we need to evaluate all our structs to decide if we "like" their ordering and 2) decide what to do with fields we don't specify (yet?), which are valid per the spec. I don't think the benefits are worthwhile here -- if users want "reproducible" images, they'll need to choose an order, and "sorted" order is much saner and more well-supported in general than "the arbitrary order of the structs in the image-spec repo" (which in some languages/tools will be impossible to enforce/adhere to).

See golang/go#63397 (comment) for some related discussion in the Go context specifically (in the encoding/json/v2 pre-proposal discussion).

[sudo-bmitch]

If we say our structs are the "canonical order", then 1) we need to evaluate all our structs to decide if we "like" their ordering

They've been widely used for a long time, so I think there's implicit agreement from the community with the current order.

and 2) decide what to do with fields we don't specify (yet?), which are valid per the spec.

I'm not sure those matter for the reproducibility issue. New fields would get added as needed, with a location decided at the time of the PR, likely with omitempty. Anyone using a new field is intentionally non-reproducible with older tools that do not use the new field. And anyone that adds a custom field is similarly non-reproducible with other tools that don't have those same custom fields.

I don't think the benefits are worthwhile here -- if users want "reproducible" images, they'll need to choose an order, and "sorted" order is much saner and more well-supported in general than "the arbitrary order of the structs in the image-spec repo" (which in some languages/tools will be impossible to enforce/adhere to).

I agree that sorted is saner, and an ideal I'd like to get to. But from the current tooling, it's largely not done, so I'm looking to document the existing state of the ecosystem.

See golang/go#63397 (comment) for some related discussion in the Go context specifically (in the encoding/json/v2 pre-proposal discussion).

If the json/v2 makes sorted struct entries easy to implement, then I'd be in favor to change the advice back to remove the exception for field ordering when that's used in the ecosystem. We could even make that an implementers note now to encourage a future migration.