{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://mlsysbook.ai/schemas/release.json",
  "title": "MLSysBook release artifact",
  "description": "Canonical shape of releases/<project>-<id>/release.json across all MLSysBook publishable artifacts. Tier A includes per-file hashes; Tier B does not.",
  "type": "object",
  "required": [
    "release_schema_version",
    "project",
    "tier",
    "release_id",
    "release_hash",
    "schema_version",
    "git_sha",
    "created_at",
    "input_paths",
    "metadata"
  ],
  "additionalProperties": false,
  "properties": {
    "release_schema_version": {
      "type": "string",
      "description": "Version of THIS schema. Bumped when release.json shape changes."
    },
    "project": {
      "type": "string",
      "description": "Short project identifier, e.g. 'staffml', 'tinytorch', 'book-vol1'.",
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "tier": {
      "type": "string",
      "enum": ["A", "B"],
      "description": "Adoption tier. A = citable (Merkle), B = lite (flat hash)."
    },
    "release_id": {
      "type": "string",
      "description": "Human-meaningful semver, e.g. '0.1.0' or '1.2.3-rc1'.",
      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$"
    },
    "release_hash": {
      "type": "string",
      "description": "Full hex digest binding the release to its input bytes.",
      "pattern": "^[0-9a-f]{16,}$"
    },
    "schema_version": {
      "type": "string",
      "description": "Project-internal schema version (e.g. vault question schema)."
    },
    "previous_release_id": {
      "type": ["string", "null"],
      "description": "Previous release_id of this project (for changelog continuity)."
    },
    "git_sha": {
      "type": "string",
      "description": "Git commit SHA the release was built from.",
      "pattern": "^[0-9a-f]{7,40}$"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 UTC timestamp of release artifact emission."
    },
    "input_paths": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Paths (relative to repo root) hashed to produce release_hash."
    },
    "files": {
      "type": "array",
      "description": "Tier A only: per-file hashes for partial verification.",
      "items": {
        "type": "object",
        "required": ["path", "hash"],
        "properties": {
          "path": {"type": "string"},
          "hash": {"type": "string", "pattern": "^[0-9a-f]{16,}$"}
        }
      }
    },
    "description": {
      "type": "string",
      "description": "One-line operator-supplied summary, mirrored from workflow input."
    },
    "metadata": {
      "type": "object",
      "description": "Project-specific metrics (page_count, question_count, module_count, etc.)."
    }
  }
}