Principle:Vespa engine Vespa ABI Compatibility Specification

Knowledge Sources	Vespa ABI Check Plugin Java Binary Compatibility
Domains	API_Governance, Backward_Compatibility
Last Updated	2026-02-09 00:00 GMT

Overview

A build-time enforcement mechanism that detects binary-incompatible changes to public Java API surfaces by comparing compiled bytecode against a stored JSON baseline of class, method, and field signatures.

Description

ABI (Application Binary Interface) Compatibility Specification is the practice of maintaining a machine-readable baseline of all public and protected API signatures in a Java module. Each module in the Vespa project stores an abi-spec.json file at its root, listing every public class with its superclass, interfaces, attributes, methods, and fields.

During the Maven build, the abi-check-plugin compares the compiled bytecode of each module against its stored ABI spec. If any public signature has been removed, renamed, or had its type changed in an incompatible way, the build fails with a clear diff report. This prevents accidental breaking changes from reaching production.

The principle addresses a core challenge in large-scale Java projects: ensuring that downstream consumers of a library can upgrade without recompilation. Javas binary compatibility rules (JLS §13) define what changes are safe, and the ABI spec mechanism automates enforcement of these rules.

Usage

Apply this principle to any Java module that exposes a public API consumed by external applications or other modules. It is especially critical for:

Container plugin APIs (jdisc_core, container-disc, container-search)
Document model APIs (document, documentapi, docproc)
Configuration APIs (config-lib, config-model-api)
Client APIs (vespa-feed-client-api)
Library APIs (vespajlib, linguistics, messagebus)

Theoretical Basis

The ABI compatibility check operates on a simple set-comparison algorithm:

Pseudo-code Logic:

# Abstract algorithm description (NOT real implementation)
baseline = load_json("abi-spec.json")       # stored signatures
compiled = extract_signatures(class_files)   # bytecode signatures

for class_name in union(baseline.keys(), compiled.keys()):
    if class_name not in compiled:
        report_error("REMOVED class: " + class_name)
    elif class_name not in baseline:
        report_info("NEW class: " + class_name)
    else:
        diff_methods(baseline[class_name].methods, compiled[class_name].methods)
        diff_fields(baseline[class_name].fields, compiled[class_name].fields)
        diff_interfaces(baseline[class_name].interfaces, compiled[class_name].interfaces)

The key invariants enforced are:

No removal of public/protected methods or fields
No narrowing of access modifiers (public → protected)
No change to method return types or parameter types
No removal of implemented interfaces

Adding new public methods, classes, or fields is always safe and the spec is updated automatically.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment