Skip to content

CSR compatibility check#

The BSR's Confluent Schema Registry (CSR) Integration allows you to publish CSR subject schemas by annotating messages in your Protobuf schemas. To preserve compatibility with previous schema versions, the BSR enforces that any changes to a CSR subject don't introduce a breaking change without being reviewed. The CSR integration works with Buf's breaking change check to ensure backwards compatibility and identify problems early in your development cycle.

This check is enabled automatically when you create a CSR instance in the BSR.

How it works#

With the CSR integration enabled, on buf push to the default label, the BSR checks that any changes to an existing subject don't introduce breaking changes to that subject's schema. It does this by using Buf's breaking change check with the CSR category. When the CSR check finds a breaking change, depending on check configuration, the commit will either enter the review flow or an error is returned explaining that the push failed.

The CSR check applies whether or not other checks are enabled, and is only enforced on Protobuf files that include messages annotated as CSR subjects and their dependencies.

Checking for CSR subject incompatibilities during development#

Developers can enable one of Buf's editor plugins to enforce formatting, linting, and breaking change rules locally and test as they're building schemas. Buf's CSR category for breaking change detection detects all breakages relevant to Kafka.

Your organization can also hook into Buf's GitHub Actions to enforce breaking change detection before schemas containing subjects are merged into the default label and registered in the BSR. Again, Buf's CSR category for breaking change detection guarantees that changes are safe for Kafka.

Reviewing a CSR breaking change#

When reviewing a commit that contains a breaking change to a CSR subject, the reviewer must explicitly choose a new compatibility mode for each affected CSR subject to deal with the breaking change.

Screenshot of CSR resolution options in review flow

  • If the reviewer rejects the commit, the BSR blocks the breaking change and the subject's compatibility mode remains unchanged. The commit must be reverted or fixed for any new schema change to be available to the CSR or other downstream systems.

  • If the reviewer approves the commit, they must choose a new compatibility mode:

    • BACKWARD: Default and recommended. Enforces the schema's backwards compatibility against the latest BSR version on the default label. This may break both existing producers using old versions of that subject's schemas, and existing consumers in general.
    • NONE: No compatibility checks are performed on the schema. This won't break producers, but may break consumers as bad data can enter the pipeline. This setting is only useful if you're actively developing a schema, expect a lot of breaking changes, and don't want this check to block them—ideally you have no consumers yet at that point.

Once approved, the BSR publishes a one-time update for the affected subjects without doing compatibility checks and sets their mode to the reviewer's selection. Future pushes to the subjects apply compatibility checks based on their new mode. A CSR subject that has had a breaking change approved can never return to the BACKWARD_TRANSITIVE mode.

sequenceDiagram
    participant User
    box CSR instance lives inside the BSR
    participant BSR
    participant CSR
    end
    Note over BSR: Typical push flow
    User->>BSR: buf push
    BSR->>CSR: Update subjects
    Note over CSR: Detect subjects<br>& check compatibility
    alt Breaking changes
        CSR->>BSR: Review flow
        alt Reviewer approves
            BSR->>CSR: Change compatibility mode
            Note over CSR: Register new schemas<br>& link to subjects
            CSR->>BSR: OK
            BSR->>User: OK
        else Reviewer rejects
            BSR->>User: ERROR
        end
    else No breaking changes
        Note over CSR: Register new schemas<br>& link to subjects
        CSR->>BSR: OK
        BSR->>User: OK
    end