Schema versioning for review comments

Once Claude Desktop and Cursor are calling your tool in production, the review comment shape becomes a wire contract. Renaming a field or adding a required one breaks every client that has not yet upgraded. A small versioning move keeps you free to evolve the schema without breaking anyone.

schemas.py
python
from typing import Literal
from pydantic import BaseModel, Field

class ReviewCommentV1(BaseModel):
    schema_version: Literal["1"] = "1"
    file_path: str
    line: int
    severity: Literal["nit", "suggestion", "issue", "blocker"]
    body: str

class ReviewCommentV2(BaseModel):
    schema_version: Literal["2"] = "2"
    file_path: str
    line: int
    severity: Literal["nit", "suggestion", "issue", "blocker"]
    body: str
    suggested_patch: str | None = None  # new optional field

# The tool advertises v2 but accepts v1 for older clients
ReviewComment = ReviewCommentV1 | ReviewCommentV2

A literal schema_version field is the compass. Old clients keep working because the new field is optional. A future v3 can repeat the pattern.

Two rules keep this safe. New fields are always optional. Removed fields stay in the union as deprecated for at least one release. Anything else is a major-version bump that you announce, not a silent breakage.

Quiz: Quiz

Loading practice…