diff --git a/doc/manual/rl-next/json-format-changes.md b/doc/manual/rl-next/json-format-changes.md index 009c1639c..ce280a305 100644 --- a/doc/manual/rl-next/json-format-changes.md +++ b/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) diff --git a/doc/manual/source/protocols/json/schema/nar-info-v1 b/doc/manual/source/protocols/json/schema/nar-info-v1 deleted file mode 120000 index ded866b6f..000000000 --- a/doc/manual/source/protocols/json/schema/nar-info-v1 +++ /dev/null @@ -1 +0,0 @@ -../../../../../../src/libstore-tests/data/nar-info \ No newline at end of file diff --git a/doc/manual/source/protocols/json/schema/nar-info-v2 b/doc/manual/source/protocols/json/schema/nar-info-v2 new file mode 120000 index 000000000..cb08fe781 --- /dev/null +++ b/doc/manual/source/protocols/json/schema/nar-info-v2 @@ -0,0 +1 @@ +../../../../../../src/libstore-tests/data/nar-info/json-2 \ No newline at end of file diff --git a/doc/manual/source/protocols/json/schema/store-object-info-v2 b/doc/manual/source/protocols/json/schema/store-object-info-v2 index fc6f5c3f0..36ca7f13d 120000 --- a/doc/manual/source/protocols/json/schema/store-object-info-v2 +++ b/doc/manual/source/protocols/json/schema/store-object-info-v2 @@ -1 +1 @@ -../../../../../../src/libstore-tests/data/path-info \ No newline at end of file +../../../../../../src/libstore-tests/data/path-info/json-2 \ No newline at end of file diff --git a/doc/manual/source/protocols/json/schema/store-object-info-v2.yaml b/doc/manual/source/protocols/json/schema/store-object-info-v2.yaml index 44d9e5eae..fb63795be 100644 --- a/doc/manual/source/protocols/json/schema/store-object-info-v2.yaml +++ b/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. diff --git a/doc/manual/source/protocols/json/store-object-info.md b/doc/manual/source/protocols/json/store-object-info.md index 6a101ab0f..4ad83de00 100644 --- a/doc/manual/source/protocols/json/store-object-info.md +++ b/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}} ```