Merge pull request #14507 from obsidiansystems/derivation-options-json-schema

JSON Schema for `DerivationOptions`

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

@@ -42,6 +42,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

@@ -126,7 +126,8 @@
     - [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)
+    - [Derivation](protocols/json/derivation/index.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.md

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

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

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

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/fixup-json-schema-generated-doc.sed

@@ -12,7 +12,7 @@ s/\\`/`/g
 # As we have more such relative links, more replacements of this nature
 # should appear below.
 s^#/\$defs/\(regular\|symlink\|directory\)^In this schema^g
-s^\(./hash-v1.yaml\)\?#/$defs/algorithm^[JSON format for `Hash`](./hash.html#algorithm)^g
-s^\(./hash-v1.yaml\)^[JSON format for `Hash`](./hash.html)^g
-s^\(./content-address-v1.yaml\)\?#/$defs/method^[JSON format for `ContentAddress`](./content-address.html#method)^g
-s^\(./content-address-v1.yaml\)^[JSON format for `ContentAddress`](./content-address.html)^g
+s^\(./hash-v1.yaml\)\?#/$defs/algorithm^[JSON format for `Hash`](@docroot@/protocols/json/hash.html#algorithm)^g
+s^\(./hash-v1.yaml\)^[JSON format for `Hash`](@docroot@/protocols/json/hash.html)^g
+s^\(./content-address-v1.yaml\)\?#/$defs/method^[JSON format for `ContentAddress`](@docroot@/protocols/json/content-address.html#method)^g
+s^\(./content-address-v1.yaml\)^[JSON format for `ContentAddress`](@docroot@/protocols/json/content-address.html)^g

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

@@ -15,6 +15,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"

doc/manual/source/release-notes/rl-2.32.md

@@ -12,7 +12,7 @@
 
   We ultimately want to rectify this issue with all JSON formats to the extent allowed by our stability promises. To start with, we are changing the JSON format for derivations because the `nix derivation` commands are — in addition to being formally unstable — less widely used than other unstable commands.
 
-  See the documentation on the [JSON format for derivations](@docroot@/protocols/json/derivation.md) for further details.
+  See the documentation on the [JSON format for derivations](@docroot@/protocols/json/derivation/index.md) for further details.
 
 - C API: `nix_get_attr_name_byidx`, `nix_get_attr_byidx` take a `nix_value *` instead of `const nix_value *` [#13987](https://github.com/NixOS/nix/pull/13987)
 

doc/manual/source/store/derivation/index.md

@@ -192,7 +192,7 @@ There are two formats, documented separately:
 
 - The legacy ["ATerm" format](@docroot@/protocols/derivation-aterm.md)
 
-- The experimental, currently under development and changing [JSON format](@docroot@/protocols/json/derivation.md)
+- The experimental, currently under development and changing [JSON format](@docroot@/protocols/json/derivation/index.md)
 
 Every derivation has a canonical choice of encoding used to serialize it to a store object.
 This ensures that there is a canonical [store path] used to refer to the derivation, as described in [Referencing derivations](#derivation-path).

src/json-schema-checks/derivation-options

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

src/json-schema-checks/meson.build

@@ -71,6 +71,18 @@ schemas = [
       'with-signature.json',
     ],
   },
+  {
+    '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

src/nix/derivation-add.md

@@ -13,6 +13,6 @@ a Nix expression evaluates.
 [store derivation]: @docroot@/glossary.md#gloss-store-derivation
 
 `nix derivation add` takes a single derivation in the JSON format.
-See [the manual](@docroot@/protocols/json/derivation.md) for a documentation of this format.
+See [the manual](@docroot@/protocols/json/derivation/index.md) for a documentation of this format.
 
 )""

src/nix/derivation-show.md

@@ -49,7 +49,7 @@ By default, this command only shows top-level derivations, but with
 [store derivation]: @docroot@/glossary.md#gloss-store-derivation
 
 `nix derivation show` outputs a JSON map of [store path]s to derivations in JSON format.
-See [the manual](@docroot@/protocols/json/derivation.md) for a documentation of this format.
+See [the manual](@docroot@/protocols/json/derivation/index.md) for a documentation of this format.
 
 [store path]: @docroot@/store/store-path.md