TUF Snapshot Metadata

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://theupdateframework.io/schemas/snapshot-metadata.json",
  "title": "TUF Snapshot Metadata",
  "description": "Schema for The Update Framework (TUF) snapshot metadata document (snapshot.json). The snapshot metadata lists the current version numbers and optional hashes of all targets metadata files in the repository, including the top-level targets.json and all delegated targets metadata. Clients use the snapshot to ensure they have a consistent, atomic view of all metadata and to prevent mix-and-match attacks where an attacker combines metadata from different repository states.",
  "type": "object",
  "required": ["signed", "signatures"],
  "properties": {
    "signed": {
      "$ref": "#/$defs/SnapshotSigned"
    },
    "signatures": {
      "type": "array",
      "description": "List of cryptographic signatures over the canonical JSON encoding of the signed field, produced by keys authorized for the snapshot role.",
      "items": {
        "$ref": "#/$defs/Signature"
      },
      "minItems": 1
    }
  },
  "$defs": {
    "SnapshotSigned": {
      "type": "object",
      "description": "The signed portion of snapshot metadata listing the current versions of all targets metadata files.",
      "required": ["_type", "spec_version", "version", "expires", "meta"],
      "properties": {
        "_type": {
          "type": "string",
          "description": "Type identifier for this metadata document.",
          "const": "snapshot"
        },
        "spec_version": {
          "type": "string",
          "description": "Version of the TUF specification this metadata conforms to.",
          "pattern": "^\\d+\\.\\d+\\.\\d+$",
          "examples": ["1.0.0"]
        },
        "version": {
          "type": "integer",
          "description": "Monotonically increasing version number for this snapshot metadata. Clients reject older versions to prevent rollback attacks.",
          "minimum": 1
        },
        "expires": {
          "type": "string",
          "description": "ISO 8601 UTC datetime after which this snapshot metadata is expired.",
          "format": "date-time"
        },
        "meta": {
          "type": "object",
          "description": "Map of metadata filename to MetaFile descriptor. Must include 'targets.json' and should include all delegated targets metadata files. Keys are filenames relative to the metadata directory.",
          "required": ["targets.json"],
          "additionalProperties": {
            "$ref": "#/$defs/MetaFile"
          },
          "examples": [
            {
              "targets.json": { "version": 3 },
              "unclaimed.json": { "version": 1, "length": 1234, "hashes": { "sha256": "abc123..." } }
            }
          ]
        }
      }
    },
    "MetaFile": {
      "type": "object",
      "description": "A reference to a metadata file recorded in the snapshot, including its version number and optionally its length and hashes.",
      "required": ["version"],
      "properties": {
        "version": {
          "type": "integer",
          "description": "Version number of the referenced metadata file. Clients use this to request the specific version and detect rollback attacks.",
          "minimum": 1
        },
        "length": {
          "type": "integer",
          "description": "Length of the metadata file in bytes. Optional but recommended for detecting size-based attacks.",
          "minimum": 0
        },
        "hashes": {
          "type": "object",
          "description": "Map of hash algorithm to hex-encoded hash digest of the metadata file content. Optional but recommended for additional integrity protection.",
          "properties": {
            "sha256": {
              "type": "string",
              "description": "SHA-256 digest of the metadata file, hex-encoded.",
              "pattern": "^[0-9a-f]{64}$"
            },
            "sha512": {
              "type": "string",
              "description": "SHA-512 digest of the metadata file, hex-encoded.",
              "pattern": "^[0-9a-f]{128}$"
            }
          },
          "additionalProperties": {
            "type": "string",
            "description": "Hex-encoded hash digest for an additional algorithm."
          }
        }
      }
    },
    "Signature": {
      "type": "object",
      "description": "A cryptographic signature over the canonical JSON of the signed field.",
      "required": ["keyid", "sig"],
      "properties": {
        "keyid": {
          "type": "string",
          "description": "ID of the key that produced this signature.",
          "pattern": "^[0-9a-f]{64}$"
        },
        "sig": {
          "type": "string",
          "description": "Hex-encoded signature bytes."
        }
      }
    }
  }
}