nixos/nix
1
1
Fork 0
mirror of https://github.com/NixOS/nix.git synced 2025-12-11 11:31:03 +01:00
Code Activity
nix/doc/manual/rl-next/json-format-changes.md
John Ericson 61de9222b0 Use SRI hash (strings) as the official JSON format for Hash after all 
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.)
2025-12-08 16:50:25 -05:00

3 KiB
Raw Blame History

synopsis prs issues
JSON format changes for store path info and derivations

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 with the following changes:

  • Nested structure with top-level metadata:

    The output is now wrapped in an object with version, storeDir, and info fields:

    {
  "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 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.