JSON Schema for DerivationOutputs

Progress on #13570

doc/manual/meson.build

@@ -88,7 +88,7 @@ manual = custom_target(
         @0@ @INPUT0@ @CURRENT_SOURCE_DIR@ > @DEPFILE@
         @0@ @INPUT1@ summary @2@ < @CURRENT_SOURCE_DIR@/source/SUMMARY.md.in > @2@/source/SUMMARY.md
         sed -e 's|@version@|@3@|g' < @INPUT2@ > @2@/book.toml
-        @4@ -r -L --include='*.md' @CURRENT_SOURCE_DIR@/ @2@/
+        @4@ -r -L --exclude='*.drv' --include='*.md' @CURRENT_SOURCE_DIR@/ @2@/
         (cd @2@; RUST_LOG=warn @1@ build -d @2@ 3>&2 2>&1 1>&3) | { grep -Fv "because fragment resolution isn't implemented" || :; } 3>&2 2>&1 1>&3
         rm -rf @2@/manual
         mv @2@/html @2@/manual

doc/manual/package.nix

@@ -41,6 +41,7 @@ mkMesonDerivation (finalAttrs: {
         ../../src/libstore-tests/data/content-address
         ../../src/libstore-tests/data/store-path
         ../../src/libstore-tests/data/realisation
+        ../../src/libstore-tests/data/derivation
         ../../src/libstore-tests/data/derived-path
         ../../src/libstore-tests/data/path-info
         ../../src/libstore-tests/data/nar-info

doc/manual/source/SUMMARY.md.in

@@ -125,6 +125,7 @@
     - [Store Path](protocols/json/store-path.md)
     - [Store Object Info](protocols/json/store-object-info.md)
     - [Derivation](protocols/json/derivation.md)
+      - [Derivation Options](protocols/json/derivation-options.md)
     - [Deriving Path](protocols/json/deriving-path.md)
     - [Build Trace Entry](protocols/json/build-trace-entry.md)
     - [Build Result](protocols/json/build-result.md)

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

@@ -0,0 +1,49 @@
+{{#include derivation-options-v1-fixed.md}}
+
+## Examples
+
+### Input-addressed derivations
+
+#### Default options
+
+```json
+{{#include schema/derivation-options-v1/ia/defaults.json}}
+```
+
+#### All options set
+
+```json
+{{#include schema/derivation-options-v1/ia/all_set.json}}
+```
+
+#### Default options (structured attributes)
+
+```json
+{{#include schema/derivation-options-v1/ia/structuredAttrs_defaults.json}}
+```
+
+#### All options set (structured attributes)
+
+```json
+{{#include schema/derivation-options-v1/ia/structuredAttrs_all_set.json}}
+```
+
+### Content-addressed derivations
+
+#### All options set
+
+```json
+{{#include schema/derivation-options-v1/ca/all_set.json}}
+```
+
+#### All options set (structured attributes)
+
+```json
+{{#include schema/derivation-options-v1/ca/structuredAttrs_all_set.json}}
+```
+
+<!-- need to convert YAML to JSON first
+## Raw Schema
+
+[JSON Schema for Derivation Options v1](schema/derivation-options-v1.json)
+-->

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

@@ -14,6 +14,7 @@ schemas = [
   'store-path-v1',
   'store-object-info-v2',
   'derivation-v4',
+  'derivation-options-v1',
   'deriving-path-v1',
   'build-trace-entry-v1',
   'build-result-v1',

doc/manual/source/protocols/json/schema/derivation-options-v1

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

doc/manual/source/protocols/json/schema/derivation-options-v1.yaml

@@ -0,0 +1,242 @@
+"$schema": "http://json-schema.org/draft-04/schema"
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/derivation-options-v1.json"
+title: Derivation Options
+description: |
+  JSON representation of Nix's `DerivationOptions` type.
+
+  This schema describes various build-time options and constraints that can be specified for a derivation.
+
+  > **Warning**
+  >
+  > This JSON format is currently
+  > [**experimental**](@docroot@/development/experimental-features.md#xp-feature-nix-command)
+  > and subject to change.
+
+type: object
+required:
+  - outputChecks
+  - unsafeDiscardReferences
+  - passAsFile
+  - exportReferencesGraph
+  - additionalSandboxProfile
+  - noChroot
+  - impureHostDeps
+  - impureEnvVars
+  - allowLocalNetworking
+  - requiredSystemFeatures
+  - preferLocalBuild
+  - allowSubstitutes
+properties:
+  outputChecks:
+    type: object
+    title: Output Check
+    description: |
+      Constraints on what the derivation's outputs can and cannot reference.
+      Can either apply to all outputs or be specified per output.
+    oneOf:
+      - title: Output Checks For All Outputs
+        description: |
+          Output checks that apply to all outputs of the derivation.
+        required:
+          - forAllOutputs
+        properties:
+          forAllOutputs:
+            "$ref": "#/$defs/outputCheckSpec"
+        additionalProperties: false
+
+      - title: Output Checks Per Output
+        description: |
+          Output checks specified individually for each output.
+        required:
+          - perOutput
+        properties:
+          perOutput:
+            type: object
+            additionalProperties:
+              "$ref": "#/$defs/outputCheckSpec"
+        additionalProperties: false
+
+  unsafeDiscardReferences:
+    type: object
+    title: Unsafe Discard References
+    description: |
+      A map specifying which references should be unsafely discarded from each output.
+      This is generally not recommended and requires special permissions.
+    additionalProperties:
+      type: array
+      items:
+        type: string
+
+  passAsFile:
+    type: array
+    title: Pass As File
+    description: |
+      List of environment variable names whose values should be passed as files rather than directly.
+    items:
+      type: string
+
+  exportReferencesGraph:
+    type: object
+    title: Export References Graph
+    description: |
+      Specify paths whose references graph should be exported to files.
+    additionalProperties:
+      type: array
+      items:
+        "$ref": "deriving-path-v1.yaml"
+
+  additionalSandboxProfile:
+    type: string
+    title: Additional Sandbox Profile
+    description: |
+      Additional sandbox profile directives (macOS specific).
+
+  noChroot:
+    type: boolean
+    title: No Chroot
+    description: |
+      Whether to disable the build sandbox, if allowed.
+
+  impureHostDeps:
+    type: array
+    title: Impure Host Dependencies
+    description: |
+      List of host paths that the build can access.
+    items:
+      type: string
+
+  impureEnvVars:
+    type: array
+    title: Impure Environment Variables
+    description: |
+      List of environment variable names that should be passed through to the build from the calling environment.
+    items:
+      type: string
+
+  allowLocalNetworking:
+    type: boolean
+    title: Allow Local Networking
+    description: |
+      Whether the build should have access to local network (macOS specific).
+
+  requiredSystemFeatures:
+    type: array
+    title: Required System Features
+    description: |
+      List of system features required to build this derivation (e.g., "kvm", "nixos-test").
+    items:
+      type: string
+
+  preferLocalBuild:
+    type: boolean
+    title: Prefer Local Build
+    description: |
+      Whether this derivation should preferably be built locally rather than its outputs substituted.
+
+  allowSubstitutes:
+    type: boolean
+    title: Allow Substitutes
+    description: |
+      Whether substituting from other stores should be allowed for this derivation's outputs.
+
+additionalProperties: false
+
+$defs:
+
+  outputCheckSpec:
+    type: object
+    title: Output Check Specification
+    description: |
+      Constraints on what a specific output can reference.
+    required:
+      - ignoreSelfRefs
+      - maxSize
+      - maxClosureSize
+      - allowedReferences
+      - allowedRequisites
+      - disallowedReferences
+      - disallowedRequisites
+    properties:
+      ignoreSelfRefs:
+        type: boolean
+        title: Ignore Self References
+        description: |
+          Whether references from this output to itself should be ignored when checking references.
+
+      maxSize:
+        type: ["integer", "null"]
+        title: Maximum Size
+        description: |
+          Maximum allowed size of this output in bytes, or null for no limit.
+        minimum: 0
+
+      maxClosureSize:
+        type: ["integer", "null"]
+        title: Maximum Closure Size
+        description: |
+          Maximum allowed size of this output's closure in bytes, or null for no limit.
+        minimum: 0
+
+      allowedReferences:
+        oneOf:
+          - type: array
+            items:
+              "$ref": "#/$defs/drvRef"
+          - type: "null"
+        title: Allowed References
+        description: |
+          If set, the output can only reference paths in this list.
+          If null, no restrictions apply.
+
+      allowedRequisites:
+        oneOf:
+          - type: array
+            items:
+              "$ref": "#/$defs/drvRef"
+          - type: "null"
+        title: Allowed Requisites
+        description: |
+          If set, the output's closure can only contain paths in this list.
+          If null, no restrictions apply.
+
+      disallowedReferences:
+        type: array
+        title: Disallowed References
+        description: |
+          The output must not reference any paths in this list.
+        items:
+          "$ref": "#/$defs/drvRef"
+
+      disallowedRequisites:
+        type: array
+        title: Disallowed Requisites
+        description: |
+          The output's closure must not contain any paths in this list.
+        items:
+          "$ref": "#/$defs/drvRef"
+    additionalProperties: false
+
+  drvRef:
+    # TODO fix bug in checker, should be `oneOf`
+    anyOf:
+      - type: object
+        title: Current derivation Output Reference
+        description: |
+          A reference to a specific output of the current derivation.
+        required:
+          - drvPath
+          - output
+        properties:
+          drvPath:
+            type: string
+            const: "self"
+            title: This derivation
+            description: |
+              Won't be confused for a deriving path
+          output:
+            type: string
+            title: Output Name
+            description: |
+              The name of the output being referenced.
+        additionalProperties: false
+      - "$ref": "deriving-path-v1.yaml"

src/json-schema-checks/derivation-options

@@ -0,0 +1 @@
+../libstore-tests/data/derivation

src/json-schema-checks/meson.build

@@ -63,6 +63,19 @@ schemas = [
       'with-signature.json',
     ],
   },
+  # Derivation options
+  {
+    'stem' : 'derivation-options',
+    'schema' : schema_dir / 'derivation-options-v1.yaml',
+    'files' : [
+      'ia' / 'defaults.json',
+      'ia' / 'all_set.json',
+      'ia' / 'structuredAttrs_defaults.json',
+      'ia' / 'structuredAttrs_all_set.json',
+      'ca' / 'all_set.json',
+      'ca' / 'structuredAttrs_all_set.json',
+    ],
+  },
 ]
 
 # Derivation and Derivation output