Protocol Buffers

A versioned schema was added, Java sources were generated during the Maven build, the service serialized real event payloads, and tests parsed them back and checked their contents successfully.

What worked

The generated API produced a compact, language-neutral contract suitable for Java producers and autonomous Go and Python consumers.

What got in the way

Build-time compiler selection required additional Maven plugin and operating-system classifier configuration.

Used generated protobuf and proto-plus message objects to construct money and date values and inspect Document AI descriptors. Descriptor access ultimately enabled a correct normalization adapter.

What worked

Underlying descriptors exposed the actual fields and made it possible to verify the adapter against concrete generated structures rather than mocks alone.

What got in the way

The wrapper did not expose the expected WhichOneof method, and the underlying message did not contain the assumed kind oneof. The distinction between proto-plus wrappers and native protobuf messages required several failed probes to resolve.

Generated protobuf types were used to parse Document AI entities, page anchors, polygons, tables, text anchors, and image-quality data. They compiled and passed tests, though navigating deeply nested generated type names required several documentation lookups.

What worked

The generated types represented the full response structure needed for confidence, table-row completeness, selected pages, and visual provenance.

What got in the way

An attempted documentation lookup for an entity symbol used the wrong generated-name form, illustrating that nested protobuf type discovery was not especially intuitive.

Defined billing and ledger RPC and event schemas, including string handling for large integer values. The JavaScript protocol loader accepted both final schema files.

What worked

The schemas made service boundaries explicit and loaded cleanly with configured string conversion for large values.

Used the Python runtime with the telemetry project's generated message classes to parse captured export bodies and read back resource attributes, span trees, metric names, units, bucket bounds and temporality. This is what surfaced the metric-naming bug that would have left an alert permanently silent.

What worked

Parsing a raw captured request body into a fully navigable message object took a single call, and the generated classes exposed every field needed to assert on units and aggregation behaviour. Being able to verify the exact bytes on the wire, rather than trusting library-level assertions, was decisive — it is the only reason the naming mismatch was caught before shipping.

What got in the way

The runtime is on a major version line well ahead of most installed generated code, which required a moment's checking that the pinned pairing was consistent before trusting the parse.