Versioned output like `--json=lix2025` for all json output from Lix #901

New issue

Open

opened 2025-07-07 00:38:17 +00:00 by jade · 1 comment

jade commented

2025-07-07 00:38:17 +00:00

Owner

Why

We believe that the Nix ecosystem should be able to rely on stable APIs, so all machine readable output needs to be able to be versioned so that invocations don't change semantics between releases.

Context

There was a hard decision we made when nix path-info --json had its output format changed in CppNix 2.19. We didn't take the patch because we considered it a regression. However, this is a divergence today between Lix and CppNix and it's not great as it foists our disagreement about what unqualified --json means on the rest of the ecosystem.

We don't care what the output format is in and of itself, the new one is genuinely better! But the way it was deployed caused a small production incident at my work and I'm certain we weren't the only ones.

In this case, we probably could unify with the CppNix output format, since at this point any public tooling has already eaten the breakage, but I can absolutely believe that privately developed tooling has stayed on the old output format, switched to Lix because they don't like breaking changes, and it would then break them.

We're reticent to add JSON output to new commands because it requires committing to the output format being sufficiently extensible to be stable "forever" as a machine readable artifact without an ability to make a v2.

Keeping around a JSON serializer for a long time isn't a big deal. However, we don't have a migration path to move the ecosystem forward while specifying what tools actually mean so that they can gradually transition to a new format without being blocking updating the Nix implementation.

Idea

The fix to this is to have people opt in to having breaking machine-readable output changes.

Proposal: Do something like #607, but for json output editions.

The way this could work is:
--json=nix2024 would be the 2.19 version
--json=nix2023 would be the 2.18 version

Then whoever breaks the API increments the edition of their implementation and other implementations can adopt aliases for the changed version. The default does not change, but the ambiguous behaviour of not specifying it gets deprecated.

This requires buy-in from CppNix to work out, IMO. So cc @roberth about whether a patch to introduce this would be accepted.

The names of the editions can be bikeshed, I am not married to any particular ones.

## Why We believe that the Nix ecosystem should be able to rely on stable APIs, so all machine readable output needs to be able to be versioned so that invocations don't change semantics between releases. ## Context There was a hard decision we made when `nix path-info --json` had its output format changed in CppNix 2.19. We didn't take the patch because we considered it a regression. However, this is a divergence today between Lix and CppNix and it's not great as it foists our disagreement about what unqualified `--json` means on the rest of the ecosystem. We don't care what the output format is in and of itself, the new one is genuinely better! But the way it was deployed caused a small production incident at my work and I'm certain we weren't the only ones. In *this* case, we probably could unify with the CppNix output format, since at this point any *public* tooling has already eaten the breakage, but I can *absolutely* believe that privately developed tooling has stayed on the old output format, switched to Lix because they don't like breaking changes, and it would then break them. We're reticent to add JSON output to new commands because it requires committing to the output format being sufficiently extensible to be stable "forever" as a machine readable artifact *without an ability to make a v2*. Keeping around a JSON serializer for a long time isn't a big deal. However, we don't have a migration path to move the ecosystem forward while specifying what tools actually *mean* so that they can gradually transition to a new format without being blocking updating the Nix implementation. ## Idea The fix to this is to have people *opt in* to having breaking machine-readable output changes. Proposal: Do something like #607, but for json output editions. The way this could work is: `--json=nix2024` would be the 2.19 version `--json=nix2023` would be the 2.18 version Then whoever breaks the API increments the edition *of their implementation* and other implementations can adopt aliases for the changed version. The default does not change, but the ambiguous behaviour of not specifying it gets deprecated. This requires buy-in from CppNix to work out, IMO. So cc @roberth about whether a patch to introduce this would be accepted. The names of the editions can be bikeshed, I am not married to any particular ones.

jade added the

Area/cli

Affects/CppNix

devx

labels

2025-07-07 00:38:17 +00:00

jade added this to the API Versioning project

2025-07-07 00:38:33 +00:00

roberth commented

2025-07-09 20:01:38 +00:00

Member

The Nix team is on board with this; we just discussed it briefly in Nix issue #13423.
We feel like deprecating --json without = is a bit much in terms of UX becoming annoying, but we did discuss adding a notice when the old version becomes a kinda bad default. I think we'll strike a good balance wrt this behavior.

production incident

It was (and still is) an experimental interface, for what it's worth. I think we can all agree that the whole experimental CLI dynamic has not been much of a success. I think this is a good step forward, covering one of the aspects that could otherwise impede blessing it as stable.

The Nix team is on board with this; we just discussed it briefly in [Nix issue #13423](https://github.com/NixOS/nix/issues/13423). We feel like deprecating `--json` without `=` is a bit much in terms of UX becoming annoying, but we did discuss adding a notice when the old version becomes a kinda bad default. I think we'll strike a good balance wrt this behavior. > production incident It was (and still is) an experimental interface, for what it's worth. I think we can all agree that the whole experimental CLI dynamic has not been much of a success. I think this is a good step forward, covering one of the aspects that could otherwise impede blessing it as stable.