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
nix/doc/manual/rl-next/json-format-changes.md
John Ericson 1ad13a1423 Introduce --json-format for nix path-info 
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.
2025-12-03 22:04:21 -05:00

2.9 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 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.