Store Object Info v2

Title: Store Object Info v2

Typecombining
RequiredNo
Additional propertiesAny type allowed

Description: Information about a store object.

This schema describes the JSON representation of store object metadata as returned by commands like nix path-info --json.

Field Categories

Store object information can come in a few different variations.

Firstly, "impure" fields, which contain non-intrinsic information about the store object, may or may not be included.

Second, binary cache stores have extra non-intrinsic infomation about the store objects they contain.

Thirdly, nix path-info --json --closure-size can compute some extra information about not just the single store object in question, but the store object and its closure.

The impure and NAR fields are grouped into separate variants below. See their descriptions for additional information. The closure fields however as just included as optional fields, to avoid a combinatorial explosion of variants.

1. Property Store Object Info

Title: Store Object Info

Typeobject
RequiredNo
Additional propertiesNot allowed
Defined in#/$defs/base

Description: Basic store object metadata containing only intrinsic properties. This is the minimal set of fields that describe what a store object contains.

PropertyTypePatternTitle/Description
+ versionconstNoFormat version (must be 2)
- pathstringNoStore Path
+ narHashstringNoNAR Hash
+ narSizeintegerNoNAR Size
+ referencesarrayNoReferences
+ caCombinationNoContent Address
+ storeDirstringNoStore Directory

1.1. Property version

Title: Format version (must be 2)

Typeconst
RequiredYes

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

1.2. Property path

Title: Store Path

Typestring
RequiredNo
Defined in./store-path-v1.yaml

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.

Restrictions
Min length34
Must match regular expression^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+$ Test

1.3. Property narHash

Title: NAR Hash

Typestring
RequiredYes
Defined inJSON format for 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=="
Restrictions
Must match regular expression^(blake3|md5|sha1|sha256|sha512)-[A-Za-z0-9+/]+=*$ Test

1.4. Property narSize

Title: NAR Size

Typeinteger
RequiredYes

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

Restrictions
Minimum≥ 0

1.5. Property references

Title: References

Typearray
RequiredYes

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

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
Store PathA store path identifying a store object. ...

1.5.1. Store Path

Title: Store Path

Typestring
RequiredNo
Same definition aspath

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

1.6. Property ca

Title: Content Address

Typecombining
RequiredYes
Additional propertiesAny type allowed

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.

One of(Option)
item 0
Content Address

1.6.1. Property item 0

Typeconst
RequiredNo

Specific value: null

1.6.2. Property Content Address

Title: Content Address

Typeobject
RequiredNo
Additional propertiesNot allowed
Defined inJSON format for ContentAddress

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.

PropertyTypePatternTitle/Description
+ methodenum (of string)NoContent-Addressing Method
+ hashstringNoContent Address
1.6.2.1. Property method

Title: Content-Addressing Method

Typeenum (of string)
RequiredYes
Defined inJSON format for ContentAddress

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

Valid method strings are:

Must be one of:

  • "flat"
  • "nar"
  • "text"
  • "git"
1.6.2.2. Property hash

Title: Content Address

Typestring
RequiredYes
Defined inJSON format for Hash

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=="
Restrictions
Must match regular expression^(blake3|md5|sha1|sha256|sha512)-[A-Za-z0-9+/]+=*$ Test

1.7. Property storeDir

Title: Store Directory

Typestring
RequiredYes

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

2. Property Store Object Info with Impure Fields

Title: Store Object Info with Impure Fields

Typeobject
RequiredNo
Additional propertiesNot allowed
Defined in#/$defs/impure

Description: Store object metadata including impure fields that are not intrinsic properties. In other words, the same store object in different stores could have different values for these impure fields.

PropertyTypePatternTitle/Description
+ versionconstNoFormat version (must be 2)
- pathstringNoStore Path
+ narHashstringNoNAR Hash
+ narSizeintegerNoNAR Size
+ referencesarrayNoReferences
+ caobjectNoContent Address
+ storeDirstringNoStore Directory
+ deriverCombinationNoDeriver
+ registrationTimeinteger or nullNoRegistration Time
+ ultimatebooleanNoUltimate
+ signaturesarray of stringNoSignatures
- closureSizeintegerNoClosure Size

2.1. Property version

Title: Format version (must be 2)

Typeconst
RequiredYes
Defined in#/$defs/base/properties/version

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.2. Property path

Title: Store Path

Typestring
RequiredNo
Defined in#/$defs/base/properties/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.

Restrictions
Min length34
Must match regular expression^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+$ Test

2.3. Property narHash

Title: NAR Hash

Typestring
RequiredYes
Defined in#/$defs/base/properties/narHash

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=="
Restrictions
Must match regular expression^(blake3|md5|sha1|sha256|sha512)-[A-Za-z0-9+/]+=*$ Test

2.4. Property narSize

Title: NAR Size

Typeinteger
RequiredYes
Defined in#/$defs/base/properties/narSize

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

Restrictions
Minimum≥ 0

2.5. Property references

Title: References

Typearray
RequiredYes
Defined in#/$defs/base/properties/references

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

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
Store PathA store path identifying a store object. ...

2.5.1. Store Path

Title: Store Path

Typestring
RequiredNo
Same definition aspath

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.6. Property ca

Title: Content Address

Typecombining
RequiredYes
Additional propertiesAny type allowed
Defined in#/$defs/base/properties/ca

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.

One of(Option)
item 0
Content Address

2.6.1. Property item 0

Typeconst
RequiredNo

Specific value: null

2.6.2. Property Content Address

Title: Content Address

Typeobject
RequiredNo
Additional propertiesNot allowed
Same definition asContent 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.7. Property storeDir

Title: Store Directory

Typestring
RequiredYes
Defined in#/$defs/base/properties/storeDir

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

2.8. Property deriver

Title: Deriver

Typecombining
RequiredYes
Additional propertiesAny type allowed

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.

One of(Option)
Store Path
item 1

2.8.1. Property Store Path

Title: Store Path

Typestring
RequiredNo
Same definition aspath

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.8.2. Property item 1

Typenull
RequiredNo

2.9. Property registrationTime

Title: Registration Time

Typeinteger or null
RequiredYes

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.10. Property ultimate

Title: Ultimate

Typeboolean
RequiredYes

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.11. Property signatures

Title: Signatures

Typearray of string
RequiredYes

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.

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
signatures items-

2.11.1. signatures items

Typestring
RequiredNo

2.12. Property closureSize

Title: Closure Size

Typeinteger
RequiredNo

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.

Restrictions
Minimum≥ 0

3. Property Store Object Info with Impure fields and NAR Info

Title: Store Object Info with Impure fields and NAR Info

Typeobject
RequiredNo
Additional propertiesNot allowed
Defined in#/$defs/narInfo

Description: The store object info in the "binary cache" family of Nix store type contain extra information pertaining to downloads of the store object in question. (This store info is called "NAR info", since the downloads take the form of [Nix Archives](../../store/file-system-object/content-address.md#serial-nix-archive, and the metadata is served in a file with a .narinfo extension.)

This download information, being specific to how the store object happens to be stored and transferred, is also considered to be non-intrinsic / impure.

PropertyTypePatternTitle/Description
+ versionconstNoFormat version (must be 2)
- pathstringNoStore Path
+ narHashstringNoNAR Hash
+ narSizeintegerNoNAR Size
+ referencesarrayNoReferences
+ caobjectNoContent Address
+ storeDirstringNoStore Directory
+ deriverobjectNoDeriver
+ registrationTimeinteger or nullNoRegistration Time
+ ultimatebooleanNoUltimate
+ signaturesarray of stringNoSignatures
- closureSizeintegerNoClosure Size
+ urlstringNoURL
+ compressionstringNoCompression
+ downloadHashstringNoDownload Hash
+ downloadSizeintegerNoDownload Size
- closureDownloadSizeintegerNoClosure Download Size

3.1. Property version

Title: Format version (must be 2)

Typeconst
RequiredYes
Same definition asversion

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

3.2. Property path

Title: Store Path

Typestring
RequiredNo
Same definition aspath

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.

3.3. Property narHash

Title: NAR Hash

Typestring
RequiredYes
Same definition asnarHash

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

3.4. Property narSize

Title: NAR Size

Typeinteger
RequiredYes
Same definition asnarSize

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

3.5. Property references

Title: References

Typearray
RequiredYes
Same definition asreferences

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

3.6. Property ca

Title: Content Address

Typecombining
RequiredYes
Additional propertiesAny type allowed
Same definition asca

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.

3.7. Property storeDir

Title: Store Directory

Typestring
RequiredYes
Same definition asstoreDir

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

3.8. Property deriver

Title: Deriver

Typecombining
RequiredYes
Additional propertiesAny type allowed
Defined in#/$defs/impure/properties/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.

One of(Option)
Store Path
item 1

3.8.1. Property Store Path

Title: Store Path

Typestring
RequiredNo
Same definition aspath

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.8.2. Property item 1

Typenull
RequiredNo

3.9. Property registrationTime

Title: Registration Time

Typeinteger or null
RequiredYes
Defined in#/$defs/impure/properties/registrationTime

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.

3.10. Property ultimate

Title: Ultimate

Typeboolean
RequiredYes
Defined in#/$defs/impure/properties/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.

3.11. Property signatures

Title: Signatures

Typearray of string
RequiredYes
Defined in#/$defs/impure/properties/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.

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
signatures items-

3.11.1. signatures items

Typestring
RequiredNo

3.12. Property closureSize

Title: Closure Size

Typeinteger
RequiredNo
Defined in#/$defs/impure/properties/closureSize

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.

Restrictions
Minimum≥ 0

3.13. Property url

Title: URL

Typestring
RequiredYes

Description: Where to download a compressed archive of the file system objects of this store object.

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

3.14. Property compression

Title: Compression

Typestring
RequiredYes

Description: The compression format that the archive is in.

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

3.15. Property downloadHash

Title: Download Hash

Typestring
RequiredYes
Defined inJSON format for Hash

Description: A digest for the compressed archive itself, as opposed to the data contained within.

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

Examples:

"sha256-ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0="
"sha512-IEqPxt2oLwoM7XvrjgikFlfBbvRosiioJ5vjMacDwzWW/RXBOxsH+aodO+pXeJygMa2Fx6cd1wNU7GMSOMo0RQ=="
Restrictions
Must match regular expression^(blake3|md5|sha1|sha256|sha512)-[A-Za-z0-9+/]+=*$ Test

3.16. Property downloadSize

Title: Download Size

Typeinteger
RequiredYes

Description: The size of the compressed archive itself.

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

Restrictions
Minimum≥ 0

3.17. Property closureDownloadSize

Title: Closure Download Size

Typeinteger
RequiredNo

Description: The total size of the compressed archive itself for this object, and the compressed archive of every object in this object's closure.

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

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

Restrictions
Minimum≥ 0

Examples

Minimal store object (content-addressed)

{
  "ca": {
    "hash": "sha256-EMIJ+giQ/gLIWoxmPKjno3zHZrxbGymgzGGyZvZBIdM=",
    "method": "nar"
  },
  "narHash": "sha256-FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc=",
  "narSize": 34878,
  "references": [
    "g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-bar",
    "n5wkd9frr45pa74if5gpz9j7mifg27fh-foo"
  ],
  "storeDir": "/nix/store",
  "version": 2
}

Store object with impure fields

{
  "ca": {
    "hash": "sha256-EMIJ+giQ/gLIWoxmPKjno3zHZrxbGymgzGGyZvZBIdM=",
    "method": "nar"
  },
  "deriver": "g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-bar.drv",
  "narHash": "sha256-FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc=",
  "narSize": 34878,
  "references": [
    "g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-bar",
    "n5wkd9frr45pa74if5gpz9j7mifg27fh-foo"
  ],
  "registrationTime": 23423,
  "signatures": [
    "asdf",
    "qwer"
  ],
  "storeDir": "/nix/store",
  "ultimate": true,
  "version": 2
}

Minimal store object (empty)

{
  "ca": null,
  "narHash": "sha256-FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc=",
  "narSize": 0,
  "references": [],
  "storeDir": "/nix/store",
  "version": 2
}

Store object with all impure fields

{
  "ca": null,
  "deriver": null,
  "narHash": "sha256-FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc=",
  "narSize": 0,
  "references": [],
  "registrationTime": null,
  "signatures": [],
  "storeDir": "/nix/store",
  "ultimate": false,
  "version": 2
}

NAR info (minimal)

{
  "ca": {
    "hash": "sha256-EMIJ+giQ/gLIWoxmPKjno3zHZrxbGymgzGGyZvZBIdM=",
    "method": "nar"
  },
  "narHash": "sha256-FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc=",
  "narSize": 34878,
  "references": [
    "g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-bar",
    "n5wkd9frr45pa74if5gpz9j7mifg27fh-foo"
  ],
  "storeDir": "/nix/store",
  "version": 2
}

NAR info (with binary cache fields)

{
  "ca": {
    "hash": "sha256-EMIJ+giQ/gLIWoxmPKjno3zHZrxbGymgzGGyZvZBIdM=",
    "method": "nar"
  },
  "compression": "xz",
  "deriver": "g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-bar.drv",
  "downloadHash": "sha256-FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc=",
  "downloadSize": 4029176,
  "narHash": "sha256-FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc=",
  "narSize": 34878,
  "references": [
    "g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-bar",
    "n5wkd9frr45pa74if5gpz9j7mifg27fh-foo"
  ],
  "registrationTime": 23423,
  "signatures": [
    "asdf",
    "qwer"
  ],
  "storeDir": "/nix/store",
  "ultimate": true,
  "url": "nar/1w1fff338fvdw53sqgamddn1b2xgds473pv6y13gizdbqjv4i5p3.nar.xz",
  "version": 2
}