Research-Stack/shared-data/schemas/deepseek-review-receipt.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/allaunthefox/Research-Stack/shared-data/schemas/deepseek-review-receipt.schema.json",
  "title": "DeepSeek Review Receipt",
  "description": "Schema for Ollama-compatible DeepSeek review receipts emitted by 5-Applications/tools-scripts/llm/ollama_deepseek_review_emitter.py. Receipts are paired with a sibling markdown answer file and pin the exact model, endpoint, token usage, and SHA-256 hashes needed to re-validate the review without re-running the model. See 6-Documentation/wiki/DeepSeek-Review-Process.md for the human-readable contract.",
  "type": "object",
  "oneOf": [
    { "$ref": "#/$defs/primaryReceipt" },
    { "$ref": "#/$defs/continuationReceipt" }
  ],
  "$defs": {
    "sha256Hash": {
      "type": "string",
      "pattern": "^sha256:[0-9a-f]{64}$",
      "description": "Lowercase hex SHA-256 digest prefixed with the literal 'sha256:'."
    },
    "isoTimestamp": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 UTC timestamp (e.g. 2026-05-12T03:35:51+00:00)."
    },
    "endpoint": {
      "type": "string",
      "format": "uri",
      "description": "API endpoint that served the review (e.g. https://ollama.com/v1/chat/completions)."
    },
    "model": {
      "type": "string",
      "minLength": 1,
      "description": "Model identifier (e.g. deepseek-v3.2, deepseek-v4-flash)."
    },
    "repoRelativePath": {
      "type": "string",
      "minLength": 1,
      "pattern": "^[^/].*",
      "description": "Repo-relative POSIX path (must not start with '/')."
    },
    "usage": {
      "type": "object",
      "description": "Token usage as reported by the endpoint.",
      "required": ["prompt_tokens", "completion_tokens", "total_tokens"],
      "additionalProperties": false,
      "properties": {
        "prompt_tokens": { "type": "integer", "minimum": 0 },
        "completion_tokens": { "type": "integer", "minimum": 0 },
        "total_tokens": { "type": "integer", "minimum": 0 }
      }
    },
    "primaryReceipt": {
      "type": "object",
      "description": "Primary review receipt: written first, pins context files used to build the prompt.",
      "required": [
        "schema",
        "created_at",
        "model",
        "endpoint",
        "prompt_sha256",
        "answer_sha256",
        "usage",
        "context_files",
        "answer_path"
      ],
      "additionalProperties": false,
      "properties": {
        "schema": { "const": "ollama_deepseek_review_receipt_v1" },
        "created_at": { "$ref": "#/$defs/isoTimestamp" },
        "model": { "$ref": "#/$defs/model" },
        "endpoint": { "$ref": "#/$defs/endpoint" },
        "prompt_sha256": { "$ref": "#/$defs/sha256Hash" },
        "answer_sha256": { "$ref": "#/$defs/sha256Hash" },
        "usage": { "$ref": "#/$defs/usage" },
        "context_files": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": { "$ref": "#/$defs/repoRelativePath" },
          "description": "Repo-relative paths to every file that participated in the review prompt context."
        },
        "answer_path": {
          "allOf": [
            { "$ref": "#/$defs/repoRelativePath" },
            { "pattern": "\\.md$" }
          ],
          "description": "Repo-relative path to the answer markdown."
        }
      }
    },
    "continuationReceipt": {
      "type": "object",
      "description": "Continuation receipt: emitted when a primary review was truncated and was continued by a separate request.",
      "required": [
        "schema",
        "created_at",
        "model",
        "endpoint",
        "prompt_sha256",
        "answer_sha256",
        "usage",
        "previous_answer_path",
        "answer_path"
      ],
      "additionalProperties": false,
      "properties": {
        "schema": { "const": "ollama_deepseek_review_continuation_receipt_v1" },
        "created_at": { "$ref": "#/$defs/isoTimestamp" },
        "model": { "$ref": "#/$defs/model" },
        "endpoint": { "$ref": "#/$defs/endpoint" },
        "prompt_sha256": { "$ref": "#/$defs/sha256Hash" },
        "answer_sha256": { "$ref": "#/$defs/sha256Hash" },
        "usage": { "$ref": "#/$defs/usage" },
        "previous_answer_path": {
          "allOf": [
            { "$ref": "#/$defs/repoRelativePath" },
            { "pattern": "\\.md$" }
          ],
          "description": "Repo-relative path to the answer being continued."
        },
        "answer_path": {
          "allOf": [
            { "$ref": "#/$defs/repoRelativePath" },
            { "pattern": "\\.md$" }
          ],
          "description": "Repo-relative path to the answer markdown produced by this continuation."
        },
        "message_keys": {
          "type": "array",
          "uniqueItems": true,
          "items": { "type": "string", "minLength": 1 },
          "description": "Field names returned alongside 'content' by the continuation endpoint (e.g. role, content, reasoning)."
        }
      }
    }
  }
}