Merge pull request #9348 from obsidiansystems/json-formats

Document JSON formats

src/libstore/globals.hh

@@ -635,7 +635,7 @@ public:
 
           - the store object has been signed using a key in the trusted keys list
           - the [`require-sigs`](#conf-require-sigs) option has been set to `false`
-          - the store object is [output-addressed](@docroot@/glossary.md#gloss-output-addressed-store-object)
+          - the store object is [content-addressed](@docroot@/glossary.md#gloss-content-addressed-store-object)
         )",
         {"binary-cache-public-keys"}};
 

src/nix/derivation-add.md

@@ -9,10 +9,11 @@ Store derivations are used internally by Nix. They are store paths with
 extension `.drv` that represent the build-time dependency graph to which
 a Nix expression evaluates.
 
-[store derivation]: ../../glossary.md#gloss-store-derivation
 
-The JSON format is documented under the [`derivation show`] command.
+[store derivation]: @docroot@/glossary.md#gloss-store-derivation
 
-[`derivation show`]: ./nix3-derivation-show.md
+`nix derivation add` takes a single derivation in the following format:
+
+{{#include ../../json/derivation.md}}
 
 )""

src/nix/derivation-show.md

@@ -5,8 +5,6 @@ R""(
 * Show the [store derivation] that results from evaluating the Hello
   package:
 
-  [store derivation]: ../../glossary.md#gloss-store-derivation
-
   ```console
   # nix derivation show nixpkgs#hello
   {
@@ -48,62 +46,12 @@ a Nix expression evaluates.
 By default, this command only shows top-level derivations, but with
 `--recursive`, it also shows their dependencies.
 
-The JSON output is a JSON object whose keys are the store paths of the
-derivations, and whose values are a JSON object with the following
-fields:
+[store derivation]: @docroot@/glossary.md#gloss-store-derivation
 
-* `name`: The name of the derivation. This is used when calculating the
-  store paths of the derivation's outputs.
+`nix derivation show` outputs a JSON map of [store path]s to derivations in the following format:
 
-* `outputs`: Information about the output paths of the
-  derivation. This is a JSON object with one member per output, where
-  the key is the output name and the value is a JSON object with these
-  fields:
+[store path]: @docroot@/glossary.md#gloss-store-path
 
-  * `path`: The output path.
-  * `hashAlgo`: For fixed-output derivations, the hashing algorithm
-    (e.g. `sha256`), optionally prefixed by `r:` if `hash` denotes a
-    NAR hash rather than a flat file hash.
-  * `hash`: For fixed-output derivations, the expected content hash in
-    base-16.
-
-  Example:
-
-  ```json
-  "outputs": {
-    "out": {
-      "path": "/nix/store/2543j7c6jn75blc3drf4g5vhb1rhdq29-source",
-      "hashAlgo": "r:sha256",
-      "hash": "6fc80dcc62179dbc12fc0b5881275898f93444833d21b89dfe5f7fbcbb1d0d62"
-    }
-  }
-  ```
-
-* `inputSrcs`: A list of store paths on which this derivation depends.
-
-* `inputDrvs`: A JSON object specifying the derivations on which this
-  derivation depends, and what outputs of those derivations. For
-  example,
-
-  ```json
-  "inputDrvs": {
-    "/nix/store/6lkh5yi7nlb7l6dr8fljlli5zfd9hq58-curl-7.73.0.drv": ["dev"],
-    "/nix/store/fn3kgnfzl5dzym26j8g907gq3kbm8bfh-unzip-6.0.drv": ["out"]
-  }
-  ```
-
-  specifies that this derivation depends on the `dev` output of
-  `curl`, and the `out` output of `unzip`.
-
-* `system`: The system type on which this derivation is to be built
-  (e.g. `x86_64-linux`).
-
-* `builder`: The absolute path of the program to be executed to run
-  the build. Typically this is the `bash` shell
-  (e.g. `/nix/store/r3j288vpmczbl500w6zz89gyfa4nr0b1-bash-4.4-p23/bin/bash`).
-
-* `args`: The command-line arguments passed to the `builder`.
-
-* `env`: The environment passed to the `builder`.
+{{#include ../../json/derivation.md}}
 
 )""