Merge pull request #14704 from NixOS/version-output

Introduce `--json-format` for `nix path-info`

doc/manual/rl-next/json-format-changes.md

@@ -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)
 

doc/manual/source/protocols/json/schema/nar-info-v1

@@ -1 +0,0 @@
-../../../../../../src/libstore-tests/data/nar-info

doc/manual/source/protocols/json/schema/nar-info-v2

@@ -0,0 +1 @@
+../../../../../../src/libstore-tests/data/nar-info/json-2

doc/manual/source/protocols/json/schema/store-object-info-v2

@@ -1 +1 @@
-../../../../../../src/libstore-tests/data/path-info
+../../../../../../src/libstore-tests/data/path-info/json-2

doc/manual/source/protocols/json/schema/store-object-info-v2.yaml

@@ -63,7 +63,7 @@ $defs:
           - Version 2: Use structured JSON type for `ca`
 
       path:
-        type: string
+        "$ref": "./store-path-v1.yaml"
         title: Store Path
         description: |
           [Store path](@docroot@/store/store-path.md) to the given store object.
@@ -89,7 +89,7 @@ $defs:
         description: |
           An array of [store paths](@docroot@/store/store-path.md), possibly including this one.
         items:
-          type: string
+          "$ref": "./store-path-v1.yaml"
 
       ca:
         oneOf:
@@ -128,7 +128,9 @@ $defs:
       references: { $ref: "#/$defs/base/properties/references" }
       ca: { $ref: "#/$defs/base/properties/ca" }
       deriver:
-        type: ["string", "null"]
+        oneOf:
+          - "$ref": "./store-path-v1.yaml"
+          - type: "null"
         title: Deriver
         description: |
           If known, the path to the [store derivation](@docroot@/glossary.md#gloss-store-derivation) from which this store object was produced.

doc/manual/source/protocols/json/store-object-info.md

@@ -29,13 +29,13 @@
 ### NAR info (minimal)
 
 ```json
-{{#include schema/nar-info-v1/pure.json}}
+{{#include schema/nar-info-v2/pure.json}}
 ```
 
 ### NAR info (with binary cache fields)
 
 ```json
-{{#include schema/nar-info-v1/impure.json}}
+{{#include schema/nar-info-v2/impure.json}}
 ```
 
 <!-- need to convert YAML to JSON first