Merge pull request #14405 from obsidiansystems/json-schema-store-path

Create JSON Schema for Store Paths

doc/manual/package.nix

@@ -36,6 +36,7 @@ mkMesonDerivation (finalAttrs: {
         # For example JSON
         ../../src/libutil-tests/data/hash
         ../../src/libstore-tests/data/content-address
+        ../../src/libstore-tests/data/store-path
         ../../src/libstore-tests/data/derived-path
         # Too many different types of files to filter for now
         ../../doc/manual

doc/manual/source/SUMMARY.md.in

@@ -119,6 +119,7 @@
   - [JSON Formats](protocols/json/index.md)
     - [Hash](protocols/json/hash.md)
     - [Content Address](protocols/json/content-address.md)
+    - [Store Path](protocols/json/store-path.md)
     - [Store Object Info](protocols/json/store-object-info.md)
     - [Derivation](protocols/json/derivation.md)
     - [Deriving Path](protocols/json/deriving-path.md)

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

@@ -11,6 +11,7 @@ json_schema_config = files('json-schema-for-humans-config.yaml')
 schemas = [
   'hash-v1',
   'content-address-v1',
+  'store-path-v1',
   'derivation-v3',
   'deriving-path-v1',
 ]

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

@@ -85,7 +85,7 @@ properties:
       > ]
       > ```
     items:
-      type: string
+      $ref: "store-path-v1.yaml"
 
   inputDrvs:
     type: object
@@ -103,6 +103,15 @@ properties:
       > ```
       >
       > 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
 
   system:
     type: string
@@ -148,7 +157,7 @@ properties:
     type: object
     properties:
       path:
-        type: string
+        $ref: "store-path-v1.yaml"
         title: Output path
         description: |
           The output path, if known in advance.
@@ -167,3 +176,28 @@ properties:
         title: Expected hash value
         description: |
           For fixed-output derivations, the expected content hash in base-16.
+
+  outputName:
+    type: string
+    title: Output name
+    description: Name of the derivation output to depend on
+
+  outputNames:
+    type: array
+    title: Output Names
+    description: Set of names of derivation outputs to depend on
+    items:
+      "$ref": "#/$defs/outputName"
+
+  dynamicOutputs:
+    type: object
+    title: Dynamic Outputs
+    description: |
+      **Experimental feature**: [`dynamic-derivations`](@docroot@/development/experimental-features.md#xp-feature-dynamic-derivations)
+
+      This recursive data type allows for depending on outputs of outputs.
+    properties:
+      outputs:
+        "$ref": "#/$defs/outputNames"
+      dynamicOutputs:
+          "$ref": "#/$defs/dynamicOutputs"

doc/manual/source/protocols/json/schema/deriving-path-v1.yaml

@@ -7,7 +7,7 @@ oneOf:
   - title: Constant
     description: |
       See [Constant](@docroot@/store/derivation/index.md#deriving-path-constant) deriving path.
-    type: string
+    $ref: "store-path-v1.yaml"
   - title: Output
     description: |
       See [Output](@docroot@/store/derivation/index.md#deriving-path-output) deriving path.

doc/manual/source/protocols/json/schema/store-path-v1

@@ -0,0 +1 @@
+../../../../../../src/libstore-tests/data/store-path

doc/manual/source/protocols/json/schema/store-path-v1.yaml

@@ -0,0 +1,32 @@
+"$schema": "http://json-schema.org/draft-07/schema"
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/store-path-v1.json"
+title: Store Path
+description: |
+  A [store path](@docroot@/store/store-path.md) identifying a store object.
+
+  This schema describes the JSON representation of store paths as used in various Nix JSON APIs.
+
+  > **Warning**
+  >
+  > This JSON format is currently
+  > [**experimental**](@docroot@/development/experimental-features.md#xp-feature-nix-command)
+  > and subject to change.
+
+  ## Format
+
+  Store paths in JSON are represented as strings containing just the hash and name portion, without the store directory prefix.
+
+  For example: `"g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-foo.drv"`
+
+  (If the store dir is `/nix/store`, then this corresponds to the path `/nix/store/g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-foo.drv`.)
+
+  ## Structure
+
+  The format follows this pattern: `${digest}-${name}`
+
+  - **hash**: Digest rendered in a custom variant of [Base32](https://en.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters)
+  - **name**: The package name and optional version/suffix information
+
+type: string
+pattern: "^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+$"
+minLength: 34

doc/manual/source/protocols/json/store-path.md

@@ -0,0 +1,15 @@
+{{#include store-path-v1-fixed.md}}
+
+## Examples
+
+### Simple store path
+
+```json
+{{#include schema/store-path-v1/simple.json}}
+```
+
+<!--
+## Raw Schema
+
+[JSON Schema for Store Path v1](schema/store-path-v1.json)
+-->

src/json-schema-checks/meson.build

@@ -38,6 +38,13 @@ schemas = [
       'nar.json',
     ],
   },
+  {
+    'stem' : 'store-path',
+    'schema' : schema_dir / 'store-path-v1.yaml',
+    'files' : [
+      'simple.json',
+    ],
+  },
   {
     'stem' : 'derivation',
     'schema' : schema_dir / 'derivation-v3.yaml',

src/json-schema-checks/package.nix

@@ -22,6 +22,7 @@ mkMesonDerivation (finalAttrs: {
     ../../doc/manual/source/protocols/json/schema
     ../../src/libutil-tests/data/hash
     ../../src/libstore-tests/data/content-address
+    ../../src/libstore-tests/data/store-path
     ../../src/libstore-tests/data/derivation
     ../../src/libstore-tests/data/derived-path
     ./.

src/json-schema-checks/store-path

@@ -0,0 +1 @@
+../../src/libstore-tests/data/store-path