Interop

At a glance

NextPDF Pro provides a versioned set of result data-transfer objects (DTOs) that serialize PDF analysis output — document info, pages, text blocks, segmentation, and form data — to a stable, schema-locked JSON shape for consumption by external systems and tools.

Availability & licensing

This capability ships in NextPDF Pro (nextpdf/pro) and activates with a Pro-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Interop is part of the Pro edition; there is no separate per-feature license flag. Compare editions and get a license.

Install

composer require nextpdf/pro:^3

Conceptual overview

When PDF processing output crosses a process or service boundary, the receiver needs a stable contract. The Interop V1 surface provides that:

• InteropResultInterface — every result DTO implements this. Each serializes to a JSON-safe array that always carries a schema_version key, and to a JSON string.
• Result DTOs — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment, and FormData / FormField. Each is an immutable view of one analysis result.
• SchemaLock — a CI guard. It holds the SHA-256 of the frozen schema and fails the build if the schema file changes without a corresponding version bump, so the wire contract cannot drift silently.

The Interop surface is explicitly versioned (SCHEMA_VERSION). Treat it as a public API contract: additive changes bump the schema; breaking changes require a new major version.

Why it works this way

The serialization shape is treated as a public API contract, not an implementation detail. Every DTO carries a schema_version key, so consumers branch on the shape they receive rather than guess. SchemaLock pins the SHA-256 of the frozen schema in CI, so the format cannot drift without a version bump. That is what lets external systems build against the JSON safely: the contract moves only when the version does. The output stays portable — documented, versioned data you own, not a shape that shifts under you.

Design background: Open core, no lock-in.

API surface

Class	Responsibility
InteropResultInterface	Common serialization contract.
DocumentInfo, PageInfo, BoundingBox	Common document/page DTOs.
ExtractedText, ExtractedPage, TextBlock	Text-extraction DTOs.
DocumentSegmentation, Segment	Document-segmentation DTOs.
FormData, FormField	Form-data DTOs.
SchemaLock	CI schema-drift guard.

Code sample — Quick start

$json = $result->toJson(JSON_PRETTY_PRINT);
$array = $result->toArray(); // includes 'schema_version'

Code sample — Production

use NextPDF\Pro\Interop\V1\SchemaLock;

if (! SchemaLock::verify()) {
    throw new RuntimeException('Interop schema drift detected — version bump required.');
}
$payload = $result->toArray();
$httpClient->postJson($endpoint, $payload);

Edge cases & gotchas

• toArray() always includes schema_version; downstream consumers should branch on it.
• SchemaLock::verify() returns false if the schema file is missing or modified.
• The DTOs are read-only views; they do not re-run analysis.

Performance

Serialization is linear in the size of the result graph.

Security notes

DTOs carry only the analysis output you populate. No filesystem or network I/O occurs during serialization.

Conformance

Interop defines a NextPDF-owned versioned schema; it does not implement an external standard.

Behavior contract

• Every result DTO implements InteropResultInterface and serializes to a JSON-safe array that always carries a schema_version key, and to a JSON string.
• Result DTOs (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) are immutable read-only views; they do not re-run analysis.
• SchemaLock::verify() holds the SHA-256 of the frozen schema and returns false if the schema file is missing or modified, so the wire contract cannot drift silently.
• The surface is explicitly versioned (SCHEMA_VERSION): additive changes bump the schema; breaking changes require a new major version.
• No filesystem or network I/O occurs during serialization.

Enterprise boundary note

Enterprise does not change Interop behavior. Enterprise adds higher-tier features documented separately; they are not required to use the versioned result DTOs.

Core fallback / alternative

There is no Core equivalent for schema-locked, versioned result DTOs. This is a Pro addition.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

See also

• Extraction — produces text and segment results.
• Form — produces form-data results.
• Interop — Deep Reference — full DTO field reference.