Goa Files

Goa v3.31.1 brings the generation preview to stable, with more expressive gRPC contracts, a unified generator, and improvements across HTTP, gRPC, and JSON-RPC. The examples and official plugins are updated and tested alongside it.

gRPC preserves whether a value was supplied

Generated gRPC code now distinguishes an omitted scalar value from an explicit false, 0, or empty string. That gives your API control over when to apply a default and when to require a value.

For an enabled flag with Default(true):

• Omit the flag, and the input default supplies true.
• Explicitly send false, and your service receives false.

With Required("enabled") and no default, an omitted flag is rejected, while an explicit false is accepted. The same presence rules apply to other scalar types, with your design's validation rules still enforced.

Service results are sent as your implementation returns them.

One plan for the whole application

Goa now builds one plan for the complete design before writing files. Services, transports, OpenAPI, commands, and plugins all use that plan, keeping shared types, names, imports, and conversions consistent across generated output.

Recursive gRPC collections

gRPC payloads and results can contain arrays and maps of their own type, including nested combinations. For example, a category can contain child categories, each with children of its own.

This fixes #2515, where a self-referencing collection could keep generation from completing. Nested validation, defaults, and optional values are preserved; your design and protobuf message format do not need to change.

Validation follows the selected result view

For APIs using result views, generated clients now validate the fields in the selected view.

For example, your full response might be:

:::json
{"id": "abc", "details": {"name": "Ada"}}

And a tiny view might return just:

:::json
{"id": "abc"}

The tiny response no longer triggers a missing-details error. Validation still checks id, including any rules you've defined for it. This applies to HTTP and gRPC, including streamed results, and fixes related WebSocket client panics.

More fixes for streams, inputs, generated commands, and docs

**Streams finish cleanly.** An empty successful WebSocket stream now closes normally. Server-sent events preserve optional values—including the difference between an absent value and an empty string—and report write or flush failures. Canceled gRPC calls retain their context cause and transport details; a separate cleanup failure remains visible. **Empty gRPC collections remain valid.** Protobuf cannot distinguish an empty list or map from an omitted one. Goa accepts both while enforcing your length and item rules: a design requiring at least one item still rejects an empty list. Nil collection wrappers inside maps also convert safely instead of panicking. **Clients and servers agree on everyday inputs.** A whole-query map reads `?a=1&b=2`, matching what the generated client sends. Float query values use compact text that preserves their value. gRPC byte metadata containing `[]byte{65, 66}` now sends `"AB"` instead of `"[65 66]"`; float metadata respects the declared precision. **Validation catches the right mistakes.** Required primitive JSON array items reject `null`. An exclusive maximum of `10` rejects `10` itself. Multipart bodies are decoded and validated before the service payload is built. **Shared types and application APIs.** Named string credentials retain their Go types, custom HTTP path types keep their imports, and shared errors use the exact declared type. `OneOf` constructors and accessors make the selected alternative explicit. Interceptors receive read-only information, and API-level errors can be reused where you explicitly select them. **More useful commands and documentation.** Generated command starters execute calls, print results, consume supported streams, and return failures. Whole-message gRPC flags accept protobuf JSON. OpenAPI output better reflects views, security, bytes, and streams. Example values stay stable across generation order changes; expect a one-time refresh when upgrading. Generated HTTP clients also report read and close failures for response bodies they consume. Methods that return a raw body leave it open for you to use and close.

A clearer JSON-RPC model

Ordinary calls use one HTTP request and response. Server streams use explicit server-sent events, followed by a final response that completes the opening request. IDs, notifications, batches, invalid requests, errors, and media types are handled consistently.

Caller-selected views now carry { "view": ..., "body": ... } inside result. Designed errors carry { "name": ..., "body": ... } inside error.data; unknown errors remain available in their original JSON-RPC form.

These formats need matching clients and servers. JSON-RPC WebSocket, client-streaming, and bidirectional generation have been removed. Use unary JSON-RPC, JSON-RPC server-sent events, ordinary HTTP WebSocket, or gRPC instead. The upgrade guide covers the changed stream methods and custom-client updates.

Upgrading to v3.31.1

From v3.30.x, this is a substantial upgrade with intentional breaking changes. Goa stays on the goa.design/goa/v3 module path, but some generated APIs and message formats have changed. Start with the upgrade guide.

Update the module and command together:

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

Regenerate the complete gen tree, compile and test your application, and review the diff. A second generation should produce no further changes. Avoid mixing output from different Goa versions.

Check handwritten code that uses OneOf, interceptors, multipart decoders, protobuf scalar literals, generated helpers, or command starters. Some signatures have changed. goa example preserves existing files; it does not update that code for you. The guide also explains newly rejected designs, such as ambiguous HTTP responses and conflicting shared error names.

For gRPC, install protoc-gen-go v1.36.12 and protoc-gen-go-grpc v1.6.2 before regenerating. This release includes gRPC v1.83.2.

Official plugins and examples have matching v3.31.1 tags. Update goa.design/plugins/v3 too; custom plugin authors should follow the generator API migration table.

Goa still supports Go 1.25. Examples and plugins require Go 1.26. If a generated starter needs Clue and you're staying on Go 1.25, pin goa.design/clue@v1.2.6 before tidying; Clue v1.3.0 requires Go 1.26.

Plan client/server deployment together where needed

Changed JSON-RPC errors, selected views and streams; affected gRPC views and metadata; and optional primitive HTTP SSE data need matching generated peers. Ordinary rolling deployment does not guarantee compatibility for these exchanges.

Protobuf field numbers and binary types remain compatible, but older clients cannot express presence for a required zero value. Update affected clients before enabling the new server's presence checks, or deploy both peers together.

There is no persisted-data migration. Keep your previous binaries, dependencies, design, handwritten code, and generated output so you can restore them together. Roll back both peers for changed exchanges. The cancellation runtime fix needs no coordinated deployment.

Already on v3.31.0?

Your upgrade is smaller: update the module and command, then regenerate for the recursive gRPC collection fix. v3.31.1 adds no further breaking API or message-format changes and needs no coordinated deployment.

One issue to keep in mind

Custom uuid.UUID query fields can still produce client code that does not compile (#3924); this also affects v3.30.0. For now, use String with FormatUUID and convert in your implementation. Server-side text decoding is supported; the corresponding client-side conversion remains to be fixed.

Thank you

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

For the individual changes, see the generation upgrade [#3971], named strings [#3984], gRPC cancellation [#3986], empty collections [#3988], and recursive collections [#3990], plus the synchronized examples [#219], complete example builds [#220], and plugins [#271].