So far, we have treated the JSON messages emitted by --message-format=json (docs) to be somewhat stable (with the caveats of adding new fields). However, that stability has been broken at times (see oli-obk/cargo_metadata#240 as an example). We don't have a strategy for how such changes could be made. We should probably come up with some story and documentation for how we manage the compatibility.

This issue is to collect feedback and ideas on how this should be handled and documented.

Note that this somewhat transitively applies to rustc's diagnostic structure. There should probably be a consistent story with both that and cargo's own messages, which may involve consulting with the compiler team.

My thoughts/ideas:

Versioning doesn't work particularly well since introducing a new version that tooling doesn't recognize would cause them to break (and in the debuginfo case, would cause them to unnecessarily to break in most cases since that change only affected the rare projects that would use the string-based types).

We could potentially indicate that types of fields can change between versions, but otherwise meanings of existing fields wouldn't change. But that could be a challenge for deserializers like cargo_metadata since the only choice to stay compatible would be to deserialize to something like serde_json::Value, losing all structure. Or those tools could just accept that type changes would break their tooling.

We could potentially just document that this format is not stable at all, and shed responsibility. An option for tools like cargo_metadata is that they could just do semver-breaking changes periodically.

Another option is to document that the format is stable except in the presence of new opt-in features (like the debuginfo string example). This could make it challenging or impossible to make broader structural changes.