# Schema Reference

GitScope output is defined by Pydantic v2 models in `src/gitscope/schema.py`. This is the contract — all output validates against these models.

## `GitScopeOutput` (top-level)

| Field | Type | Description |
|-------|------|-------------|
| `schema_version` | `str` | Always `"1.0"` |
| `meta` | `Meta` | Run metadata: ref range, stats, timing |
| `files` | `list[FileChange]` | Per-file semantic changes |
| `summary` | `Summary` | Aggregate: change types, breaking changes, focus areas |
| `tiered` | `TieredSummary` | Human-readable summaries at different token budgets |

## `Meta`

| Field | Type | Description |
|-------|------|-------------|
| `ref_range` | `str` | Git ref range analyzed (e.g. `"abc1234..def5678"`) |
| `stats` | `DiffStats` | `files`, `additions`, `deletions` counts |
| `warnings` | `list[str]` | Degraded output signals (parse errors, truncation) |
| `timing_ms` | `float \| None` | Wall-clock time for analysis |

## `FileChange`

| Field | Type | Description |
|-------|------|-------------|
| `path` | `str` | File path relative to repo root |
| `language` | `str \| None` | Detected language (e.g. `"python"`, `"typescript"`) |
| `change_type` | `"added" \| "removed" \| "modified" \| "renamed"` | File-level change type |
| `generated` | `bool` | Lock files, protobuf output, etc. |
| `binary` | `bool` | Binary file (skipped for analysis) |
| `parse_error` | `bool` | Tree-sitter couldn't parse this file |
| `unsupported_language` | `bool` | No grammar available for this language |
| `changes` | `list[SymbolChange]` | Symbol-level changes in this file |

## `SymbolChange`

| Field | Type | Description |
|-------|------|-------------|
| `kind` | `Literal[...]` | One of: `function_added`, `function_removed`, `function_modified`, `class_added`, `class_removed`, `class_modified`, `signature_changed`, `moved` |
| `name` | `str` | Symbol name (e.g. `"authenticate"`) |
| `signature` | `str \| None` | Full signature for added/removed symbols |
| `before_signature` | `str \| None` | Old signature (for `signature_changed`) |
| `after_signature` | `str \| None` | New signature (for `signature_changed`) |
| `file_from` | `str \| None` | Source file path (for `moved`) |
| `line` | `int \| None` | Line number in the new file |
| `breaking` | `bool` | Whether this change breaks the public API |
| `detail` | `dict \| None` | Escape hatch for language-specific metadata |

## `Summary`

| Field | Type | Description |
|-------|------|-------------|
| `change_types` | `dict[str, int]` | Counts by category (e.g. `{"feature": 3, "refactor": 5}`) |
| `breaking_changes` | `list[SymbolChange]` | All breaking changes, surfaced at top level |
| `focus` | `list[str]` | Short list of the most important items for reviewer agents. See [Agent Integration](agent-integration.md#the-focus-field). |

## `TieredSummary`

| Field | Type | Description |
|-------|------|-------------|
| `oneliner` | `str` | ~20 tokens. One sentence. |
| `short` | `str` | ~80 tokens. Key changes with signatures. |
| `detailed` | `str` | Full narrative. Per-file breakdown. |

## Example output by tier

### `oneliner` (~20 tokens)

```
Replace API key auth with OAuth2 PKCE; 2 breaking changes
```

### `short` (~80 tokens)

```
Removes authenticate(apiKey), adds authenticateOAuth(config) with PKCE.
refreshToken now returns TokenPair. 1 new dep: oauth4webapi.
```

### `detailed` (full JSON)

See the complete JSON example in [Quick Start](quickstart.md#--format-json).

## Design principles

- **Semantic change units.** Function/class/type level, with signatures — not line numbers.
- **Breaking changes at top level.** Not buried in file details.
- **No opinions.** Structural facts only. Risk assessment is the reviewer's job.
- **Tiered output.** Consumers pick their token budget.
- **Graceful degradation.** Parse errors, unsupported languages, and binary files are flagged — never crashes, always produces valid output.
