"$schema": "http://json-schema.org/draft-04/schema"
"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/derivation-v3.json"
title: Derivation
description: |
  Experimental JSON representation of a Nix derivation (version 3).

  This schema describes the JSON representation of Nix's `Derivation` type.

  > **Warning**
  >
  > This JSON format is currently
  > [**experimental**](@docroot@/development/experimental-features.md#xp-feature-nix-command)
  > and subject to change.

type: object
required:
  - name
  - version
  - outputs
  - inputSrcs
  - inputDrvs
  - system
  - builder
  - args
  - env
properties:
  name:
    type: string
    title: Derivation name
    description: |
      The name of the derivation.
      Used when calculating store paths for the derivation’s outputs.

  version:
    const: 3
    title: Format version (must be 3)
    description: |
      Must be `3`.
      This is a guard that allows us to continue evolving this format.
      The choice of `3` is fairly arbitrary, but corresponds to this informal version:

      - Version 0: A-Term format

      - Version 1: Original JSON format, with ugly `"r:sha256"` inherited from A-Term format.

      - Version 2: Separate `method` and `hashAlgo` fields in output specs

      - Version 3: Drop store dir from store paths, just include base name.

      Note that while this format is experimental, the maintenance of versions is best-effort, and not promised to identify every change.

  outputs:
    type: object
    title: Output specifications
    description: |
     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 as described.

      > **Example**
      >
      > ```json
      > "outputs": {
      >   "out": {
      >     "method": "nar",
      >     "hashAlgo": "sha256",
      >     "hash": "6fc80dcc62179dbc12fc0b5881275898f93444833d21b89dfe5f7fbcbb1d0d62"
      >   }
      > }
      > ```
    additionalProperties:
      "$ref": "#/$defs/output"

  inputSrcs:
    type: array
    title: Input source paths
    description: |
      List of store paths on which this derivation depends.

      > **Example**
      >
      > ```json
      > "inputSrcs": [
      >   "47y241wqdhac3jm5l7nv0x4975mb1975-separate-debug-info.sh",
      >   "56d0w71pjj9bdr363ym3wj1zkwyqq97j-fix-pop-var-context-error.patch"
      > ]
      > ```
    items:
      $ref: "store-path-v1.yaml"

  inputDrvs:
    type: object
    title: Input derivations
    description: |
      Mapping of derivation paths to lists of output names they provide.

      > **Example**
      >
      > ```json
      > "inputDrvs": {
      >   "6lkh5yi7nlb7l6dr8fljlli5zfd9hq58-curl-7.73.0.drv": ["dev"],
      >   "fn3kgnfzl5dzym26j8g907gq3kbm8bfh-unzip-6.0.drv": ["out"]
      > }
      > ```
      >
      > specifies that this derivation depends on the `dev` output of `curl`, and the `out` output of `unzip`.
    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
    title: Build system type
    description: |
      The system type on which this derivation is to be built
      (e.g. `x86_64-linux`).

  builder:
    type: string
    title: Build program path
    description: |
      Absolute path of the program used to perform the build.
      Typically this is the `bash` shell
      (e.g. `/nix/store/r3j288vpmczbl500w6zz89gyfa4nr0b1-bash-4.4-p23/bin/bash`).

  args:
    type: array
    title: Builder arguments
    description: |
      Command-line arguments passed to the `builder`.
    items:
      type: string

  env:
    type: object
    title: Environment variables
    description: |
      Environment variables passed to the `builder`.
    additionalProperties:
      type: string

  structuredAttrs:
    title: Structured attributes
    description: |
      [Structured Attributes](@docroot@/store/derivation/index.md#structured-attrs), only defined if the derivation contains them.
      Structured attributes are JSON, and thus embedded as-is.
    type: object
    additionalProperties: true

"$defs":
  output:
    type: object
    properties:
      path:
        $ref: "store-path-v1.yaml"
        title: Output path
        description: |
          The output path, if known in advance.

      method:
        "$ref": "./content-address-v1.yaml#/$defs/method"
        description: |
          For an output which will be [content addressed](@docroot@/store/derivation/outputs/content-address.md), a string representing the [method](@docroot@/store/store-object/content-address.md) of content addressing that is chosen.
          See the linked original definition for further details.
      hashAlgo:
        title: Hash algorithm
        "$ref": "./hash-v1.yaml#/$defs/algorithm"

      hash:
        type: string
        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"