nixos/nix
1
1
Fork 0
mirror of https://github.com/NixOS/nix.git synced 2025-12-08 18:11:02 +01:00
Code Activity

Introduce --json-format for nix path-info

Browse source 
As discussed today at great length in the Nix meeting, we don't want to
break the format, but we also don't want to impede the improvement of
JSON formats. The solution is to add a new flag for control the output
format.

Note that prior to the release, we may want to replace `--json
--json-format N` with `--json=N`, but this is being left for a separate
PR, as we don't yet have `=` support for CLI flags.
This commit is contained in:
John Ericson 2025-12-03 17:07:00 -05:00
parent 69920f9557
commit 1ad13a1423
36 changed files with 464 additions and 132 deletions
Download patch file Download diff file Expand all files Collapse all files

35
doc/manual/rl-next/json-format-changes.md
View file

@ -6,13 +6,29 @@ issues: []
JSON formats for store path info and derivations have been updated with new versions and structured fields.
## Store Path Info JSON (Version 2)
## Store Path Info JSON
The store path info JSON format has been updated from version 1 to version 2:
`nix path-info --json` now requires a `--json-format` flag to specify the output format version.
Using `--json` without `--json-format` is deprecated and will become an error in a future release.
For now, it defaults to version 1 with a warning, for a smoother migration.
- **Added `version` field**:
### Version 1 (`--json-format 1`)
All store path info JSON now includes `"version": 2`.
This is the legacy format, preserved for backwards compatibility:
- String-based hash values (e.g., `"narHash": "sha256:FePFYIlM..."`)
- String-based content addresses (e.g., `"ca": "fixed:r:sha256:1abc..."`)
- Full store paths in references (e.g., `"/nix/store/abc...-foo"`)
- Now includes `"storeDir"` field at the top level
### Version 2 (`--json-format 2`)
The new structured format with the following changes:
- **Store path base names in references**:
References use store path base names (e.g., `"abc...-foo"`) instead of full paths.
Combined with `storeDir`, the full path can be reconstructed.
- **Structured `ca` field**:
@ -33,7 +49,16 @@ The store path info JSON format has been updated from version 1 to version 2:
Nix currently only produces, and doesn't consume this format.
**Affected command**: `nix path-info --json`
Additionally the following field is added to both formats.
(The `version` tracks breaking changes, and adding fields to outputted JSON is not a breaking change.)
- **`version` field**:
All store path info JSON now includes `"version": <1|2>`.
- **`storeDir` field**:
Top-level `"storeDir"` field contains the store directory path (e.g., `"/nix/store"`).
## Derivation JSON (Version 4)