Goa Files

Goa v3.31.0 brings the generation preview to stable: one complete design now determines the declarations, imports, conversions, validators, and transport code generated across an application. This removes disagreements between generator passes that could produce code that failed to compile or handled a value differently across transports.

This is a substantial upgrade with intentional breaking changes. Goa stays on the goa.design/goa/v3 module path, but applications and custom plugins may need source changes, and some client/server exchanges require coordinated deployment. Read the upgrade guide before regenerating a production application.

What improves

Consistent generated packages

Services, HTTP, gRPC, JSON-RPC, commands, examples, OpenAPI documents, and plugins use the same recorded generation decisions. Shared types and errors have one package owner. Declarations and their callers use the same final names and imports. Example values stay stable when generation order changes. Plugins that add declarations participate before package names become final.

gRPC preserves the values the design requires

Required singular protobuf fields now distinguish absence from explicit zero values. An omitted required value produces a validation error; an explicitly supplied false, 0, or empty value remains valid when allowed by the design. Input defaults apply only when the input is absent. Service results are sent as returned.

Selected result views have matching conversion and validation, including dynamic server streams. Fields omitted by a view are not incorrectly required. Empty repeated and map fields remain valid because protobuf cannot distinguish their absence from emptiness; authored length and item validation still runs. Nil collection wrappers used as map values no longer cause conversion panics.

Canceled gRPC calls now expose one context cause while retaining the gRPC status and transport details. Independent cleanup failures remain visible. The release also includes gRPC v1.83.2.

HTTP clients and servers agree on their contracts

Clients decode and validate the selected result view. Views that omit complete-result fields no longer cause false validation errors or WebSocket client panics. Required primitive JSON array items reject null. Multipart bodies are decoded and validated before the service payload is constructed.

Whole-query maps accept the raw keys generated clients send. Float query values use compact text that preserves their value. Server-sent events preserve optional primitive values and report write/flush failures. Empty successful WebSocket streams complete and close normally. Custom HTTP path types retain their generated imports.

JSON-RPC has explicit request and stream behavior

Generated JSON-RPC handles IDs, notifications, batches, invalid requests, errors, and media types consistently. Unary methods use HTTP requests and responses. Server streams use explicit server-sent events with service stream methods and a terminal response for the opening request.

Caller-selected views use { "view": ..., "body": ... } inside result. Designed errors use { "name": ..., "body": ... } inside error.data; unknown errors retain the raw JSON-RPC representation. These exchanges need matching peers.

Clearer application and plugin APIs

OneOf values have one selected branch, managed through generated constructors, setters, accessors, and Kind. Interceptors receive read-only information interfaces. API-level errors are reusable definitions that services or methods select explicitly. Named string credentials keep their declared types.

Generated command starters execute calls, print results, consume supported streams, and return failures. Complete-message gRPC flags use protobuf JSON. OpenAPI schemas and examples better reflect views, security, bytes, and streaming data.

Required upgrade steps

1. Upgrade the module and command together, then regenerate the complete gen tree. Never mix files generated by different Goa versions. Compile and test the whole application, review the generated diff, and verify that a second generation produces no further changes.

sh go get goa.design/goa/v3@v3.31.0 go install goa.design/goa/v3/cmd/goa@v3.31.0 goa gen YOUR_MODULE/design

1. Update handwritten callers where needed. Direct union field access moves to constructors/accessors. Interceptor information parameters lose their pointer. Multipart decoder callbacks populate generated body types. Protobuf scalar literals use pointers. Direct generated helper calls and command starters may have new signatures. goa example preserves existing files and cannot migrate handwritten code automatically.

2. Use the supported protobuf tools for gRPC regeneration. Install protoc-gen-go v1.36.12 and protoc-gen-go-grpc v1.6.2; Goa checks their versions before writing gRPC files.

3. Migrate removed JSON-RPC APIs. JSON-RPC WebSocket, client-streaming, and bidirectional generation are removed. Use unary JSON-RPC, explicit JSON-RPC server-sent events, ordinary HTTP WebSocket, or gRPC. Server streams use Send, SendWithContext, and Close; clients use Recv() or RecvWithContext(ctx).

4. Resolve newly rejected designs. Examples include multiple untagged HTTP success responses, conflicting shared error names, invalid nested defaults, ambiguous routes or stream mappings, and unsupported security field types. The upgrade guide lists replacements for each affected design.

5. Upgrade official and custom plugins together. Official plugins are released as goa.design/plugins/v3@v3.31.0, with all example modules synchronized. Custom plugins that declare package names must use the planning lifecycle. The generator API migration table lists changed and removed APIs.

Goa requires Go 1.25 or later. The examples and plugins repositories retain their Go 1.26 requirement. Generated starters import Clue; applications staying on Go 1.25 should pin goa.design/clue@v1.2.6 before tidying, since Clue v1.3.0 requires Go 1.26.

Deployment and rollback

Coordinate both generated peers for designed JSON-RPC errors, caller-selected JSON-RPC views, JSON-RPC server streams, affected viewed gRPC methods and streams, optional primitive HTTP SSE data, and changed gRPC metadata text. Use matching client/server versions during cutover; ordinary rolling deployment does not guarantee compatibility for those changed exchanges.

Required protobuf field numbers and binary types remain compatible, but an old client cannot express presence for a required zero value. Update affected clients before enabling the new server's presence checks, or deploy matching peers together.

There is no persisted-data migration. Retain previous binaries, dependencies, design, handwritten callers, and generated output. Rollback restores that complete set; roll back both peers together for changed exchanges. The cancellation runtime fix does not require coordinated deployment.

Known existing limitations

The release review reproduced two issues that also affect v3.30.0: custom uuid.UUID query fields can generate client code that does not compile (#3924), and recursive gRPC results containing arrays of themselves can make generation recurse indefinitely (#2515). Plain string query fields with FormatUUID remain usable. These issues are not claimed as fixed by this release.

Related changes and thanks

See the generation upgrade #3971, synchronized examples [#219], and plugins [#271]. Examples [#220] makes the normal build and release cover all 19 modules. Later preview corrections include named string contracts [#3984], gRPC cancellation [#3986], and protobuf collection presence [#3988].

Thanks to @ikawaha and @raphael for the fixes, review, and extensive generation and transport testing behind this release.