Implementation:Vespa engine Vespa DocumentAPI ABI Spec

Knowledge Sources	Vespa Vespa ABI Check Plugin
Domains	API, Document_Processing
Last Updated	2026-02-09 00:00 GMT

Overview

ABI compatibility specification for the documentapi module of the Vespa search engine, defining 182 public Java API surfaces for backward compatibility enforcement.

Description

This ABI specification file is a machine-readable JSON baseline listing every public and protected class, method, and field signature in the documentapi module. It is consumed by the abi-check-plugin Maven plugin during the build to detect binary-incompatible changes to the public API.

Key packages covered:

• com.yahoo.documentapi

Key API classes:

• DocumentAccess
• AsyncSession
• SyncSession
• VisitorParameters

Usage

This specification is consumed automatically during the Maven build by the abi-check-plugin. Developers interact with it when:

• Adding new public API methods or classes (the spec must be updated)
• Removing or changing existing public signatures (the build will fail if the spec is not updated)
• Reviewing pull requests that modify public API surfaces

Code Reference

Source Location

• Repository: Vespa
• File: documentapi/abi-spec.json
• Lines: 1-3213

Format

{
  "fully.qualified.ClassName": {
    "superClass": "java.lang.Object",
    "interfaces": [],
    "attributes": ["public"],
    "methods": [
      "public void <init>()",
      "public ReturnType methodName(ParamType)"
    ],
    "fields": []
  }
}

Build Integration

<plugin>
    <groupId>com.yahoo.vespa</groupId>
    <artifactId>abi-check-plugin</artifactId>
    <configuration>
        <specFileName>abi-spec.json</specFileName>
    </configuration>
</plugin>

I/O Contract

Inputs

Name	Type	Required	Description
spec file	JSON	Yes	ABI specification baseline with class signatures
compiled classes	.class files	Yes	Compiled Java bytecode to verify against the spec

Outputs

Name	Type	Description
build result	Pass/Fail	Build fails if compiled classes diverge from spec
diff report	Text	Human-readable report of detected ABI changes

Usage Examples

Updating After API Change

# After adding a new public method, regenerate the ABI spec:
mvn install -pl documentapi -DskipTests

# The abi-check-plugin will update abi-spec.json with new signatures
# Commit the updated spec alongside your code change
git add documentapi/abi-spec.json
git commit -m "Update ABI spec for documentapi"

Verifying Compatibility

# Run ABI check explicitly
mvn verify -pl documentapi -DskipTests

Related Pages

• Principle:Vespa_engine_Vespa_ABI_Compatibility_Specification