From be2572ed8d0c9dd626462229436ba7aaf2369690 Mon Sep 17 00:00:00 2001 From: John Ericson Date: Tue, 28 Oct 2025 17:16:38 -0400 Subject: [PATCH 1/2] Make `inputDrvs` JSON schema more precise It now captures the stable non-recursive format (just an output set) and the unstable recursive form for dynamic derivations. --- .../protocols/json/schema/derivation-v3.yaml | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/doc/manual/source/protocols/json/schema/derivation-v3.yaml b/doc/manual/source/protocols/json/schema/derivation-v3.yaml index c950b839f..30fddf699 100644 --- a/doc/manual/source/protocols/json/schema/derivation-v3.yaml +++ b/doc/manual/source/protocols/json/schema/derivation-v3.yaml @@ -103,6 +103,13 @@ properties: > ``` > > specifies that this derivation depends on the `dev` output of `curl`, and the `out` output of `unzip`. + additionalProperties: + title: Store Path + description: | + A store path to a derivation, mapped to the outputs of that derivation. + oneOf: + - "$ref": "#/$defs/outputNames" + - "$ref": "#/$defs/dynamicOutputs" system: type: string @@ -167,3 +174,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" From c67966418f99120a31e3d15c58a0aa253abfb151 Mon Sep 17 00:00:00 2001 From: John Ericson Date: Tue, 28 Oct 2025 16:59:35 -0400 Subject: [PATCH 2/2] Create JSON Schema for Store Paths We immediately use this in the JSON schemas for Derivation and Deriving Path, but we cannot yet use it in Store Object Info because those paths *do* include the store dir currently. --- doc/manual/package.nix | 1 + doc/manual/source/SUMMARY.md.in | 1 + doc/manual/source/protocols/json/meson.build | 1 + .../protocols/json/schema/derivation-v3.yaml | 20 ++++++------ .../json/schema/deriving-path-v1.yaml | 2 +- .../protocols/json/schema/store-path-v1 | 1 + .../protocols/json/schema/store-path-v1.yaml | 32 +++++++++++++++++++ .../source/protocols/json/store-path.md | 15 +++++++++ src/json-schema-checks/meson.build | 7 ++++ src/json-schema-checks/package.nix | 1 + src/json-schema-checks/store-path | 1 + 11 files changed, 72 insertions(+), 10 deletions(-) create mode 120000 doc/manual/source/protocols/json/schema/store-path-v1 create mode 100644 doc/manual/source/protocols/json/schema/store-path-v1.yaml create mode 100644 doc/manual/source/protocols/json/store-path.md create mode 120000 src/json-schema-checks/store-path diff --git a/doc/manual/package.nix b/doc/manual/package.nix index 140fa9849..b7c9503ef 100644 --- a/doc/manual/package.nix +++ b/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 diff --git a/doc/manual/source/SUMMARY.md.in b/doc/manual/source/SUMMARY.md.in index abd9422cd..7f3b1a103 100644 --- a/doc/manual/source/SUMMARY.md.in +++ b/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) diff --git a/doc/manual/source/protocols/json/meson.build b/doc/manual/source/protocols/json/meson.build index f79667961..e8546d813 100644 --- a/doc/manual/source/protocols/json/meson.build +++ b/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', ] diff --git a/doc/manual/source/protocols/json/schema/derivation-v3.yaml b/doc/manual/source/protocols/json/schema/derivation-v3.yaml index 30fddf699..3275bcdd9 100644 --- a/doc/manual/source/protocols/json/schema/derivation-v3.yaml +++ b/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,13 +103,15 @@ properties: > ``` > > specifies that this derivation depends on the `dev` output of `curl`, and the `out` output of `unzip`. - additionalProperties: - title: Store Path - description: | - A store path to a derivation, mapped to the outputs of that derivation. - oneOf: - - "$ref": "#/$defs/outputNames" - - "$ref": "#/$defs/dynamicOutputs" + 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 @@ -155,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. diff --git a/doc/manual/source/protocols/json/schema/deriving-path-v1.yaml b/doc/manual/source/protocols/json/schema/deriving-path-v1.yaml index 7fd74941e..11a784d06 100644 --- a/doc/manual/source/protocols/json/schema/deriving-path-v1.yaml +++ b/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. diff --git a/doc/manual/source/protocols/json/schema/store-path-v1 b/doc/manual/source/protocols/json/schema/store-path-v1 new file mode 120000 index 000000000..31e7a6b2a --- /dev/null +++ b/doc/manual/source/protocols/json/schema/store-path-v1 @@ -0,0 +1 @@ +../../../../../../src/libstore-tests/data/store-path \ No newline at end of file diff --git a/doc/manual/source/protocols/json/schema/store-path-v1.yaml b/doc/manual/source/protocols/json/schema/store-path-v1.yaml new file mode 100644 index 000000000..2012aab99 --- /dev/null +++ b/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 diff --git a/doc/manual/source/protocols/json/store-path.md b/doc/manual/source/protocols/json/store-path.md new file mode 100644 index 000000000..02ecc8068 --- /dev/null +++ b/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}} +``` + + diff --git a/src/json-schema-checks/meson.build b/src/json-schema-checks/meson.build index 745fb5ffa..f3e52e544 100644 --- a/src/json-schema-checks/meson.build +++ b/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', diff --git a/src/json-schema-checks/package.nix b/src/json-schema-checks/package.nix index 6a76c8b28..0122b5493 100644 --- a/src/json-schema-checks/package.nix +++ b/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 ./. diff --git a/src/json-schema-checks/store-path b/src/json-schema-checks/store-path new file mode 120000 index 000000000..003b1dbbb --- /dev/null +++ b/src/json-schema-checks/store-path @@ -0,0 +1 @@ +../../src/libstore-tests/data/store-path \ No newline at end of file