Implementation:Vespa engine Vespa Linguistics ABI Spec

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

Overview

ABI compatibility specification for the linguistics module of the Vespa search engine, defining 50 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 linguistics 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.language
• com.yahoo.language.process
• com.yahoo.language.detect
• com.yahoo.language.significance
• com.yahoo.language.simple

Key API classes:

• Language
• Linguistics
• Tokenizer
• Stemmer
• Embedder
• Normalizer
• Detector

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: linguistics/abi-spec.json
• Lines: 1-1046

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 linguistics -DskipTests

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

Verifying Compatibility

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

Related Pages

• Principle:Vespa_engine_Vespa_ABI_Compatibility_Specification