JSON impl and Schema for DummyStore

doc/manual/package.nix

@@ -47,6 +47,7 @@ mkMesonDerivation (finalAttrs: {
         ../../src/libstore-tests/data/path-info
         ../../src/libstore-tests/data/nar-info
         ../../src/libstore-tests/data/build-result
+        ../../src/libstore-tests/data/dummy-store
         # Too many different types of files to filter for now
         ../../doc/manual
         ./.

doc/manual/source/SUMMARY.md.in

@@ -131,6 +131,7 @@
     - [Deriving Path](protocols/json/deriving-path.md)
     - [Build Trace Entry](protocols/json/build-trace-entry.md)
     - [Build Result](protocols/json/build-result.md)
+    - [Store](protocols/json/store.md)
   - [Serving Tarball Flakes](protocols/tarball-fetcher.md)
   - [Store Path Specification](protocols/store-path.md)
   - [Nix Archive (NAR) Format](protocols/nix-archive/index.md)

doc/manual/source/development/testing.md

@@ -137,6 +137,12 @@ $ _NIX_TEST_ACCEPT=1 meson test nix-store-tests -v
 will regenerate the "golden master" expected result for the `libnixstore` characterisation tests.
 The characterisation tests will mark themselves "skipped" since they regenerated the expected result instead of actually testing anything.
 
+### JSON Schema testing
+
+In `doc/manual/source/protocols/json/` we have a number of manual pages generated from [JSON Schema](https://json-schema.org/).
+That JSON schema is tested against the JSON file test data used in [characterisation tests](#characterisation-testing-unit ) for JSON (de)serialization, in `src/json-schema-checks`.
+Between the JSON (de)serialization testing, and this testing of the same data against the schema, we make sure that the manual, the implementation, and a machine-readable schema are are all in sync.
+
 ### Unit test support libraries
 
 There are headers and code which are not just used to test the library in question, but also downstream libraries.

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

@@ -19,6 +19,7 @@ schemas = [
   'deriving-path-v1',
   'build-trace-entry-v1',
   'build-result-v1',
+  'store-v1',
 ]
 
 schema_files = files()

doc/manual/source/protocols/json/schema/build-trace-entry-v1.yaml

@@ -4,71 +4,97 @@ title: Build Trace Entry
 description: |
   A record of a successful build outcome for a specific derivation output.
 
-  This schema describes the JSON representation of a [build trace entry](@docroot@/store/build-trace.md) entry.
+  This schema describes the JSON representation of a [build trace entry](@docroot@/store/build-trace.md).
 
   > **Warning**
   >
   > This JSON format is currently
   > [**experimental**](@docroot@/development/experimental-features.md#xp-feature-ca-derivations)
   > and subject to change.
-
-type: object
 required:
   - id
   - outPath
   - dependentRealisations
   - signatures
+allOf:
+  - "$ref": "#/$defs/key"
+  - "$ref": "#/$defs/value"
 properties:
-  id:
-    type: string
-    title: Derivation Output ID
-    pattern: "^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$"
+  id: {}
+  outPath: {}
+  dependentRealisations: {}
+  signatures: {}
+additionalProperties: false
+
+"$defs":
+  key:
+    title: Build Trace Key
     description: |
-      Unique identifier for the derivation output that was built.
+      A [build trace entry](@docroot@/store/build-trace.md) is a key-value pair.
+      This is the "key" part, refering to a derivation and output.
+    type: object
+    required:
+      - id
+    properties:
+      id:
+        type: string
+        title: Derivation Output ID
+        pattern: "^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$"
+        description: |
+          Unique identifier for the derivation output that was built.
 
-      Format: `{hash-quotient-drv}!{output-name}`
+          Format: `{hash-quotient-drv}!{output-name}`
 
-      - **hash-quotient-drv**: SHA-256 [hash of the quotient derivation](@docroot@/store/derivation/outputs/input-address.md#hash-quotient-drv).
-        Begins with `sha256:`.
+          - **hash-quotient-drv**: SHA-256 [hash of the quotient derivation](@docroot@/store/derivation/outputs/input-address.md#hash-quotient-drv).
+            Begins with `sha256:`.
 
-      - **output-name**: Name of the specific output (e.g., "out", "dev", "doc")
+          - **output-name**: Name of the specific output (e.g., "out", "dev", "doc")
 
-      Example: `"sha256:ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad!foo"`
+          Example: `"sha256:ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad!foo"`
 
-  outPath:
-    "$ref": "store-path-v1.yaml"
-    title: Output Store Path
+  value:
+    title: Build Trace Value
     description: |
-      The path to the store object that resulted from building this derivation for the given output name.
-
-  dependentRealisations:
+      A [build trace entry](@docroot@/store/build-trace.md) is a key-value pair.
+      This is the "value" part, describing an output.
     type: object
-    title: Underlying Base Build Trace
-    description: |
-      This is for [*derived*](@docroot@/store/build-trace.md#derived) build trace entries to ensure coherence.
+    required:
+      - outPath
+      - dependentRealisations
+      - signatures
+    properties:
+      outPath:
+        "$ref": "store-path-v1.yaml"
+        title: Output Store Path
+        description: |
+          The path to the store object that resulted from building this derivation for the given output name.
 
-      Keys are derivation output IDs (same format as the main `id` field).
-      Values are the store paths that those dependencies resolved to.
+      dependentRealisations:
+        type: object
+        title: Underlying Base Build Trace
+        description: |
+          This is for [*derived*](@docroot@/store/build-trace.md#derived) build trace entries to ensure coherence.
 
-      As described in the linked section on derived build trace traces, derived build trace entries must be kept in addition and not instead of the underlying base build entries.
-      This is the set of base build trace entries that this derived build trace is derived from.
-      (The set is also a map since this miniature base build trace must be coherent, mapping each key to a single value.)
+          Keys are derivation output IDs (same format as the main `id` field).
+          Values are the store paths that those dependencies resolved to.
 
-    patternProperties:
-      "^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$":
-        $ref: "store-path-v1.yaml"
-        title: Dependent Store Path
-        description: Store path that this dependency resolved to during the build
-    additionalProperties: false
+          As described in the linked section on derived build trace traces, derived build trace entries must be kept in addition and not instead of the underlying base build entries.
+          This is the set of base build trace entries that this derived build trace is derived from.
+          (The set is also a map since this miniature base build trace must be coherent, mapping each key to a single value.)
 
-  signatures:
-    type: array
-    title: Build Signatures
-    description: |
-      A set of cryptographic signatures attesting to the authenticity of this build trace entry.
-    items:
-      type: string
-      title: Signature
-      description: A single cryptographic signature
+        patternProperties:
+          "^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$":
+            "$ref": "store-path-v1.yaml"
+            title: Dependent Store Path
+            description: Store path that this dependency resolved to during the build
+        additionalProperties: false
 
-additionalProperties: false
+      signatures:
+        type: array
+        title: Build Signatures
+        description: |
+          A set of cryptographic signatures attesting to the authenticity of this build trace entry.
+        items:
+          type: string
+          title: Signature
+          description: A single cryptographic signature

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

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

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

@@ -0,0 +1,90 @@
+"$schema": "http://json-schema.org/draft-04/schema"
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/store-v1.json"
+title: Store
+description: |
+  Experimental JSON representation of a Nix [Store](@docroot@/store/index.md).
+
+  This schema describes the JSON serialization of a Nix store.
+  We use it for (de)serializing in-memory "dummy stores" used for testing, but in principle the data represented in this schema could live in any type of store.
+
+  > **Warning**
+  >
+  > This JSON format is currently
+  > [**experimental**](@docroot@/development/experimental-features.md#xp-feature-nix-command)
+  > and subject to change.
+
+type: object
+required:
+  - config
+  - contents
+  - derivations
+  - buildTrace
+properties:
+  config:
+    "$ref": "#/$defs/storeConfig"
+
+  contents:
+    type: object
+    title: Store Objects
+    description: |
+      Map of [store path](@docroot@/store/store-path.md) base names to [store objects](@docroot@/store/store-object.md).
+    patternProperties:
+      "^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+$":
+        type: object
+        title: Store Object
+        required:
+          - info
+          - contents
+        properties:
+          info:
+            "$ref": "./store-object-info-v2.yaml#/$defs/impure"
+            title: Store Object Info
+            description: |
+              Metadata about the [store object](@docroot@/store/store-object.md) including hash, size, references, etc.
+          contents:
+            "$ref": "./file-system-object-v1.yaml"
+            title: File System Object Contents
+            description: |
+              The actual [file system object](@docroot@/store/file-system-object.md) contents of this store path.
+        additionalProperties: false
+    additionalProperties: false
+
+  derivations:
+    type: object
+    title: Derivations
+    description: |
+      Map of [store path](@docroot@/store/store-path.md) base names (always ending in `.drv`) to [derivations](@docroot@/store/derivation/index.md).
+    patternProperties:
+      "^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+\\.drv$":
+        "$ref": "./derivation-v4.yaml"
+    additionalProperties: false
+
+  buildTrace:
+    type: object
+    title: Build Trace
+    description: |
+      Map of output hashes (base64 SHA256) to maps of output names to realisations.
+      Records which outputs have been built and their realisations.
+      See [Build Trace](@docroot@/store/build-trace.md) for more details.
+    patternProperties:
+      "^[A-Za-z0-9+/]{43}=$":
+        type: object
+        additionalProperties:
+          "$ref": "./build-trace-entry-v1.yaml#/$defs/value"
+    additionalProperties: false
+
+"$defs":
+  storeConfig:
+    title: Store Configuration
+    description: |
+      Configuration for the store, including the store directory path.
+    type: object
+    required:
+      - store
+    properties:
+      store:
+        type: string
+        title: Store Directory
+        description: |
+          The store directory path (e.g., `/nix/store`).
+    additionalProperties: false

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

@@ -0,0 +1,21 @@
+{{#include store-v1-fixed.md}}
+
+## Examples
+
+### Empty store
+
+```json
+{{#include schema/store-v1/empty.json}}
+```
+
+### Store with one file
+
+```json
+{{#include schema/store-v1/one-flat-file.json}}
+```
+
+### Store with one derivation
+
+```json
+{{#include schema/store-v1/one-derivation.json}}
+```

src/json-schema-checks/meson.build

@@ -212,6 +212,19 @@ schemas += [
   },
 ]
 
+# Dummy store
+schemas += [
+  {
+    'stem' : 'store',
+    'schema' : schema_dir / 'store-v1.yaml',
+    'files' : [
+      'empty.json',
+      'one-flat-file.json',
+      'one-derivation.json',
+    ],
+  },
+]
+
 # Validate each example against the schema
 foreach schema : schemas
   stem = schema['stem']

src/json-schema-checks/package.nix

@@ -30,6 +30,7 @@ mkMesonDerivation (finalAttrs: {
     ../../src/libstore-tests/data/path-info
     ../../src/libstore-tests/data/nar-info
     ../../src/libstore-tests/data/build-result
+    ../../src/libstore-tests/data/dummy-store
     ./.
   ];
 

src/json-schema-checks/store

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

src/libstore-tests/data/dummy-store/empty.json

@@ -0,0 +1,8 @@
+{
+  "buildTrace": {},
+  "config": {
+    "store": "/nix/store"
+  },
+  "contents": {},
+  "derivations": {}
+}

src/libstore-tests/data/dummy-store/one-derivation.json

@@ -0,0 +1,22 @@
+{
+  "buildTrace": {},
+  "config": {
+    "store": "/nix/store"
+  },
+  "contents": {},
+  "derivations": {
+    "rlqjbbb65ggcx9hy577hvnn929wz1aj0-foo.drv": {
+      "args": [],
+      "builder": "",
+      "env": {},
+      "inputs": {
+        "drvs": {},
+        "srcs": []
+      },
+      "name": "foo",
+      "outputs": {},
+      "system": "",
+      "version": 4
+    }
+  }
+}

src/libstore-tests/data/dummy-store/one-flat-file.json

@@ -0,0 +1,38 @@
+{
+  "buildTrace": {},
+  "config": {
+    "store": "/nix/store"
+  },
+  "contents": {
+    "5hizn7xyyrhxr0k2magvxl5ccvk0ci9n-my-file": {
+      "contents": {
+        "contents": "asdf",
+        "executable": false,
+        "type": "regular"
+      },
+      "info": {
+        "ca": {
+          "hash": {
+            "algorithm": "sha256",
+            "format": "base64",
+            "hash": "f1eduuSIYC1BofXA1tycF79Ai2NSMJQtUErx5DxLYSU="
+          },
+          "method": "nar"
+        },
+        "deriver": null,
+        "narHash": {
+          "algorithm": "sha256",
+          "format": "base64",
+          "hash": "f1eduuSIYC1BofXA1tycF79Ai2NSMJQtUErx5DxLYSU="
+        },
+        "narSize": 120,
+        "references": [],
+        "registrationTime": null,
+        "signatures": [],
+        "ultimate": false,
+        "version": 2
+      }
+    }
+  },
+  "derivations": {}
+}