Merge pull request #14425 from obsidiansystems/json-schema-build-trace

JSON Schema for build trace entry

doc/manual/source/SUMMARY.md.in

@@ -126,6 +126,7 @@
     - [Store Object Info](protocols/json/store-object-info.md)
     - [Derivation](protocols/json/derivation.md)
     - [Deriving Path](protocols/json/deriving-path.md)
+    - [Build Trace Entry](protocols/json/build-trace-entry.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/protocols/json/build-trace-entry.md

@@ -0,0 +1,27 @@
+{{#include build-trace-entry-v1-fixed.md}}
+
+## Examples
+
+### Simple build trace entry
+
+```json
+{{#include schema/build-trace-entry-v1/simple.json}}
+```
+
+### Build trace entry with dependencies
+
+```json
+{{#include schema/build-trace-entry-v1/with-dependent-realisations.json}}
+```
+
+### Build trace entry with signature
+
+```json
+{{#include schema/build-trace-entry-v1/with-signature.json}}
+```
+
+<!--
+## Raw Schema
+
+[JSON Schema for Build Trace Entry v1](schema/build-trace-entry-v1.json)
+-->

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

@@ -15,6 +15,7 @@ schemas = [
   'store-object-info-v1',
   'derivation-v3',
   'deriving-path-v1',
+  'build-trace-entry-v1',
 ]
 
 schema_files = files()

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

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

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

@@ -0,0 +1,74 @@
+"$schema": "http://json-schema.org/draft-04/schema"
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/build-trace-entry-v1.json"
+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.
+
+  > **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
+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}`
+
+      - **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")
+
+      Example: `"sha256:ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad!foo"`
+
+  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.
+
+  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.
+
+      Keys are derivation output IDs (same format as the main `id` field).
+      Values are the store paths that those dependencies resolved to.
+
+      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.)
+
+    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
+
+  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
+
+additionalProperties: false

doc/manual/source/store/build-trace.md

@@ -29,7 +29,7 @@ And even in that case, a different result doesn't mean the original entry was a
 As such, the decision of whether to trust a counterparty's build trace is a fundamentally subject policy choice.
 Build trace entries are typically *signed* in order to enable arbitrary public-key-based trust polices.
 
-## Derived build traces
+## Derived build traces {#derived}
 
 Implementations that wish to memoize the above may also keep additional *derived* build trace entries that do map unresolved derivations.
 But if they do so, they *must* also keep the underlying base entries with resolved derivation keys around.