Store

• 1. Property config
  • 1.1. Property store
• 2. Property contents
  • 2.1. Pattern Property Store Object
    • 2.1.1. Property info
      • 2.1.1.1. Property version
      • 2.1.1.2. Property path
      • 2.1.1.3. Property narHash
      • 2.1.1.4. Property narSize
      • 2.1.1.5. Property references
        • 2.1.1.5.1. Store Path
      • 2.1.1.6. Property ca
        • 2.1.1.6.1. Property item 0
        • 2.1.1.6.2. Property Content Address
          • 2.1.1.6.2.1. Property method
          • 2.1.1.6.2.2. Property hash
      • 2.1.1.7. Property storeDir
      • 2.1.1.8. Property deriver
        • 2.1.1.8.1. Property Store Path
        • 2.1.1.8.2. Property item 1
      • 2.1.1.9. Property registrationTime
      • 2.1.1.10. Property ultimate
      • 2.1.1.11. Property signatures
        • 2.1.1.11.1. signatures items
      • 2.1.1.12. Property closureSize
    • 2.1.2. Property contents
      • 2.1.2.1. Property Regular File
        • 2.1.2.1.1. Property type
        • 2.1.2.1.2. Property contents
        • 2.1.2.1.3. Property executable
      • 2.1.2.2. Property Directory
        • 2.1.2.2.1. Property type
        • 2.1.2.2.2. Property entries
          • 2.1.2.2.2.1. Property File System Object
      • 2.1.2.3. Property Symbolic Link
        • 2.1.2.3.1. Property type
        • 2.1.2.3.2. Property target
      • 2.1.2.4. Property type
• 3. Property derivations
  • 3.1. Pattern Property Derivation
    • 3.1.1. Property name
    • 3.1.2. Property version
    • 3.1.3. Property outputs
      • 3.1.3.1. Property Derivation Output
        • 3.1.3.1.1. Property Input-Addressed Output
          • 3.1.3.1.1.1. Property path
        • 3.1.3.1.2. Property Fixed Content-Addressed Output
          • 3.1.3.1.2.1. Property method
          • 3.1.3.1.2.2. Property hash
        • 3.1.3.1.3. Property Floating Content-Addressed Output
          • 3.1.3.1.3.1. Property method
          • 3.1.3.1.3.2. Property hashAlgo
        • 3.1.3.1.4. Property Deferred Output
        • 3.1.3.1.5. Property Impure Output
          • 3.1.3.1.5.1. Property impure
          • 3.1.3.1.5.2. Property method
          • 3.1.3.1.5.3. Property hashAlgo
    • 3.1.4. Property inputs
      • 3.1.4.1. Property srcs
        • 3.1.4.1.1. Store Path
      • 3.1.4.2. Property drvs
        • 3.1.4.2.1. Pattern Property Store Path
          • 3.1.4.2.1.1. Property Output Names
            • 3.1.4.2.1.1.1. Output name
          • 3.1.4.2.1.2. Property Dynamic Outputs
            • 3.1.4.2.1.2.1. Property outputs
            • 3.1.4.2.1.2.2. Property dynamicOutputs
    • 3.1.5. Property system
    • 3.1.6. Property builder
    • 3.1.7. Property args
      • 3.1.7.1. args items
    • 3.1.8. Property env
      • 3.1.8.1. Property additionalProperties
    • 3.1.9. Property structuredAttrs
• 4. Property buildTrace
  • 4.1. Pattern Property ^[A-Za-z0-9+/]{43}=$
    • 4.1.1. Property Build Trace Value
      • 4.1.1.1. Property outPath
      • 4.1.1.2. Property dependentRealisations
        • 4.1.1.2.1. Pattern Property Dependent Store Path
      • 4.1.1.3. Property signatures
        • 4.1.1.3.1. Signature

Title: Store

Description: Experimental JSON representation of a Nix Store.

This schema describes the JSON serialization of a Nix store. We use it for (de)serializing in-memory "dummy stores" used for testing, but in principle the data represented in this schema could live in any type of store.

Warning

This JSON format is currently experimental and subject to change.

1. Property config

Title: Store Configuration

Description: Configuration for the store, including the store directory path.

1.1. Property store

Title: Store Directory

Description: The store directory path (e.g., /nix/store).

2. Property contents

Title: Store Objects

Description: Map of store path base names to store objects.

2.1. Pattern Property Store Object

All properties whose name matches the regular expression ^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+$ (Test) must respect the following conditions

Title: Store Object

2.1.1. Property info

Title: Store Object Info

Description: Metadata about the store object including hash, size, references, etc.

2.1.1.1. Property version

Title: Format version (must be 2)

Description: Must be 2. This is a guard that allows us to continue evolving this format. Here is the rough version history:

• Version 0: .narinfo line-oriented format

• Version 1: Original JSON format, with ugly "r:sha256" inherited from .narinfo format.

• Version 2: Use structured JSON type for ca

Specific value: 2

2.1.1.2. Property path

Title: Store Path

Description: Store path to the given store object.

Note: This field may not be present in all contexts, such as when the path is used as the key and the the store object info the value in map.

2.1.1.3. Property narHash

Title: NAR Hash

Description: Hash of the file system object part of the store object when serialized as a Nix Archive.

Examples:

"sha256-ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0="

"sha512-IEqPxt2oLwoM7XvrjgikFlfBbvRosiioJ5vjMacDwzWW/RXBOxsH+aodO+pXeJygMa2Fx6cd1wNU7GMSOMo0RQ=="

2.1.1.4. Property narSize

Title: NAR Size

Description: Size of the file system object part of the store object when serialized as a Nix Archive.

2.1.1.5. Property references

Title: References

Description: An array of store paths, possibly including this one.

2.1.1.5.1. Store Path

Title: Store Path

Description: A store path identifying a store object.

This schema describes the JSON representation of store paths as used in various Nix JSON APIs.

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 (20 arbitrary bytes become 32 ASCII characters)
• name: The package name and optional version/suffix information

2.1.1.6. Property ca

Title: Content Address

Description: If the store object is content-addressed, this is the content address of this store object's file system object, used to compute its store path. Otherwise (i.e. if it is input-addressed), this is null.

2.1.1.6.1. Property item 0

Specific value: null

2.1.1.6.2. Property Content Address

Title: Content Address

Description: This schema describes the JSON representation of Nix's ContentAddress type, which conveys information about content-addressing store objects.

Note

For current methods of content addressing, this data type is a bit suspicious, because it is neither simply a content address of a file system object (the method is richer), nor simply a content address of a store object (the hash doesn't account for the references). It should thus only be used in contexts where the references are also known / otherwise made tamper-resistant.

2.1.1.6.2.1. Property method

Title: Content-Addressing Method

Description: A string representing the method of content addressing that is chosen.

Valid method strings are:

• flat (provided the contents are a single file)
• nar
• text
• git

Must be one of:

• "flat"
• "nar"
• "text"
• "git"

2.1.1.6.2.2. Property hash

Title: Content Address

Description: This would be the content-address itself.

For all current methods, this is just a content address of the file system object of the store object, as described in the store chapter, and not of the store object as a whole. In particular, the references of the store object are not taken into account with this hash (and currently-supported methods).

Examples:

"sha256-ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0="

"sha512-IEqPxt2oLwoM7XvrjgikFlfBbvRosiioJ5vjMacDwzWW/RXBOxsH+aodO+pXeJygMa2Fx6cd1wNU7GMSOMo0RQ=="

2.1.1.7. Property storeDir

Title: Store Directory

Description: The store directory this store object belongs to (e.g. /nix/store).

2.1.1.8. Property deriver

Title: Deriver

Description: If known, the path to the store derivation from which this store object was produced. Otherwise null.

This is an "impure" field that may not be included in certain contexts.

2.1.1.8.1. Property Store Path

Title: Store Path

Description: A store path identifying a store object.

This schema describes the JSON representation of store paths as used in various Nix JSON APIs.

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 (20 arbitrary bytes become 32 ASCII characters)
• name: The package name and optional version/suffix information

2.1.1.8.2. Property item 1

2.1.1.9. Property registrationTime

Title: Registration Time

Description: If known, when this derivation was added to the store (Unix timestamp). Otherwise null.

This is an "impure" field that may not be included in certain contexts.

2.1.1.10. Property ultimate

Title: Ultimate

Description: Whether this store object is trusted because we built it ourselves, rather than substituted a build product from elsewhere.

This is an "impure" field that may not be included in certain contexts.

2.1.1.11. Property signatures

Title: Signatures

Description: Signatures claiming that this store object is what it claims to be. Not relevant for content-addressed store objects, but useful for input-addressed store objects.

This is an "impure" field that may not be included in certain contexts.

2.1.1.11.1. signatures items

2.1.1.12. Property closureSize

Title: Closure Size

Description: The total size of this store object and every other object in its closure.

This field is not stored at all, but computed by traversing the other fields across all the store objects in a closure.

2.1.2. Property contents

Title: File System Object Contents

Description: The actual file system object contents of this store path.

2.1.2.1. Property Regular File

Title: Regular File

Description: See Regular File in the manual for details.

2.1.2.1.1. Property type

Specific value: "regular"

2.1.2.1.2. Property contents

Description: File contents

2.1.2.1.3. Property executable

Description: Whether the file is executable.

2.1.2.2. Property Directory

Title: Directory

Description: See Directory in the manual for details.

2.1.2.2.1. Property type

Specific value: "directory"

2.1.2.2.2. Property entries

Description: Map of names to nested file system objects (for type=directory)

2.1.2.2.2.1. Property File System Object

Title: File System Object

Description: This schema describes the JSON representation of Nix's File System Object.

The schema is recursive because file system objects contain other file system objects.

2.1.2.3. Property Symbolic Link

Title: Symbolic Link

Description: See Symbolic Link in the manual for details.

2.1.2.3.1. Property type

Specific value: "symlink"

2.1.2.3.2. Property target

Description: Target path of the symlink.

2.1.2.4. Property type

Must be one of:

• "regular"
• "symlink"
• "directory"

3. Property derivations

Title: Derivations

Description: Map of store path base names (always ending in .drv) to derivations.

3.1. Pattern Property Derivation

All properties whose name matches the regular expression ^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+\.drv$ (Test) must respect the following conditions

Title: Derivation

Description: Experimental JSON representation of a Nix derivation (version 4).

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

Warning

This JSON format is currently experimental and subject to change.

3.1.1. Property name

Title: Derivation name

Description: The name of the derivation. Used when calculating store paths for the derivation’s outputs.

3.1.2. Property version

Title: Format version (must be 4)

Description: Must be 4. 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: ATerm format

• Version 1: Original JSON format, with ugly "r:sha256" inherited from ATerm format.

• Version 2: Separate method and hashAlgo fields in output specs

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

• Version 4: Two cleanups, batched together to lesson churn:

  • Reorganize inputs into nested structure (inputs.srcs and inputs.drvs)

  • Use canonical content address JSON format for floating content addressed derivation outputs.

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

Specific value: 4

3.1.3. Property outputs

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

"outputs": {
  "out": {
    "method": "nar",
    "hashAlgo": "sha256",
    "hash": "6fc80dcc62179dbc12fc0b5881275898f93444833d21b89dfe5f7fbcbb1d0d62"
  }
}

3.1.3.1. Property Derivation Output

Title: Derivation Output

Description: A single output of a derivation, with different variants for different output types.

3.1.3.1.1. Property Input-Addressed Output

Title: Input-Addressed Output

Description: The traditional non-fixed-output derivation type. The output path is determined from the derivation itself.

See Input-addressing derivation outputs for more details.

3.1.3.1.1.1. Property path

Title: Output path

Description: The output path determined from the derivation itself.

3.1.3.1.2. Property Fixed Content-Addressed Output

Title: Fixed Content-Addressed Output

Description: The output is content-addressed, and the content-address is fixed in advance.

See Fixed-output content-addressing for more details.

3.1.3.1.2.1. Property method

Title: Content-Addressing Method

Description: Method of content addressing used for this output.

Must be one of:

• "flat"
• "nar"
• "text"
• "git"

3.1.3.1.2.2. Property hash

Title: Expected hash value

Description: The expected content hash.

Examples:

"sha256-ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0="

"sha512-IEqPxt2oLwoM7XvrjgikFlfBbvRosiioJ5vjMacDwzWW/RXBOxsH+aodO+pXeJygMa2Fx6cd1wNU7GMSOMo0RQ=="

3.1.3.1.3. Property Floating Content-Addressed Output

Title: Floating Content-Addressed Output

Description: Floating-output derivations, whose outputs are content addressed, but not fixed, and so the output paths are dynamically calculated from whatever the output ends up being.

See Floating Content-Addressing for more details.

3.1.3.1.3.1. Property method

Title: Content-Addressing Method

Description: Method of content addressing used for this output.

3.1.3.1.3.2. Property hashAlgo

Title: Hash algorithm

Description: What hash algorithm to use for the given method of content-addressing.

Must be one of:

• "blake3"
• "md5"
• "sha1"
• "sha256"
• "sha512"

3.1.3.1.4. Property Deferred Output

Title: Deferred Output

Description: Input-addressed output which depends on a (CA) derivation whose outputs (and thus their content-address are not yet known.

3.1.3.1.5. Property Impure Output

Title: Impure Output

Description: Impure output which is just like a floating content-addressed output, but this derivation runs without sandboxing. As such, we don't record it in the build trace, under the assumption that if we need it again, we should rebuild it, as it might produce something different.

3.1.3.1.5.1. Property impure

Specific value: true

3.1.3.1.5.2. Property method

Title: Content-Addressing Method

Description: How the file system objects will be serialized for hashing.

3.1.3.1.5.3. Property hashAlgo

Title: Hash algorithm

Description: How the serialization will be hashed.

Must be one of:

• "blake3"
• "md5"
• "sha1"
• "sha256"
• "sha512"

3.1.4. Property inputs

Title: Derivation inputs

Description: Input dependencies for the derivation, organized into source paths and derivation dependencies.

3.1.4.1. Property srcs

Title: Input source paths

Description: List of store paths on which this derivation depends.

Example

"srcs": [
  "47y241wqdhac3jm5l7nv0x4975mb1975-separate-debug-info.sh",
  "56d0w71pjj9bdr363ym3wj1zkwyqq97j-fix-pop-var-context-error.patch"
]

3.1.4.1.1. Store Path

Title: Store Path

Description: A store path identifying a store object.

This schema describes the JSON representation of store paths as used in various Nix JSON APIs.

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 (20 arbitrary bytes become 32 ASCII characters)
• name: The package name and optional version/suffix information

3.1.4.2. Property drvs

Title: Input derivations

Description: Mapping of derivation paths to lists of output names they provide.

Example

"drvs": {
  "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.

3.1.4.2.1. Pattern Property Store Path

All properties whose name matches the regular expression ^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+\.drv$ (Test) must respect the following conditions

Title: Store Path

Description: A store path to a derivation, mapped to the outputs of that derivation.

3.1.4.2.1.1. Property Output Names

Title: Output Names

Description: Set of names of derivation outputs to depend on

3.1.4.2.1.1.1. Output name

Title: Output name

Description: Name of the derivation output to depend on

3.1.4.2.1.2. Property Dynamic Outputs

Title: Dynamic Outputs

Description: Experimental feature: dynamic-derivations

This recursive data type allows for depending on outputs of outputs.

3.1.4.2.1.2.1. Property outputs

Title: Output Names

Description: Set of names of derivation outputs to depend on

3.1.4.2.1.2.2. Property dynamicOutputs

Title: Dynamic Outputs

Description: Experimental feature: dynamic-derivations

This recursive data type allows for depending on outputs of outputs.

3.1.5. Property system

Title: Build system type

Description: The system type on which this derivation is to be built (e.g. x86_64-linux).

3.1.6. Property builder

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).

3.1.7. Property args

Title: Builder arguments

Description: Command-line arguments passed to the builder.

3.1.7.1. args items

3.1.8. Property env

Title: Environment variables

Description: Environment variables passed to the builder.

3.1.8.1. Property additionalProperties

3.1.9. Property structuredAttrs

Title: Structured attributes

Description: Structured Attributes, only defined if the derivation contains them. Structured attributes are JSON, and thus embedded as-is.

4. Property buildTrace

Title: Build Trace

Description: Map of output hashes (base64 SHA256) to maps of output names to realisations. Records which outputs have been built and their realisations. See Build Trace for more details.

4.1. Pattern Property ^[A-Za-z0-9+/]{43}=$

All properties whose name matches the regular expression ^[A-Za-z0-9+/]{43}=$ (Test) must respect the following conditions

4.1.1. Property Build Trace Value

Title: Build Trace Value

Description: A build trace entry is a key-value pair. This is the "value" part, describing an output.

4.1.1.1. Property outPath

Title: Output Store Path

Description: The path to the store object that resulted from building this derivation for the given output name.

4.1.1.2. Property dependentRealisations

Title: Underlying Base Build Trace

Description: This is for derived build trace entries to ensure coherence.

Keys are derivation output IDs (same format as the main id field). Values are the store paths that those dependencies resolved to.

As described in the linked section on derived build trace traces, derived build trace entries must be kept in addition and not instead of the underlying base build entries. This is the set of base build trace entries that this derived build trace is derived from. (The set is also a map since this miniature base build trace must be coherent, mapping each key to a single value.)

4.1.1.2.1. Pattern Property Dependent Store Path

All properties whose name matches the regular expression ^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$ (Test) must respect the following conditions

Title: Dependent Store Path

Description: Store path that this dependency resolved to during the build

4.1.1.3. Property signatures

Title: Build Signatures

Description: A set of cryptographic signatures attesting to the authenticity of this build trace entry.

4.1.1.3.1. Signature

Title: Signature

Description: A single cryptographic signature

Examples

Empty store

{
  "buildTrace": {},
  "config": {
    "store": "/nix/store"
  },
  "contents": {},
  "derivations": {}
}

Store with one file

{
  "buildTrace": {},
  "config": {
    "store": "/nix/store"
  },
  "contents": {
    "5hizn7xyyrhxr0k2magvxl5ccvk0ci9n-my-file": {
      "contents": {
        "contents": "asdf",
        "executable": false,
        "type": "regular"
      },
      "info": {
        "ca": {
          "hash": "sha256-f1eduuSIYC1BofXA1tycF79Ai2NSMJQtUErx5DxLYSU=",
          "method": "nar"
        },
        "deriver": null,
        "narHash": "sha256-f1eduuSIYC1BofXA1tycF79Ai2NSMJQtUErx5DxLYSU=",
        "narSize": 120,
        "references": [],
        "registrationTime": null,
        "signatures": [],
        "storeDir": "/nix/store",
        "ultimate": false,
        "version": 2
      }
    }
  },
  "derivations": {}
}

Store with one derivation

{
  "buildTrace": {},
  "config": {
    "store": "/nix/store"
  },
  "contents": {},
  "derivations": {
    "rlqjbbb65ggcx9hy577hvnn929wz1aj0-foo.drv": {
      "args": [],
      "builder": "",
      "env": {},
      "inputs": {
        "drvs": {},
        "srcs": []
      },
      "name": "foo",
      "outputs": {},
      "system": "",
      "version": 4
    }
  }
}