Goa v3.29.0

Goa v3.29.0 lets a single Goa design produce OpenAPI 3.2.0 documents, while making generated services, clients, and API descriptions more consistent. It is a v3 minor release: the public DSL remains backward compatible, but regeneration deliberately makes a few invalid wire values fail fast instead of being silently accepted.

Generate OpenAPI 3.2 from your Goa design

Goa can now generate OpenAPI 3.2.0 JSON and YAML alongside the existing 2.0 and 3.0 documents. That means an API team can publish a current contract for HTTP endpoints, streaming responses, server details, tags, named schemas, and type extensions from the design it already maintains.

Add this at the API level when you want the new output:

Meta("openapi:versions", "3.2")

Generation writes gen/http/openapi3.2.json and gen/http/openapi3.2.yaml. You may generate 2.0, 3.0, and 3.2 together, and may set a different 3.2 output location with Meta("openapi:path:3.2", "docs/openapi").

More predictable generation and stronger contracts

• Goa now normalizes a design once, after plugins have contributed to it and before generators read it. Generators no longer reshape the design as they run. The practical result is more stable generated code and examples, independent of generator order.
• When Goa itself reaches an internal generation invariant violation, goa gen now prints a useful stack trace and a clear bug-report request instead of failing opaquely.
• Generated union codecs now require both the discriminator and a non-null value. For example, {"type":"email","value":"a@example.com"} is valid; {"type":"email"} and {"type":"email","value":null} are rejected. This keeps a union’s selected branch and its value inseparable.
• Alias-chain validations and generated OpenAPI schemas now preserve the effective constraints defined by the design, including constraints on nested or computed body types.

Fixes across generated transports

• Fixed HTTP server code generation for result types that contain nested or sibling user types.
• Fixed WebSocket client code generation for a bidirectional stream whose result has views.
• Fixed a race when a shared HTTP error encoder handles concurrent requests.
• Corrected OpenAPI descriptions for server-sent event responses, schemas reached through result views, generated examples, and parameter formatting.
• Added an opt-in gRPC compatibility mode for services that need to accept clients using Goa’s earlier streaming protocol.
• Fixed goa gen when invoked from a directory outside the module tree.

Upgrade notes

1. Upgrade the module and regenerate as usual:

   go get goa.design/goa/v3@v3.29.0
   goa gen your/design/package

   Review the generated diff, build, and test your service before deployment. The refactoring that makes generation deterministic can change generated files without changing your DSL.

2. OpenAPI 3.2 is opt-in; add Meta("openapi:versions", "3.2") only when you want those files. Existing OpenAPI 2.0 and 3.0 output is unchanged unless you choose new version metadata.

3. If an external client sends JSON directly to a generated union codec, ensure it always includes a recognized discriminator and a non-null value. Goa has always generated the canonical {type, value} shape when marshaling unions; this release makes decoding enforce it too.

4. Existing gRPC streaming services require no change. Use Meta("grpc:stream:compat", "v1") only while supporting a client generated by the earlier Goa streaming protocol.

Included maintenance

Goa, its examples, and its Plugins repository were regenerated and tested against v3.29.0. The release also updates gRPC, Go tooling dependencies, and the project GitHub Actions.

Contributors

Thank you to Raphael Simon, Adam Bocim, and Jonathan Duck for the work in this release.

Links

• Full commit comparison
• Code generation guide
• gRPC guide
• OpenAPI 3.2 generation (#3940), gRPC compatibility (#3946), HTTP server fix (#3944), WebSocket client fix (#3947), union contract fix (#3950), and generator launch fix (#3953)