Merge pull request #14493 from obsidiansystems/drv-and-path-info-new-fmts

Modifications to the JSON formats for `Derivation` and `ValidPathInfo`

Author: Ericson2314

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

@@ -0,0 +1,47 @@
+---
+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 (Version 2)
+
+The store path info JSON format has been updated from version 1 to version 2:
+
+- **Added `version` field**:
+
+  All store path info JSON now includes `"version": 2`.
+
+- **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": "base64", "hash": "EMIJ+giQ..."}}`
+  - Still `null` values for input-addressed store objects
+
+Version 1 format is still accepted when reading for backward compatibility.
+
+**Affected command**: `nix path-info --json`
+
+## 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 in store path info (after the new version).
+
+Version 3 and earlier formats are *not* accepted when reading.
+
+**Affected command**: `nix derivation`, namely it's `show` and `add` sub-commands.

doc/manual/source/protocols/json/derivation.md

@@ -1,7 +1,7 @@
-{{#include derivation-v3-fixed.md}}
+{{#include derivation-v4-fixed.md}}
 
 <!-- need to convert YAML to JSON first
 ## Raw Schema
 
-[JSON Schema for Derivation v3](schema/derivation-v3.json)
+[JSON Schema for Derivation v3](schema/derivation-v4.json)
 -->

doc/manual/source/protocols/json/meson.build

@@ -12,8 +12,8 @@ schemas = [
   'hash-v1',
   'content-address-v1',
   'store-path-v1',
-  'store-object-info-v1',
-  'derivation-v3',
+  'store-object-info-v2',
+  'derivation-v4',
   'deriving-path-v1',
   'build-trace-entry-v1',
   'build-result-v1',

doc/manual/source/protocols/json/schema/derivation-v3.yaml renamed to doc/manual/source/protocols/json/schema/derivation-v4.yaml

@@ -1,8 +1,8 @@
 "$schema": "http://json-schema.org/draft-04/schema"
-"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/derivation-v3.json"
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/derivation-v4.json"
 title: Derivation
 description: |
-  Experimental JSON representation of a Nix derivation (version 3).
+  Experimental JSON representation of a Nix derivation (version 4).
 
   This schema describes the JSON representation of Nix's `Derivation` type.
 
@@ -17,8 +17,7 @@ required:
   - name
   - version
   - outputs
-  - inputSrcs
-  - inputDrvs
+  - inputs
   - system
   - builder
   - args
@@ -32,10 +31,10 @@ properties:
       Used when calculating store paths for the derivation’s outputs.
 
   version:
-    const: 3
-    title: Format version (must be 3)
+    const: 4
+    title: Format version (must be 4)
     description: |
-      Must be `3`.
+      Must be `4`.
       This is a guard that allows us to continue evolving this format.
       The choice of `3` is fairly arbitrary, but corresponds to this informal version:
 
@@ -47,6 +46,12 @@ properties:
 
       - Version 3: Drop store dir from store paths, just include base name.
 
+      - Version 4: Two cleanups, batched together to lesson churn:
+
+        - Reorganize inputs into nested structure (`inputs.srcs` and `inputs.drvs`)
+
+        - Use canonical content address JSON format for floating content addressed derivation outputs.
+
       Note that while this format is experimental, the maintenance of versions is best-effort, and not promised to identify every change.
 
   outputs:
@@ -70,47 +75,56 @@ properties:
     additionalProperties:
       "$ref": "#/$defs/output/overall"
 
-  inputSrcs:
-    type: array
-    title: Input source paths
-    description: |
-      List of store paths on which this derivation depends.
-
-      > **Example**
-      >
-      > ```json
-      > "inputSrcs": [
-      >   "47y241wqdhac3jm5l7nv0x4975mb1975-separate-debug-info.sh",
-      >   "56d0w71pjj9bdr363ym3wj1zkwyqq97j-fix-pop-var-context-error.patch"
-      > ]
-      > ```
-    items:
-      $ref: "store-path-v1.yaml"
-
-  inputDrvs:
+  inputs:
     type: object
-    title: Input derivations
+    title: Derivation inputs
     description: |
-      Mapping of derivation paths to lists of output names they provide.
-
-      > **Example**
-      >
-      > ```json
-      > "inputDrvs": {
-      >   "6lkh5yi7nlb7l6dr8fljlli5zfd9hq58-curl-7.73.0.drv": ["dev"],
-      >   "fn3kgnfzl5dzym26j8g907gq3kbm8bfh-unzip-6.0.drv": ["out"]
-      > }
-      > ```
-      >
-      > specifies that this derivation depends on the `dev` output of `curl`, and the `out` output of `unzip`.
-    patternProperties:
-      "^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+\\.drv$":
-        title: Store Path
+      Input dependencies for the derivation, organized into source paths and derivation dependencies.
+    required:
+      - srcs
+      - drvs
+    properties:
+      srcs:
+        type: array
+        title: Input source paths
+        description: |
+          List of store paths on which this derivation depends.
+
+          > **Example**
+          >
+          > ```json
+          > "srcs": [
+          >   "47y241wqdhac3jm5l7nv0x4975mb1975-separate-debug-info.sh",
+          >   "56d0w71pjj9bdr363ym3wj1zkwyqq97j-fix-pop-var-context-error.patch"
+          > ]
+          > ```
+        items:
+          $ref: "store-path-v1.yaml"
+      drvs:
+        type: object
+        title: Input derivations
         description: |
-          A store path to a derivation, mapped to the outputs of that derivation.
-        oneOf:
-        - "$ref": "#/$defs/outputNames"
-        - "$ref": "#/$defs/dynamicOutputs"
+          Mapping of derivation paths to lists of output names they provide.
+
+          > **Example**
+          >
+          > ```json
+          > "drvs": {
+          >   "6lkh5yi7nlb7l6dr8fljlli5zfd9hq58-curl-7.73.0.drv": ["dev"],
+          >   "fn3kgnfzl5dzym26j8g907gq3kbm8bfh-unzip-6.0.drv": ["out"]
+          > }
+          > ```
+          >
+          > specifies that this derivation depends on the `dev` output of `curl`, and the `out` output of `unzip`.
+        patternProperties:
+          "^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+\\.drv$":
+            title: Store Path
+            description: |
+              A store path to a derivation, mapped to the outputs of that derivation.
+            oneOf:
+            - "$ref": "#/$defs/outputNames"
+            - "$ref": "#/$defs/dynamicOutputs"
+        additionalProperties: false
     additionalProperties: false
 
   system:
@@ -189,24 +203,18 @@ properties:
         The output is content-addressed, and the content-address is fixed in advance.
 
         See [Fixed-output content-addressing](@docroot@/store/derivation/outputs/content-address.md#fixed) for more details.
-      type: object
+      "$ref": "./content-address-v1.yaml"
       required:
         - method
-        - hashAlgo
         - hash
       properties:
         method:
-          "$ref": "./content-address-v1.yaml#/$defs/method"
           description: |
             Method of content addressing used for this output.
-        hashAlgo:
-          title: Hash algorithm
-          "$ref": "./hash-v1.yaml#/$defs/algorithm"
         hash:
-          type: string
           title: Expected hash value
           description: |
-            The expected content hash in base-16.
+            The expected content hash.
       additionalProperties: false
 
     caFloating:

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

@@ -1,6 +1,6 @@
-"$schema": "http://json-schema.org/draft-07/schema"
-"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/store-object-info-v1.json"
-title: Store Object Info
+"$schema": "http://json-schema.org/draft-04/schema"
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/store-object-info-v2.json"
+title: Store Object Info v2
 description: |
   Information about a [store object](@docroot@/store/store-object.md).
 
@@ -41,11 +41,27 @@ $defs:
       This is the minimal set of fields that describe what a store object contains.
     type: object
     required:
+      - version
       - narHash
       - narSize
       - references
       - ca
     properties:
+      version:
+        type: integer
+        const: 2
+        title: Format version (must be 2)
+        description: |
+          Must be `2`.
+          This is a guard that allows us to continue evolving this format.
+          Here is the rough version history:
+
+          - Version 0: `.narinfo` line-oriented format
+
+          - Version 1: Original JSON format, with ugly `"r:sha256"` inherited from `.narinfo` format.
+
+          - Version 2: Use structured JSON type for `ca`
+
       path:
         type: string
         title: Store Path
@@ -76,7 +92,10 @@ $defs:
           type: string
 
       ca:
-        type: ["string", "null"]
+        oneOf:
+          - type: "null"
+            const: null
+          - "$ref": "./content-address-v1.yaml"
         title: Content Address
         description: |
           If the store object is [content-addressed](@docroot@/store/store-object/content-address.md),
@@ -91,6 +110,7 @@ $defs:
       In other words, the same store object in different stores could have different values for these impure fields.
     type: object
     required:
+      - version
       - narHash
       - narSize
       - references
@@ -101,6 +121,7 @@ $defs:
       - ultimate
       - signatures
     properties:
+      version: { $ref: "#/$defs/base/properties/version" }
       path: { $ref: "#/$defs/base/properties/path" }
       narHash: { $ref: "#/$defs/base/properties/narHash" }
       narSize: { $ref: "#/$defs/base/properties/narSize" }
@@ -164,6 +185,7 @@ $defs:
       This download information, being specific to how the store object happens to be stored and transferred, is also considered to be non-intrinsic / impure.
     type: object
     required:
+      - version
       - narHash
       - narSize
       - references
@@ -179,6 +201,7 @@ $defs:
       - downloadHash
       - downloadSize
     properties:
+      version: { $ref: "#/$defs/base/properties/version" }
       path: { $ref: "#/$defs/base/properties/path" }
       narHash: { $ref: "#/$defs/base/properties/narHash" }
       narSize: { $ref: "#/$defs/base/properties/narSize" }

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

@@ -1,29 +1,29 @@
-{{#include store-object-info-v1-fixed.md}}
+{{#include store-object-info-v2-fixed.md}}
 
 ## Examples
 
 ### Minimal store object (content-addressed)
 
 ```json
-{{#include schema/store-object-info-v1/pure.json}}
+{{#include schema/store-object-info-v2/pure.json}}
 ```
 
 ### Store object with impure fields
 
 ```json
-{{#include schema/store-object-info-v1/impure.json}}
+{{#include schema/store-object-info-v2/impure.json}}
 ```
 
 ### Minimal store object (empty)
 
 ```json
-{{#include schema/store-object-info-v1/empty_pure.json}}
+{{#include schema/store-object-info-v2/empty_pure.json}}
 ```
 
 ### Store object with all impure fields
 
 ```json
-{{#include schema/store-object-info-v1/empty_impure.json}}
+{{#include schema/store-object-info-v2/empty_impure.json}}
 ```
 
 ### NAR info (minimal)
@@ -41,5 +41,5 @@
 <!-- need to convert YAML to JSON first
 ## Raw Schema
 
-[JSON Schema for Store Object Info v1](schema/store-object-info-v1.json)
+[JSON Schema for Store Object Info v1](schema/store-object-info-v2.json)
 -->