gob-contract

Overview ¶

Package gob-contract demonstrates the "Go library as contract" pattern.

Instead of an OpenAPI or AsyncAPI document as the cross-service contract, a shared Go module (the contract/ subpackage in this example) defines:

• The domain type (Order) with exported fields (required by encoding/gob)
• The codec (OrderCodec) — shape, constraints, and schema in one value
• The wire format (GobFormat = format.Gob(OrderCodec)) — binary, Go-native
• The channel definition (OrderChannel) — topic template and operations

Both services import this package. The Go compiler enforces the contract: any field rename, type change, or constraint modification breaks compilation on both sides immediately — no stale YAML, no schema drift, no code-generation.

When to use this pattern ¶

Use the "Go library as contract" pattern when:

• All services communicating over this channel are written in Go
• You want binary-efficient wire encoding without a schema compiler (protobuf, Avro)
• Compile-time contract enforcement matters more than cross-language interoperability

For external-facing APIs (consumed by non-Go clients or documented via tooling), use JSON/YAML formats and generate OpenAPI or AsyncAPI specs from the same codec.

What about OpenAPI/AsyncAPI with Gob? ¶

You can add format.Gob to a route or channel and the spec renderer will emit "application/gob" as the content type alongside the JSON Schema body. The schema documents the logical data shape — useful for humans — but tooling (Swagger UI, API gateways, code generators) cannot interpret or validate binary gob payloads. Keep "application/gob" out of external-facing specs; use it only for internal Go-to-Go channels where the Go library is the authoritative contract.

Run with: go run ./examples/gob-contract