{ "$schema": "https://json-schema.org/draft-07/schema", "id": "https://diskuv.com/dk/schema/dk-value-1.0.json", "title": "JSON schema for values.json, values.json, *.values.json and *.values.jsonc build files", "definitions": { "producer": { "type": "object", "description": "The human or machine that produces and signs values. The producer provides a form of \"attestation\": a cryptographically verifiable statement (ex. \"the build produced bundle A and object O at time T\").", "additionalProperties": false, "properties": { "application": { "type": "object", "description": "The software application that produced and signed the values.", "properties": { "name": { "type": "string" }, "version": { "type": "string" } } }, "openbsd_signify": { "description": "The signify public key used to verify the distribution's signature.", "type": "object", "additionalProperties": false, "properties": { "public_key": { "description": "The signify public key, in base64 format, including the comment line.", "type": "string" } }, "required": [ "public_key" ] }, "github_slsa_v1_l2": { "description": "GitHub's SLSA v1 Level 2 provider that can attest there is no tampering of values after GitHub Actions finishes. Follow the guide at https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations#generating-artifact-attestations-for-your-builds", "type": "object", "additionalProperties": false, "properties": { "repository": { "description": "The GitHub repository that produced the values. Ex. /", "type": "string" } }, "required": [ "repository" ] }, "github_slsa_v1_l3": { "description": "GitHub's SLSA v1 Level 3 provider that attests there is no tampering of values during a build produced by a known, vetted GitHub Actions script. Follow the guide at https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/increase-security-rating", "type": "object", "additionalProperties": false, "properties": { "organization": { "description": "The GitHub organization that produced the values. Ex. ", "type": "string" }, "repository": { "description": "The GitHub repository that produced the values. Ex. /", "type": "string" }, "signer_repository": { "description": "The re-usable GitHub repository that does the signing. Ex. /", "type": "string" }, "signer_workflow": { "description": "The re-usable GitHub workflow path that does the signing. Ex. //.github/workflows/sign-artifact.yml", "type": "string" } }, "oneOf": [ { "required": [ "organization", "signer_repository" ] }, { "required": [ "repository", "signer_repository" ] }, { "required": [ "organization", "signer_workflow" ] }, { "required": [ "repository", "signer_workflow" ] } ] } }, "anyOf": [ { "required": [ "openbsd_signify" ] }, { "required": [ "github_slsa_v1_l2" ] }, { "required": [ "github_slsa_v1_l3" ] } ] } }, "type": "object", "additionalProperties": false, "properties": { "$schema": { "description": "The JSON schema for dk build system values.json, values.json, *.values.json and *.values.jsonc. Used by VS Code for auto-completions, but otherwise ignored.", "type": "string", "default": "https://github.com/diskuv/dk/raw/refs/heads/V2_5/etc/jsonschema/dk-values.json" }, "schema_version": { "type": "object", "additionalProperties": false, "description": "The version of the value specification that these values conform to.", "properties": { "major": { "type": "integer", "enum": [ 1 ] }, "minor": { "type": "integer", "enum": [ 0 ] } }, "required": [ "major", "minor" ] }, "distributions": { "description": "The distributions defined in this values document", "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "description": "The identifier for the distribution, in the format 'LIBRARY@VERSION'. The identifier must be unique across the value store. The LIBRARY is the part of a package up to, but not including, the first dot (`.`). The VERSION must be a semver 2.0.0 compatible version number as documented by https://semver.org/. Any 'bn-*' semver build metadata will be dropped. Any 'dk-*' metadata is reserved for the build system. The distribution may be called from a MlFront script using the function call '.distribution ()'.", "type": "string" }, "producer": { "$ref": "#/definitions/producer" }, "license": { "type": "object", "description": "The license for the distribution. Model, Gold and Silver permissive licenses from the Blue Oak list (https://blueoakcouncil.org/list) do not prompt for license agreement. Depending on the build system implementation, all other licenses can require acceptance from the user.", "additionalProperties": false, "properties": { "plaintext": { "description": "The plaintext of the license for the distribution.", "type": "string" }, "markdown": { "description": "The markdown text of the license for the distribution.", "type": "string" }, "spdx": { "description": "The SPDX identifier of the license for the distribution from https://spdx.org/licenses/.", "type": "string" } }, "anyOf": [ { "required": [ "plaintext" ] }, { "required": [ "markdown" ] }, { "required": [ "spdx" ] } ] }, "continuations": { "description": "The accepted future continuations of the build keys. A continuation is a new distribution that is a successor to this distribution. Continuations are optional, but if no continuations are specified, the distribution may need to be re-registered with new build keys.", "type": "object", "additionalProperties": false, "properties": { "attestation": { "description": "The attestation document that authorizes the next versions of the build keys. The attestation document is signed by the producer of the continuation and includes the SHA-256 hash of this distribution's ID and the SHA-256 hash of the continuation's ID.", "type": "object", "additionalProperties": false, "properties": { "openbsd_signify": { "description": "The OpenBSD signify attestation (a signature) that proves the continued build keys are authorized.", "type": "object", "additionalProperties": false, "properties": { "signature": { "description": "The signature of the attestation document, in base64 format, including the comment line. The attestation document is the SHA-256 hex-encoded hash of the canonical (ie. whitespace removed) JSON document `{\"1.0\":...,\"1.1\":...,...}`.", "type": "string" } } } }, "required": [ "openbsd_signify" ] }, "continuations_to_sign": { "description": "The next versions of the build keys that are authorized by the attestation. The property names are the next minor version (ie. 1.1) and/or the next major version (ie. 2.0). The property value is the producer. Currently the producer must be a `{\"openbsd_signify\":{\"public_key\":\"...\"}}` object.", "type": "object", "additionalProperties": { "$ref": "#/definitions/producer" }, "properties": {} } } }, "build": { "type": "object", "description": "A description of the build artifacts.", "additionalProperties": false, "properties": { "attestation": { "description": "The attestations that prove the build was performed by the producer. The attested document is the carriage-return-removed values JSON document, and is signed by the producer.", "type": "object", "additionalProperties": false, "properties": { "openbsd_signify": { "description": "The OpenBSD signify attestation (a signature) that proves the build was performed by the producer.", "type": "object", "additionalProperties": false, "properties": { "signature": { "description": "The signature of the attestation document, in base64 format, including the comment line. The attested document is the hex-encoded SHA-256 of the carriage-return-removed values JSON document, including any comments, with an empty, zero-width attestation JSON object `\"openbsd_signify\": {}`.", "type": "string" } } }, "github_slsa_v1_l2": { "description": "GitHub's SLSA v1 Level 2 provider that can attest there is no tampering of values after GitHub Actions finishes. The attested document is the carriage-return-removed values JSON document, including any comments, with an empty, zero-width attestation JSON object `\"github_slsa_v1_l2\": {}`. Follow the guide at https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations#generating-artifact-attestations-for-your-builds", "type": "object", "additionalProperties": false, "properties": { "docs": { "description": "The SLSA v1 Level 2 attestation document as a JSON array encoding of the generated GitHub Actions JSONL attestations.", "type": "array" } } }, "github_slsa_v1_l3": { "description": "GitHub's SLSA v1 Level 3 provider that attests there is no tampering of values during a build produced by a known, vetted GitHub Actions script. The attested document is the carriage-return-removed values JSON document, including any comments, with an empty, zero-width attestation JSON object `\"github_slsa_v1_l3\": {}`. Follow the guide at https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/increase-security-rating", "type": "object", "additionalProperties": false, "properties": { "docs": { "description": "The SLSA v1 Level 3 attestation document as a JSON array encoding of the generated GitHub Actions JSONL attestations.", "type": "array" } } } }, "anyOf": [ { "required": [ "openbsd_signify" ] }, { "required": [ "github_slsa_v1_l2" ] }, { "required": [ "github_slsa_v1_l3" ] } ] }, "build_to_sign": { "description": "The modules and stores that are included in the distribution.", "type": "object", "additionalProperties": false, "properties": { "bundle_id": { "type": "string", "description": "The identifier for the bundle containing the trace and value stores, in the format 'PACKAGE.NAME@VERSION'. The VERSION must be a semver 2.0.0 compatible version number as documented by https://semver.org/. Any 'bn-*' semver build metadata will be dropped. Any 'dk-*' metadata is reserved for the build system." }, "modules": { "type": "array", "items": { "type": "string", "description": "The identifier for the package, in the format 'PACKAGE.NAME@VERSION'. The VERSION must be a semver 2.0.0 compatible version number as documented by https://semver.org/. Any 'bn-*' semver build metadata will be dropped. Any 'dk-*' metadata is reserved for the build system." } }, "producer_accepts": { "type": "array", "description": "The list of licenses the producer has accepted. The list must at least include the direct dependencies of all `packages` (ie. the precommands for each package). Model, Gold and Silver permissive licenses from the Blue Oak list https://blueoakcouncil.org/list are implicitly accepted and should not be listed. Most other licenses, open-source or not, have limits on the producer's redistribution, promotion, or attribution. So if a package uses a license that the producer has not accepted (attribution in documentation, a link to source code, whatever), the build will be rejected.", "items": { "type": "string", "description": "The SPDX identifier of the license from https://spdx.org/licenses/, or the lowercase hex-encoded SHA-256 of the license text." } }, "bundle_canonical": { "type": "string", "description": "The canonical identifier for the bundle, a lowercase hex-encoded SHA-256 of the critical fields of an bundle JSON document." }, "distmeta": { "type": "object", "description": "Transitive distributions, script modules, and \"meta\" values that can define other values (values.json and values.lua).", "additionalProperties": false, "properties": { "traces": { "type": "array", "description": "A snapshot of the tracestore(s) that were created/updated after the distributions' builds completed.", "items": { "type": "object", "description": "The location in the bundle of a tracestore.", "properties": { "tag": { "type": "string", "description": "The compatibility tag of the tracestore, like `cts.1`." }, "path": { "type": "string", "description": "The path within the bundle to the tracestore." } }, "additionalProperties": false, "required": [ "tag", "path" ] } }, "values": { "type": "array", "description": "Snapshots of the distmeta valuestores that were populated after the distributions' builds completed.", "items": { "type": "object", "description": "A zip snapshot of the valuestore that was populated after the distributions' builds completed. Entries in the zipfile must be `./{value_id}` like `./vnmfdhn7lw4wepx2qiunrmgm4o5lx4wwsf2yfj7xyxggkg5kdsltq`.", "additionalProperties": false, "properties": { "path": { "type": "string", "description": "The path within the bundle to the zipped value store." } } } } }, "required": [ "traces", "values" ] }, "package": { "type": "object", "description": "Objects, bundles, assets and asset indexes.", "additionalProperties": false, "properties": { "traces": { "type": "array", "description": "A snapshot of the tracestore(s) that were created/updated after the distributions' builds completed.", "items": { "type": "object", "description": "The location in the bundle of a tracestore.", "properties": { "tag": { "type": "string", "description": "The compatibility tag of the tracestore, like `cts.1`." }, "path": { "type": "string", "description": "The path within the bundle to the tracestore." } }, "additionalProperties": false, "required": [ "tag", "path" ] } }, "values": { "type": "array", "description": "Snapshots of the package valuestores that were populated after the distributions' builds completed.", "items": { "type": "object", "description": "A zip snapshot of the valuestore that was populated after the distributions' builds completed. Entries in the zipfile must be `./{value_id}` like `./vnmfdhn7lw4wepx2qiunrmgm4o5lx4wwsf2yfj7xyxggkg5kdsltq`.", "additionalProperties": false, "properties": { "path": { "type": "string", "description": "The path within the bundle to the zipped value store." } } } } }, "required": [ "traces", "values" ] } }, "required": [ "producer_accepts", "bundle_id", "bundle_canonical", "distmeta", "package", "modules" ] } }, "required": [ "build_to_sign" ] } }, "required": [ "id", "producer", "build" ] } }, "forms": { "description": "The form rules defined in this values document", "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "description": "The identifier for the form rule, in the format 'PACKAGE.NAME@VERSION'. It must be unique across the value store. The PACKAGE is optional if the build system supplies an implicit package, but best practice is to supply it. The VERSION must be a semver 2.0.0 compatible version number as documented by https://semver.org/. Any 'bn-*' semver build metadata will be dropped. Any 'dk-*' metadata is reserved for the build system. The form rule may be called from a MlFront script using the function call '.form ()'.", "type": "string" }, "options": { "type": "object", "description": "A mapping from the JSON document given when invoking the form rule to command line options and variables. The JSON document has an effect on .function.args. Also, the JSON document's top-level fields can be referenced in the .precommands and .function.envmods using the syntax `${PARAM.name}`.", "additionalProperties": false, "properties": { "fields": { "type": "object", "properties": {}, "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "description": "The type of the parameter. Options are: long-opt (ex. --opt stringy_json), short-opt (ex. -o stringy_json), dos-opt (ex. /opt:stringy_json), long-flag (ex. --flag), short-flag (ex. -f), dos-flag (ex. /f) and arg (a positional argument).", "enum": [ "long-opt", "short-opt", "dos-opt", "long-flag", "short-flag", "dos-flag", "arg" ] }, "description": { "type": "string", "description": "A description of the parameter." }, "group": { "type": "integer", "description": "If specified and between 0 and 9, it is the index into the `groups` array." } }, "required": [ "type" ] } }, "groups": { "type": "array", "description": "An optional array of up to 10 groups of leading command line arguments.", "items": { "type": "array", "items": { "type": "string" } }, "maxItems": 10 }, "responsefile": { "type": "object", "description": "If specified, the command line arguments will be written to a temporary file and the form rule executable will be passed a reference to the temporary file. This is useful when the command line arguments are too long for the operating system to handle.", "additionalProperties": false, "properties": { "subpath": { "type": "string", "description": "The literal, relative subpath to a temporary file that will contain the command line arguments. The path must be a subpath (it cannot contain any `..` segments) and does not expand any variables." }, "quoting": { "type": "object", "additionalProperties": false, "properties": { "default": { "type": "string", "description": "The default quoting style to use for arguments in the response file. Options are `windows` and `posix`.", "enum": [ "windows", "posix" ] }, "windows_slots": { "type": "array", "description": "The slots that will always use the 'windows' quoting style.", "items": { "type": "string" } }, "posix_slots": { "type": "array", "description": "The slots that will always use the 'posix' quoting style.", "items": { "type": "string" } } }, "required": [ "default" ] }, "threshold": { "type": "integer", "description": "If specified, the response file will only be created if the command line length exceeds this value." } }, "required": [ "subpath", "quoting" ] }, "document": { "type": "object", "description": "If specified, the form rule will add the full JSON document to the command line.", "additionalProperties": false, "properties": { "type": { "type": "string", "description": "The type of command line option that declares the JSON document on the command line. For example, if `type` is `long-opt` and `name` is `form-file`, then the command line will include `--form-file `.", "enum": [ "long-opt", "short-opt", "dos-opt", "long-flag", "short-flag", "dos-flag", "arg" ] }, "optname": { "type": "string", "description": "The name of the option. Ignored if the `type` is `arg`" } }, "required": [ "type" ] } } }, "precommands": { "description": "The commands used to fetch objects that must be available to execute the form rule. The commands are written in the Value Shell Language (VSL). For example, 'get-object VGKot5hBsd81kMupNCXHaqbhv3huEbxAFMLnpcX2hniwn Release.Agnostic > gcc'.", "type": "object", "additionalProperties": false, "properties": { "sequential": { "description": "Whether the precommands should be executed sequentially. If true (or 1), the precommands are executed one after the other in the order they are defined. If false, 0 or not specified, the precommands may be executed in parallel. Defaults to false.", "oneOf": [ { "type": "boolean" }, { "type": "integer", "enum": [ 0, 1 ] } ] }, "private": { "description": "The commands used to fetch objects that must be available to execute the form rule. The commands are written in the Value Shell Language (VSL). When installing the form rule with an installer value controller, these \"private\" objects are not installed with this form rule's output.", "type": "array", "items": { "type": "string" } }, "public": { "description": "The commands used to fetch objects that must be available to execute the form rule. The commands are written in the Value Shell Language (VSL). When installing the form rule with an installer value controller, these \"public\" objects are installed with this form rule's output. Any \"public\" objects of the \"public\" form rule objects are installed transitively.", "type": "array", "items": { "type": "string" } } } }, "function": { "description": "The command line invocation that will execute the form rule. If no .function is specified, the \"identity\" function which does nothing will be used instead.", "type": "object", "additionalProperties": false, "properties": { "commands": { "description": "One or more command lines. A flat list is the command line arguments for a single command line; a two-level list is a list of command lines. All form rule variables (ex. ${SLOT.Release.Agnostic}) may be used.", "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1 } ] }, "minItems": 1 }, "envmods": { "description": "Environment variables supplied to the executable", "type": "array", "items": { "type": "string" } }, "execution": { "description": "Technical requirements for the machine that will execute the function. The OSFamily and ISA from Bazel's Platform Lexicon (https://github.com/bazelbuild/remote-apis/blob/main/build/bazel/remote/execution/v2/platform.md) may be supported by the build system.", "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } } }, "required": [ "commands" ] }, "outputs": { "type": "object", "properties": { "assets": { "description": "These files will be assigned and validated as output after the form rule executable is finished running.", "type": "array", "items": { "type": "object", "description": "A set of output files produced by the form rule where all of the given [slots] will produce all of the given relative file [paths]. The file paths are relative to the object slot ${SLOT.name}. The object slot is a namespace that may be used to refer to the file from other thunks.", "properties": { "slots": { "type": "array", "items": { "type": "string", "description": "The object slot that the file is placed in. The object slot is a namespace that may be used to refer to the file in other thunks." }, "minItems": 1 }, "paths": { "type": "array", "items": { "type": "string", "description": "The file path relative to the object slot." }, "minItems": 1 } }, "additionalProperties": false, "required": [ "slots", "paths" ] }, "minItems": 1 } } } }, "required": [ "id", "outputs" ] } }, "bundles": { "description": "The assets, possibly remote, defined in this values document. The assets are arranged in \"listings\" that follow the specification in https://diskuv.com/dk/help/latest/manual/DkAssets_Capture-Spec-1/.", "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "description": "The identifier for the bundle, in the format 'PACKAGE.NAME@VERSION'. It must be unique across the value store. The VERSION must be a semver 2.0.0 compatible version number as documented by https://semver.org/. Any 'bn-*' semver build metadata will be dropped. Any 'dk-*' metadata is reserved for the build system. The bundle may be called from a MlFront script using the function call '.bundle ()'.", "type": "string" }, "listing": { "description": "The metadata for the bundle that may be encrypted in future versions of the bundle spec.", "type": "object", "properties": { "origins": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "A local identifier for the origin used to identify the source of each file in the [files] section. More than one file in [files] can come from the same origin." }, "mirrors": { "type": "array", "description": "The base URL of each source site. The base URL combined with the path in the [files] section become the full URL used to download the asset when the file is not cached.", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "name", "mirrors" ] } } } }, "assets": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string", "description": "The name of the origin that is the source of the asset. This field is optional only for canonicalization (comparison purposes); in all other contexts this field is required." }, "path": { "type": "string", "description": "The relative subpath from the origin's base URL." }, "size": { "type": "integer", "description": "The file size of the asset." }, "checksum": { "type": "object", "description": "The checksum of the asset. Prefer 'blake2b256' if possible, or 'sha256' if not possible. 'sha1' is only for compatibility with git.", "properties": { "sha256": { "type": "string", "description": "The SHA-256 checksum of the asset, in lowercase hexadecimal." }, "sha1": { "type": "string", "description": "The SHA-1 checksum of the asset, in lowercase hexadecimal." }, "blake2b256": { "type": "string", "description": "The BLAKE2B-256 checksum of the asset, in lowercase hexadecimal. The BLAKE hashes are not suspectible to length extension attacks." } }, "oneOf": [ { "required": ["sha256"] }, { "required": ["sha1"] }, { "required": ["blake2b256"] } ] }, "indexes": { "type": "array", "description": "Optional indexes that are included at the end of the asset file to speed up access. For example, a zipfile index.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of index. Currently, the only supported type is `zip`." }, "zip": { "type": "object", "description": "Parameters for a zipfile index.", "properties": { "local_offset": { "type": "integer", "description": "The byte offset in the asset file where the zip file local headers start. Defaults to zero (0)." }, "central_offset": { "type": "integer", "description": "The byte offset in the asset file where the zip file central directory starts." }, "central_size": { "type": "integer", "description": "The size in bytes of the zip file central directory." }, "checksum": { "type": "object", "properties": { "blake2b256": { "type": "string", "description": "The BLAKE2B-256 checksum of the asset, in lowercase hexadecimal. The BLAKE hashes are not suspectible to length extension attacks for the central directory at the end of the zip file." } }, "oneOf": [ { "required": ["blake2b256"] } ] } }, "required": [ "central_offset", "central_size" ] } }, "additionalProperties": false, "required": [ "type" ], "oneOf": [ { "required": [ "zip" ] } ] } } }, "required": [ "path", "size", "checksum" ] } } }, "required": [ "id" ] } } }, "required": [ "schema_version" ] }