JSON Schema: /api/contract/v1/schema.json
HQ Rabbit review contract (v1)
A submission is how a developer's local agent hands a finished code review
to HQ Rabbit. It is one plain PR comment with a marker and a JSON payload. The
server validates it deterministically: if it fits this contract and matches the
PR, the bot reposts the findings as its own review, deletes the comment and
turns the hq-rabbit check green. If not, the bot replies with the errors
listed below and leaves the comment in place so the agent can fix it and post
a new submission.
The source of truth is the src/contract module. A JSON Schema generated from
it is served at /api/contract/v1/schema.json.
Comment format
<!-- hq-rabbit:submission v1 -->
```json
{ ...payload... }
```
- The marker
<!-- hq-rabbit:submission v1 -->must be the first non-whitespace content of the comment. A comment that mentions the marker anywhere else is not treated as a submission and is ignored by the server. - Exactly one fenced
jsonblock follows. The opening fence is a line of 3 or more backticks followed byjson; the closing fence is a line of only backticks, at least as many as the opening fence. Text before or after the block is ignored. - The block must be strict JSON: double-quoted keys and strings, no comments, no trailing commas.
- Backticks inside JSON strings (for example a code block in a finding body)
need no special care: strings in valid JSON cannot contain raw newlines, and
a closing fence must be a line of its own, so they can never end the block.
As a precaution,
buildSubmissionCommentuses a fence one backtick longer than any backtick run in the JSON, and the parser accepts any fence of 3 or more backticks.
Post it with gh pr comment <number> --body-file <file>.
Payload
{
"version": 1,
"headSha": "<40-char hex commit SHA the review was performed against>",
"summary": "<overall assessment, 1–2,000 chars>",
"reviewer": { // optional, informational only
"tool": "claude-code", // free text, max 60
"model": "<model id>" // free text, max 100
},
"filesReviewed": ["path/a.ts", "path/b.ts"], // 1–3,000 unique repo-relative paths
"findings": [ // 0–50 items; empty means a clean review
{
"path": "src/x.ts", // required, repo-relative
"line": 42, // optional; omit for a file-level finding
"startLine": 40, // optional; requires line; startLine <= line
"side": "RIGHT", // optional, "RIGHT" (default, new code) or "LEFT" (removed code)
"severity": "major", // "critical" | "major" | "minor" | "nit"
"title": "<max 120 chars>",
"body": "<max 1,000 chars, markdown allowed>",
"suggestion": "<optional replacement code, max 1,000 chars>"
}
]
}
Unknown keys, at the top level, in reviewer or in a finding, are rejected so
that typos surface as errors.
Field reference
| Field | Required | Rules |
|---|---|---|
version | yes | The number 1. |
headSha | yes | Full 40-character hex SHA of the commit you reviewed (git rev-parse HEAD). Must equal the PR's head. |
summary | yes | 1–2,000 characters, not blank. Overall assessment; say here if lower-severity findings were dropped. |
reviewer | no | Object with optional tool (max 60) and model (max 100). Informational only. |
filesReviewed | yes | 1–3,000 unique repo-relative paths. Must include every file the PR changes, including deleted files. |
findings | yes | 0–50 findings. [] is a clean review. |
findings[].path | yes | Repo-relative path of the file the finding is about. |
findings[].line | no | Positive integer: the line the comment attaches to (the last line of a range). Omit for a file-level note. |
findings[].startLine | no | Positive integer, first line of a multi-line range. Requires line, and startLine <= line. |
findings[].side | no | RIGHT (default): line numbers in the new version of the file. LEFT: line numbers in the old version. |
findings[].severity | yes | critical, major, minor or nit (see below). |
findings[].title | yes | 1–120 characters, not blank. One-line statement of the problem. |
findings[].body | yes | 1–1,000 characters, not blank. Markdown allowed. Explain the problem and the fix. |
findings[].suggestion | no | 1–1,000 characters. Replacement code for the line range (rendered as a GitHub suggestion where possible). |
A repo-relative path has no leading /, no . or .. segments and no line
breaks, and is spelled exactly as GitHub lists it in the PR's files, for
example src/app/page.tsx. Paths are at most 1,024 characters.
Findings whose line cannot be placed on the PR diff are still accepted; the bot puts them in the body of its review instead of inline.
Severity
critical— will break production, lose data, or open a security hole.major— a real bug or a design problem that should be fixed before merge.minor— worth fixing but not blocking.nit— style or preference.
Limits
| Limit | Value |
|---|---|
summary | 2,000 characters |
reviewer.tool | 60 characters |
reviewer.model | 100 characters |
filesReviewed | 1–3,000 paths |
| Any path | 1,024 characters |
findings | 50 |
findings[].title | 120 characters |
findings[].body | 1,000 characters |
findings[].suggestion | 1,000 characters |
| Whole payload, as compact JSON | 60,000 characters (total) |
Lengths are counted in JavaScript string length (UTF-16 code units; most characters count as 1, emoji as 2).
Why a total cap. A GitHub comment holds at most 65,536 characters. The
per-field limits alone allow far more than that (50 findings with full bodies
and suggestions is over 100,000 characters before JSON escaping), so the
payload also has a total cap: JSON.stringify(payload) must be at most 60,000
characters. Within that cap, a comment built by buildSubmissionComment is
always under 65,536 characters, fences included. If you hit the cap, shorten
finding bodies and suggestions, or keep the highest-severity findings and say
in summary that lower ones were dropped. The cap is measured on compact JSON; indenting adds characters, so use compact
JSON for payloads near the cap (buildSubmissionComment indents with 2
spaces, and switches to compact JSON when the indented form would exceed
60,000 characters).
Large PRs. Each filesReviewed entry costs its length plus 3 characters,
so the total cap binds before the 3,000-path limit: with an average path of
50 characters, about 1,000 files fit alongside a short summary and a few
findings. PRs larger than that cannot be submitted in v1 and should be split.
If there are more than 50 findings, keep the 50 most severe and say in
summary that lower-severity ones were dropped. Multi-part submissions are
not part of v1.
Checks against the PR
After the payload fits the schema, the server checks it against the PR:
headShamust equal the PR's current head SHA. A push after the review makes the submission stale: pull, review again, resubmit.- Every file the PR changes (every
filenamein GitHub's list-PR-files response, including removed files) must appear infilesReviewed. Extra paths are allowed.
Error codes
Every error has a stable code, a path into the payload where relevant
(for example findings[2].title), and a message that says how to fix it. The
bot's rejection reply lists them (at most 30, then a count of the rest).
| Code | Meaning |
|---|---|
missing_marker | The comment does not contain the submission marker. |
marker_not_first | The marker is present but something comes before it. |
unsupported_version | The marker or version names a contract version other than 1. |
missing_json_block | No fenced json block after the marker, or the block is never closed. |
multiple_json_blocks | More than one fenced json block. |
invalid_json | The block is not valid JSON (comments, trailing commas, single quotes, unescaped newlines...). |
unknown_key | A key the contract does not define (often a typo). |
schema | A field is missing, has the wrong type, is out of range or too long, or breaks a rule such as startLine. |
duplicate_file | A path appears more than once in filesReviewed. |
too_many_findings | More than 50 findings. |
too_large | The payload exceeds 60,000 characters as compact JSON. |
stale_sha | headSha is not the PR's current head. The message names both SHAs. |
missing_files | Changed files are missing from filesReviewed. The message lists up to 20 of them and counts the rest. |
The JSON Schema covers everything except the cross-field and whole-payload
rules: unique filesReviewed, startLine requiring line and being at most
line, and the total size cap.
Examples
A review with findings:
<!-- hq-rabbit:submission v1 -->
````json
{
"version": 1,
"headSha": "3f2a9c1e8b7d6a5f4e3d2c1b0a9f8e7d6c5b4a39",
"summary": "Adds rate limiting to the login endpoint. The limiter itself is sound, but the key ignores proxies and one error path leaks whether an account exists.",
"reviewer": { "tool": "claude-code", "model": "claude-opus-4-5" },
"filesReviewed": [
"src/app/api/login/route.ts",
"src/lib/rate-limit.ts",
"src/lib/rate-limit.test.ts",
"src/lib/old-throttle.ts"
],
"findings": [
{
"path": "src/lib/rate-limit.ts",
"line": 18,
"startLine": 15,
"severity": "major",
"title": "Rate limit key uses the proxy address",
"body": "Behind the load balancer `req.ip` is the proxy, so every user shares one bucket. Use the first address in `x-forwarded-for`, which the platform sets.",
"suggestion": "const key = req.headers.get(\"x-forwarded-for\")?.split(\",\")[0]?.trim() ?? req.ip;"
},
{
"path": "src/app/api/login/route.ts",
"line": 42,
"severity": "critical",
"title": "Error message reveals whether the account exists",
"body": "Unknown emails return `No such user` while bad passwords return `Wrong password`. Return the same message for both:\n\n```ts\nreturn error(401, \"Invalid email or password\");\n```"
},
{
"path": "src/lib/rate-limit.test.ts",
"severity": "nit",
"title": "Test names describe implementation, not behavior",
"body": "Consider naming tests after what the user sees, e.g. `blocks the sixth attempt within a minute`."
}
]
}
````
A clean review:
<!-- hq-rabbit:submission v1 -->
```json
{
"version": 1,
"headSha": "0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d",
"summary": "Renames the config loader and updates its callers. No issues found.",
"filesReviewed": ["src/config/load.ts", "src/server.ts"],
"findings": []
}
```