in-toto Layout

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://in-toto.io/schemas/v1/layout.json",
  "title": "in-toto Layout",
  "description": "Schema for the in-toto Layout metadata document, which defines the expected steps of a software supply chain, the authorized functionaries for each step, and the inspection rules used during verification. A signed Layout is the root of trust for an in-toto supply chain.",
  "type": "object",
  "required": ["_type", "steps", "inspect", "keys", "expires"],
  "properties": {
    "_type": {
      "type": "string",
      "const": "layout",
      "description": "Identifies this metadata document as an in-toto layout."
    },
    "expires": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 date-time string after which this layout is considered expired and verification must fail."
    },
    "readme": {
      "type": "string",
      "description": "Human-readable description of the software supply chain and the purpose of this layout."
    },
    "keys": {
      "type": "object",
      "description": "Dictionary of public keys authorized to sign link metadata for steps in this layout. Keys are key IDs (fingerprints); values are key objects.",
      "additionalProperties": {
        "$ref": "#/$defs/Key"
      }
    },
    "steps": {
      "type": "array",
      "description": "Ordered list of steps that must be performed in the software supply chain. Each step specifies who may perform it and what artifact rules must hold.",
      "items": {
        "$ref": "#/$defs/Step"
      }
    },
    "inspect": {
      "type": "array",
      "description": "List of inspection commands to run during verification. Inspections compute link metadata locally and can apply artifact rules against the combined set of supply chain artifacts.",
      "items": {
        "$ref": "#/$defs/Inspection"
      }
    }
  },
  "$defs": {
    "Key": {
      "type": "object",
      "description": "A public key used to verify signatures on link metadata or on the layout itself.",
      "required": ["keytype", "keyval", "scheme"],
      "properties": {
        "keytype": {
          "type": "string",
          "description": "Algorithm family for this key.",
          "enum": ["rsa", "ed25519", "ecdsa", "rsa-pkcs1v15"]
        },
        "scheme": {
          "type": "string",
          "description": "Signing scheme used with this key, e.g. rsassa-pss-sha256 or ed25519."
        },
        "keyid_hash_algorithms": {
          "type": "array",
          "description": "Hash algorithms used to compute the key ID.",
          "items": {
            "type": "string"
          }
        },
        "keyval": {
          "type": "object",
          "description": "Key material. For asymmetric keys, contains a 'public' property with the PEM-encoded public key.",
          "properties": {
            "public": {
              "type": "string",
              "description": "PEM-encoded public key."
            }
          }
        }
      }
    },
    "Step": {
      "type": "object",
      "description": "A single step in the software supply chain. Specifies who is authorized to perform the step and the artifact rules governing materials and products.",
      "required": ["name", "pubkeys", "expected_materials", "expected_products"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Unique name identifying this step within the layout. Must match the name used in the corresponding link metadata."
        },
        "pubkeys": {
          "type": "array",
          "description": "List of key IDs of functionaries authorized to perform this step and sign its link metadata.",
          "items": {
            "type": "string"
          }
        },
        "expected_command": {
          "type": "array",
          "description": "Optional list of command tokens expected to be run for this step. Verification may warn if the actual command differs.",
          "items": {
            "type": "string"
          }
        },
        "expected_materials": {
          "type": "array",
          "description": "Artifact rules applied to materials recorded in this step's link metadata.",
          "items": {
            "$ref": "#/$defs/ArtifactRule"
          }
        },
        "expected_products": {
          "type": "array",
          "description": "Artifact rules applied to products recorded in this step's link metadata.",
          "items": {
            "$ref": "#/$defs/ArtifactRule"
          }
        },
        "threshold": {
          "type": "integer",
          "minimum": 1,
          "description": "Minimum number of valid link metadata files required from different functionaries for this step to be considered complete.",
          "default": 1
        }
      }
    },
    "Inspection": {
      "type": "object",
      "description": "A verification-time command that is run by the verifier to produce link metadata locally. Allows applying artifact rules over the final supply chain state.",
      "required": ["name", "run", "expected_materials", "expected_products"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Unique name identifying this inspection within the layout."
        },
        "run": {
          "type": "array",
          "description": "Command tokens to execute during the inspection phase of verification.",
          "items": {
            "type": "string"
          }
        },
        "expected_materials": {
          "type": "array",
          "description": "Artifact rules applied to materials recorded by this inspection.",
          "items": {
            "$ref": "#/$defs/ArtifactRule"
          }
        },
        "expected_products": {
          "type": "array",
          "description": "Artifact rules applied to products recorded by this inspection.",
          "items": {
            "$ref": "#/$defs/ArtifactRule"
          }
        }
      }
    },
    "ArtifactRule": {
      "type": "array",
      "description": "A rule that constrains which artifacts (materials or products) are acceptable for a step. Rules are expressed as arrays of tokens following the in-toto artifact rule grammar, e.g. ['MATCH', 'foo', 'WITH', 'PRODUCTS', 'FROM', 'build'].",
      "items": {
        "type": "string"
      },
      "minItems": 1
    }
  }
}