mirror of
https://github.com/NixOS/nix.git
synced 2025-12-08 18:11:02 +01:00
1ad13a1423
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.
81 lines
2.9 KiB
Markdown
81 lines
2.9 KiB
Markdown
---
|
|
synopsis: "JSON format changes for store path info and derivations"
|
|
prs: []
|
|
issues: []
|
|
---
|
|
|
|
JSON formats for store path info and derivations have been updated with new versions and structured fields.
|
|
|
|
## Store Path Info JSON
|
|
|
|
`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.
|
|
|
|
### Version 1 (`--json-format 1`)
|
|
|
|
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**:
|
|
|
|
Content address is now a structured JSON object instead of a string:
|
|
|
|
- Old: `"ca": "fixed:r:sha256:1abc..."`
|
|
- New: `"ca": {"method": "nar", "hash": {"algorithm": "sha256", "format": "base16", "hash": "10c209fa..."}}`
|
|
- Still `null` values for input-addressed store objects
|
|
|
|
- **Structured hash fields**:
|
|
|
|
Hash values (`narHash` and `downloadHash`) are now structured JSON objects instead of strings:
|
|
|
|
- Old: `"narHash": "sha256:FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc="`
|
|
- New: `"narHash": {"algorithm": "sha256", "format": "base16", "hash": "15e3c5608946..."}`
|
|
- Same structure applies to `downloadHash` in NAR info contexts
|
|
- The `format` field is always `"base16"` (hexadecimal)
|
|
|
|
Nix currently only produces, and doesn't consume this format.
|
|
|
|
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)
|
|
|
|
The derivation JSON format has been updated from version 3 to version 4:
|
|
|
|
- **Restructured inputs**:
|
|
|
|
Inputs are now nested under an `inputs` object:
|
|
|
|
- Old: `"inputSrcs": [...], "inputDrvs": {...}`
|
|
- New: `"inputs": {"srcs": [...], "drvs": {...}}`
|
|
|
|
- **Consistent content addresses**:
|
|
|
|
Floating content-addressed outputs now use structured JSON format.
|
|
This is the same format as `ca` in store path info (after the new version).
|
|
|
|
Version 3 and earlier formats are *not* accepted when reading.
|
|
|
|
**Affected command**: `nix derivation`, namely its `show` and `add` sub-commands.
|