Schema Cheatsheet — Skia Update Review

Quick reference for skia-review-schema.json v1.0.

Top-Level Structure

{
  "meta": { ... },
  "summary": "Executive summary of the PR review...",
  "recommendations": ["Action item 1", "Action item 2"],
  "generatedFiles": { "status": "...", "summary": "...", "recommendations": [...], ... },
  "upstreamIntegrity": { "status": "...", "summary": "...", "recommendations": [...], ... },
  "interopIntegrity": { "status": "...", "summary": "...", "recommendations": [...], ... },
  "depsAudit": { "status": "...", "summary": "...", "recommendations": [...], ... },
  "riskAssessment": "HIGH",
  "companionPr": { "prNumber": N, "status": "...", "summary": "...", "recommendations": [...], "added": [...], "changed": [...], "unchanged": N }
}

Every section has summary (brief overview) and recommendations (actionable items for reviewer).

companionPr is required — a Skia update always has a companion SkiaSharp PR.

Scripts

Status Values

All sections use PASS or REVIEW_REQUIRED. There is no WARN or FAIL for source/deps — all changes need human review.

Risk Assessment

Source Integrity (upstream + interop)

Both use the same structure (diff-of-diffs):

Each item in added/removed:

{ "path": "include/core/SkBitmap.h", "summary": "...", "diff": "...", "relatedFiles": [...] }

Each item in changed:

{ "path": "src/core/SkFont.cpp", "summary": "...", "diff": "...", "oldDiff": "...", "newDiff": "...", "patchDiff": "...", "relatedFiles": [...] }

• diff — Direct branch-to-branch diff (base→PR head). The simplest view — what actually changed in the fork. Default view in the HTML viewer.
• patchDiff — Diff-of-diffs (old patch vs new patch). Shows how the fork's modifications changed. Useful for understanding why something changed relative to upstream.
• oldDiff / newDiff — The full fork-vs-upstream patches for old and new branches respectively.

No per-file status. AI provides factual summaries only. ALL items need human review.

Related Files (Cross-Links)

Each source file item can include an optional relatedFiles array to link to other files in the report:

{
  "path": "include/core/SkFontMgr.h",
  "summary": "Fork patch added MakeDefault()...",
  "relatedFiles": [
    { "path": "src/c/sk_default_fontmgr.cpp", "relationship": "replaced by" },
    { "path": "src/c/sk_typeface.cpp", "relationship": "consumer" }
  ]
}

The HTML viewer renders these as clickable pills. Clicking navigates to the matching file in the report (scrolling + highlighting), or opens on GitHub if not found in the report.

When to add relatedFiles:

• A removed patch has a replacement in a different section (e.g., upstream removed → interop added)
• A header and implementation file are both changed
• An interop file has a corresponding C# wrapper in the companion PR

DEPS Audit

Same added/removed/changed pattern:

Each added/removed item:

{ "name": "icu4x", "summary": "...", "url": "...", "revision": "..." }

Each changed item:

{ "name": "libpng", "summary": "...", "oldUrl": "...", "oldRevision": "...", "newUrl": "...", "newRevision": "..." }

Companion PR (C# changes)

Uses the same sourceFile structure as upstream/interop for full file-level review with diffs:

{
  "companionPr": {
    "prNumber": 3560,
    "status": "REVIEW_REQUIRED",
    "summary": "Brief overview of C# changes...",
    "recommendations": ["Action item 1", "..."],
    "added": [
      { "path": "binding/SkiaSharp/SKFoo.cs", "summary": "New wrapper for sk_foo API", "diff": "..." }
    ],
    "changed": [
      { "path": "binding/SkiaSharp/SKBar.cs", "summary": "Updated overload for new parameter", "diff": "...", "oldDiff": "...", "newDiff": "...", "patchDiff": "..." }
    ],
    "unchanged": 5
  }
}

Each item uses the same sourceFile shape as upstream/interop — full diff support with Direct/Patch/Old/New views, related files cross-links, etc.

Files in these dirs go to interopIntegrity; everything else to upstreamIntegrity:

• include/c/
• include/xamarin/
• src/c/
• src/xamarin/

Validation Rules

• REVIEW_REQUIRED sections must have at least one added/removed/changed item
• Each source file item must have path + summary
• Each dep item must have name + summary
• meta.skiasharpPrNumber is required (integer, not null)
• meta.shas.upstream is the NEW upstream SHA (the milestone being merged in)
• companionPr must have prNumber, status, summary, recommendations, unchanged
• Each companion PR file item must have path + summary (same as source integrity items)
• generatedFiles can include generatorError (string) when the generator itself crashes
• No absolute paths (redact /Users/... → relative)
• Schema version must be "1.0"