mirror of
https://github.com/NixOS/nix.git
synced 2025-12-13 20:41:04 +01:00
61de9222b0
The fact that we were introducing a conversion from the output of `nix path-info` into the input of `builtins.fetchTree` was the deciding factor. We want scripting outputs into inputs like that to be easy. Since JSON strings and objects are trivially distinguishable, we still have the option of introducing the JSON format as an alternative input scheme in the future, should we want to. (The output format would still be SRI in that case, presumably.)
88 lines
3 KiB
Markdown
88 lines
3 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 for map keys and references (e.g., `"/nix/store/abc...-foo"`)
|
|
- Now includes `"storeDir"` field at the top level
|
|
|
|
### Version 2 (`--json-format 2`)
|
|
|
|
The new structured format follows the [JSON guidelines](@docroot@/development/json-guideline.md) with the following changes:
|
|
|
|
- **Nested structure with top-level metadata**:
|
|
|
|
The output is now wrapped in an object with `version`, `storeDir`, and `info` fields:
|
|
|
|
```json
|
|
{
|
|
"version": 2,
|
|
"storeDir": "/nix/store",
|
|
"info": { ... }
|
|
}
|
|
```
|
|
|
|
The map from store bath base names to store object info is nested under the `info` field.
|
|
|
|
- **Store path base names instead of full paths**:
|
|
|
|
Map keys and references use store path base names (e.g., `"abc...-foo"`) instead of full absolute store 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": "sha256-ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0="}`
|
|
- Still `null` values for input-addressed store objects
|
|
|
|
The `hash` field uses the [SRI](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) format like other hashes.
|
|
|
|
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**:
|
|
|
|
Fixed 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.
|