# Protobuf Compatibility Checker

- Human page: https://happytails.ai/en/developer-tools/protobuf-compatibility-checker/
- Markdown: https://happytails.ai/en/developer-tools/protobuf-compatibility-checker.md
- Structured JSON: https://happytails.ai/agents/en/developer-tools/protobuf-compatibility-checker/index.json
- Visibility: public

## Tool capabilities

| Property | Value |
| --- | --- |
| Tool ID | `protobuf-compatibility-checker` |
| Category | developer-tools |
| Implementation | Registered implementation. Registration alone is not a production-quality guarantee. |
| Browser execution | Use the visible action or interactive controls. |
| Browser processing | Browser; see tool notes for network behavior. |
| HTTP API | Not callable through HTTP. |
| Browser-agent interface | run_current_tool |

### Implementation notes

Runs in your browser in a background worker. Accepts two .proto files of up to 1000000 characters each, without imports, editions or extensions.

### Inputs and settings

Text input: Old .proto file.

Example or placeholder shown in the interface (not a validated fixture):

```text
syntax = "proto3";
message Order { string id = 1; }
```

The version that existing data was written with. Put the changed file in New schema. Up to 1,000,000 characters. Review the settings before running.

| Setting | Meaning | Control type | Default | Constraints |
| --- | --- | --- | --- | --- |
| `next` | New schema | textarea | "" |  |

### Browser-agent workflow

1. Open the human page in a browser that supports WebMCP.
2. Discover the interface exposed by that page; use its actual schema.
3. Select files on the page first when the tool requires files.
4. Call `run_current_tool` with valid input and settings.
5. Inspect the returned result or error and the displayed output. Retrieve files from the displayed download links.

Calls do not automatically copy or download results. Browser permissions still apply. Interface availability alone is not proof of successful execution.

### Planning specification

Accepts two .proto files of up to 1,000,000 characters each, with at most 200,000 tokens, 2,000 messages and enums, 10,000 fields per message and 32 levels of nested messages. The comparison runs in your browser in a background worker. Downloads are a JSON report and a CSV list of findings.

This describes intended requirements. Use the implementation notes, interface schema and observed output to determine current support.

### Complete machine-readable capability record

```json
{
  "id": "protobuf-compatibility-checker",
  "category": "developer-tools",
  "built": true,
  "requirements": "Accepts two .proto files of up to 1,000,000 characters each, with at most 200,000 tokens, 2,000 messages and enums, 10,000 fields per message and 32 levels of nested messages. The comparison runs in your browser in a background worker. Downloads are a JSON report and a CSV list of findings.",
  "implementation": {
    "fields": [
      {
        "key": "next",
        "label": "New schema",
        "value": "",
        "type": "textarea",
        "maxLength": 1000000,
        "help": "The changed .proto file. Paste the old version in the main input."
      }
    ],
    "registrationFamily": "api-contracts-schemas",
    "codeDirection": "ltr",
    "inputMaxLength": 1000000,
    "inputErrorCode": "API_CONTRACTS_SCHEMAS_TOO_LONG_PROTOBUF_COMPATIBILITY_CHECKER",
    "note": "Runs in your browser in a background worker. Accepts two .proto files of up to 1000000 characters each, without imports, editions or extensions.",
    "experience": {
      "automatic": false,
      "single": false,
      "inputMaxLength": 1000000,
      "inputMode": "text",
      "label": "Old .proto file",
      "placeholder": "syntax = \"proto3\";\nmessage Order { string id = 1; }",
      "help": "The version that existing data was written with. Put the changed file in New schema. Up to 1,000,000 characters. Review the settings before running.",
      "helpParts": [
        "The version that existing data was written with. Put the changed file in New schema.",
        "Up to 1,000,000 characters.",
        "Review the settings before running."
      ],
      "action": null
    },
    "mode": "explicit",
    "interactive": false
  },
  "execution": "Browser interface",
  "api": null,
  "browser_agent": {
    "supported": true,
    "name": "run_current_tool",
    "discovery": "WebMCP on the human page in a supporting browser",
    "verification": "See audit/API-AUDIT.md; availability is not verification"
  }
}
```

## Page guide

Compare two versions of a .proto file and find the edits that break messages already written on the wire or as JSON. Removed numbers, type changes, renamed fields and enum changes are each explained.

### How to use Protobuf Compatibility Checker

1. Paste the old .proto file in the main box.
2. Paste the new version in the New schema field.
3. Run the check and review the findings, most severe first.
4. Download the JSON report or the CSV list.

How can we improve this tool?

Report a problem or share an idea.

Please leave out private information. Your message and the tool name go to our team via PostHog.

## Useful next steps

- [Avro Schema Compatibility Checker](https://happytails.ai/en/developer-tools/avro-schema-compatibility-checker/) ([Markdown](https://happytails.ai/en/developer-tools/avro-schema-compatibility-checker.md))

- [JSON diff](https://happytails.ai/en/developer-tools/json-diff/) ([Markdown](https://happytails.ai/en/developer-tools/json-diff.md))

- [Compare text](https://happytails.ai/en/text-tools/compare-text/) ([Markdown](https://happytails.ai/en/text-tools/compare-text.md))

Accepts two .proto files of up to 1,000,000 characters each, with at most 200,000 tokens, 2,000 messages and enums, 10,000 fields per message and 32 levels of nested messages. The comparison runs in your browser in a background worker. Downloads are a JSON report and a CSV list of findings.

## Severities

Breaking means old and new programs can misread binary messages: a removed field whose number is not reserved, a number reused from a reserved range, a type with a different wire encoding, a change between singular and repeated, a removed message or enum, or a renumbered enum value. Breaking JSON means binary data still works but the JSON or text format changes, such as a renamed field or enum value. Warnings cover changes that work on the wire but can truncate or reinterpret values, such as int32 to int64, or moves into and out of a oneof.

### How it compares

Messages and enums are matched by their name without the package, and fields by number, following the protobuf language guide rules for updating a message type. Messages and enums nested inside other messages are compared too.

### What is not supported

The parser reads proto2 and proto3 files with messages, enums, oneof, maps, nested types, reserved numbers and names, and field options. Imports are listed but not resolved, so types from other files are compared by name only. Editions, groups and extensions are rejected. Services are skipped.