Schemas

Every payload the CLI and the MCP server accept or return is validated against a schema. The six schemas below are generated from the single zod source of truth in core/model.ts by scripts/gen-schemas.ts, and continuous integration fails the build if the checked-in files under schemas/ ever drift from that source. What you read here is exactly what the package enforces at runtime.

Config

Machine-local settings resolved before every command: your GitHub login, default repository, custom skills directory, and whether checks may run build or test scripts.

{
  "$ref": "#/definitions/config",
  "definitions": {
    "config": {
      "type": "object",
      "properties": {
        "githubLogin": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        },
        "defaultRepo": {
          "type": "string"
        },
        "skillsDir": {
          "type": [
            "string",
            "null"
          ],
          "default": null
        },
        "runChecks": {
          "type": "boolean",
          "default": false
        },
        "model": {
          "type": "string"
        },
        "agent": {
          "type": "string"
        },
        "toolVersion": {
          "type": "string"
        },
        "captureMetadata": {
          "type": "boolean",
          "default": false
        }
      },
      "additionalProperties": false
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example:

{ "githubLogin": null, "defaultRepo": "input-output-hk/some-repo", "skillsDir": null, "runChecks": false }

Review Request

The input to review.create: the pull request to review, the skills to attach, and the reviewers to request.

{
  "$ref": "#/definitions/review-request",
  "definitions": {
    "review-request": {
      "type": "object",
      "properties": {
        "repo": {
          "type": "string",
          "pattern": "^[^/]+\\/[^/]+$"
        },
        "pr": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "skills": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "reviewers": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "minItems": 1
        },
        "note": {
          "type": "string"
        }
      },
      "required": [
        "repo",
        "pr",
        "reviewers"
      ],
      "additionalProperties": false
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example:

{ "repo": "input-output-hk/some-repo", "pr": 42, "skills": ["security", "cryptography"], "reviewers": ["yshyn-iohk"], "note": "focus on the crypto changes" }

Claim Marker

The JSON payload embedded in the claim comment. It pins a review to a commit SHA and records who claimed it and from which machine.

{
  "$ref": "#/definitions/claim-marker",
  "definitions": {
    "claim-marker": {
      "type": "object",
      "properties": {
        "v": {
          "type": "number",
          "enum": [
            1,
            2
          ]
        },
        "reviewer": {
          "type": "string",
          "minLength": 1
        },
        "machine": {
          "type": "string",
          "minLength": 1
        },
        "sha": {
          "type": "string",
          "minLength": 7
        },
        "claimedAt": {
          "type": "string",
          "minLength": 1
        },
        "model": {
          "type": "string"
        },
        "agent": {
          "type": "string"
        },
        "toolVersion": {
          "type": "string"
        }
      },
      "required": [
        "v",
        "reviewer",
        "machine",
        "sha",
        "claimedAt"
      ],
      "additionalProperties": false
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Review Result

The input to review.complete: the review event, the summary, and any inline comments.

{
  "$ref": "#/definitions/review-result",
  "definitions": {
    "review-result": {
      "type": "object",
      "properties": {
        "repo": {
          "type": "string",
          "pattern": "^[^/]+\\/[^/]+$"
        },
        "pr": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "event": {
          "type": "string",
          "enum": [
            "approve",
            "request-changes",
            "comment"
          ]
        },
        "summary": {
          "type": "string",
          "minLength": 1
        },
        "comments": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": {
                "type": "string"
              },
              "line": {
                "type": "integer",
                "exclusiveMinimum": 0
              },
              "body": {
                "type": "string"
              }
            },
            "required": [
              "path",
              "line",
              "body"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "repo",
        "pr",
        "event",
        "summary"
      ],
      "additionalProperties": false
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example:

{ "repo": "input-output-hk/some-repo", "pr": 42, "event": "request-changes", "summary": "Two blocking issues; see inline comments.", "comments": [{ "path": "src/crypto.rs", "line": 88, "body": "Nonce is reused across messages." }] }

Enrichment

The input to review.enrich: an enricher's overall verdict, summary, and any new findings the primary review missed.

{
  "$ref": "#/definitions/enrichment",
  "definitions": {
    "enrichment": {
      "type": "object",
      "properties": {
        "overallVerdict": {
          "type": "string",
          "enum": [
            "agree",
            "disagree",
            "mixed"
          ]
        },
        "summary": {
          "type": "string",
          "minLength": 1
        },
        "newFindings": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": {
                "type": "string"
              },
              "line": {
                "type": "integer",
                "exclusiveMinimum": 0
              },
              "body": {
                "type": "string"
              }
            },
            "required": [
              "path",
              "line",
              "body"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "overallVerdict",
        "summary"
      ],
      "additionalProperties": false
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Label Spec

One label definition, a name, a color, and a description, applied when labels.bootstrap provisions a repository.

{
  "$ref": "#/definitions/label-spec",
  "definitions": {
    "label-spec": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "color": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{6}$"
        },
        "description": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "color",
        "description"
      ],
      "additionalProperties": false
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}