Realizations¶
Realization resources SHOULD use the media type application/json.
Realization documents MUST be in JSON format
and MUST conform to the realization schema.
Realization documents SHOULD contain one or more realizations. A realization is a mapping from derivation output to a store object. Realization documents SHOULD have exactly one realization for each output of a derivation, but MAY have more than one realization for a derivation output.
Derivation Hashes¶
A realization is identified by its derivation’s hash and an output name.
However, the .drv file’s contents are not directly hashed.
To enable reuse of realizations
even if the input derivations have been modified but produce identical results,
the derivation hashes in a realization document are handled specially.
Fixed Output Derivation Hashes¶
If a derivation is a fixed-output derivation, then the hash is based on the fixed output hash and the store object path. The exact structure of the hash algorithm input is defined by the following syntax:
fixed-hash-input = %s"fixed:out:"
ca-method
hash-algo ":"
1*(2lower-hexdig) ":"
path
ca-method = "" ; flat file, hash by file contents
ca-method =/ %s"r:" ; recursive file, hashed by NAR serialization
ca-method =/ %s"text:" ; a text file, hashed by file contents
hash-algo = %s"md5" / %s"sha1" / %s"sha256" / %s"sha512"
lower-hexdig = DIGIT / %s"a" / %s"b" / %s"c" / %s"d" / %s"e" / %s"f"
See the store path syntax for the path rule.
Floating Output Derivation Hashes¶
If a derivation is not a fixed-output derivation,
then the hash is a normalized version of the .drv file format.
The following transformations are performed:
The input derivations set is cleared.
The input derivations’ outputs are added to the input sources set.
Placeholders are expanded in-place with the store paths used for the input derivations’ outputs.
Then, the hash algorithm is given an input as defined by the following syntax:
floating-hash-input = %s"floating:" drv-name ":" drv-file
drv-name = *(ALPHA / DIGIT / "+" / "-" / "." / "_" / "=")
See the derivation specification for the drv-file rule.
Signatures¶
Each realization SHOULD include one or more signatures, which provide a means for clients to authenticate that a realization is trusted by a particular source.
The only defined signature format is ed25519.
(More formats may be added over time.)
Clients MUST ignore signatures with formats they do not support.
ed25519 uses the Ed25519 signature algorithm.
The publicKey field is Base-64-encoded 32 bytes of a public key.
The signature field is Base-64-encoded 64 bytes of a signature.
The signature is computed for a JSON object encoded using the JSON Canonicalization Scheme.
The schema is defined by the realizationForSignature definition
in the realization JSON schema.
The reference classes in the object MUST be sorted by path,
then by realization/derivationHash/algorithm,
then by realization/derivationHash/digest,
then by realization/outputName.
JSON Schema¶
{
"$schema": "https://json-schema.org/draft-07/schema",
"title": "zb realization document",
"type": "object",
"required": ["derivationHash", "realizations"],
"properties": {
"derivationHash": {
"$ref": "#/definitions/hash",
"description": "The hash of the derivation's equivalence class"
},
"realizations": {
"type": "object",
"propertyNames": {
"$ref": "#/definitions/outputName",
"description": "Derivation output name"
},
"additionalProperties": {
"type": "array",
"items": {"$ref": "#/definitions/realization"}
}
}
},
"definitions": {
"realization": {
"type": "object",
"required": ["outputPath", "referenceClasses"],
"properties": {
"outputPath": {
"$ref": "#/definitions/path",
"description": "The absolute store path of the realized output for the given name"
},
"referenceClasses": {"$ref": "#/definitions/referenceClasses"},
"signatures": {
"type": "array",
"description": "Set of signatures",
"default": [],
"items": {"$ref": "#/definitions/signature"}
}
}
},
"referenceClasses": {
"type": "array",
"description": "A set of other realization outputs referenced by this store object",
"default": [],
"items": {"$ref": "#/definitions/referenceClass"}
},
"referenceClass": {
"type": "object",
"required": ["path", "realization"],
"additionalProperties": false,
"properties": {
"path": {
"$ref": "#/definitions/path",
"description": "The absolute path of the referenced store object"
},
"realization": {
"oneOf": [
{"type": "null"},
{
"type": "object",
"required": ["derivationHash", "outputName"],
"additionalProperties": false,
"properties": {
"derivationHash": {
"$ref": "#/definitions/hash",
"description": "The hash of the referenced derivation equivalence class"
},
"outputName": {
"$ref": "#/definitions/outputName",
"description": "The name of the derivation output"
}
}
}
]
}
}
},
"outputName": {
"type": "string",
"minLength": 1,
"examples": ["out"]
},
"hash": {
"type": "object",
"required": ["algorithm", "digest"],
"additionalProperties": false,
"properties": {
"algorithm": {
"description": "Hash algorithm",
"default": "sha256",
"enum": ["md5", "sha1", "sha256", "sha512"]
},
"digest": {
"$ref": "#/definitions/base64",
"description": "Hash data (Base-64 encoded)"
}
}
},
"signature": {
"type": "object",
"required": ["format", "publicKey", "signature"],
"properties": {
"format": {
"const": "ed25519",
"description": "Signature format (more formats may be added over time)"
},
"publicKey": {
"$ref": "#/definitions/base64",
"description": "Public key (Base-64 encoded)"
},
"signature": {
"$ref": "#/definitions/base64",
"description": "Signature data (Base-64 encoded)"
}
}
},
"realizationForSignature": {
"title": "Signature realization object",
"description": "An object serialized in JCS for computing signatures",
"type": "object",
"additionalProperties": false,
"required": ["derivationHash", "outputName", "outputPath", "referenceClasses"],
"properties": {
"derivationHash": {
"$ref": "#/definitions/hash",
"description": "The hash of the derivation's equivalence class"
},
"outputName": {
"$ref": "#/definitions/outputName",
"description": "Derivation output name"
},
"outputPath": {
"$ref": "#/definitions/path",
"description": "The absolute store path of the realized output for the given name"
},
"referenceClasses": {
"$ref": "#/definitions/referenceClasses",
"$comment": "The reference classes MUST be sorted by path, then by realization/derivationHash/algorithm, then by realization/derivationHash/digest, then by realization/outputName."
}
}
},
"path": {
"type": "string",
"minLength": 1
},
"base64": {
"type": "string",
"pattern": "^([a-zA-Z0-9+/]{4})*[a-zA-Z0-9+/]{2}([a-zA-Z0-9+/=]=|[a-zA-Z0-9+/]{2})$"
}
}
}
