Overview

This release adds native support for stdlib UUIDs, cuts compile times for large APIs, and brings a big batch of correctness fixes across request limits, defaults, validation, and the Fiber adapter. It also raises the minimum Go version to 1.26 and includes a few intentional breaking changes, so please read the upgrade notes below.

Upgrade Notes

• Minimum Go version is now 1.26. Dependencies have been bumped too, picking up a few vulnerability fixes (#1149)
• Raw bodies now have default limits. Non-multipart RawBody operations (e.g. []byte uploads) now get the same default 1 MiB MaxBodyBytes and 5s BodyReadTimeout as regular bodies. Endpoints accepting larger or slower raw uploads should set these explicitly (-1 for unlimited) (#1095)
• Multipart now honors MaxBodyBytes. An explicitly set MaxBodyBytes is now enforced on multipart requests. Multipart remains exempt from the defaults, so existing uploads keep working unless you've set a limit (#1094)
• Overflowing default tags panic at startup. For example, int8 with default:"128" previously wrapped silently to -128; it now fails at registration (#1142)
• Out-of-range bound tags panic at startup. For example, int8 with maximum:"500". int8, int16, uint8 and uint16 fields also now advertise minimum/maximum from their Go type, so generated specs will change (#1143)

Security Fix

A malformed Accept header such as application/json;,b caused a panic during content negotiation. On net/http-based adapters this dropped the request; on Fiber, which doesn't recover handler panics unless the recover middleware is used, it crashed the server process. This affects v2.26.0 onwards, so upgrading is recommended. (#1128)

Native Stdlib UUIDs

On Go 1.27+, fields using the new standard library uuid.UUID type are automatically documented as type: string with format: uuid, with no struct tag needed. (#1051)

Faster Compile Times

huma.Register, sse.Register and the convenience helpers (huma.Get, huma.Post, ...) now keep their generic parts tiny, so Go no longer compiles a full copy of the registration logic for every input/output pair. In a 200-operation benchmark package, build time dropped from 3.38s to 0.64s. There are no API or runtime changes. (#1115, #1117)

New Features

• String SSE event IDs via sse.Message.IDString, for UUIDs, cursor tokens and other opaque IDs (#1086)
• Schema can be unmarshalled from JSON, including $ref, x- extensions and nullable types, and is ready for Validate once decoded (#1144)

Validation & Defaults Fixes

• {"type": "null"} is now validated. Previously it accepted any value, so an anyOf with a null branch skipped the constraints of its other branches (#1120)
• Numeric request parameters which overflow the destination Go type (e.g. 300 into an int8) now return 422 instead of silently wrapping (#1096)
• default tags on encoding.TextUnmarshaler types (e.g. a duration with default:"10s") are now applied via UnmarshalText instead of panicking (#1126)
• Defaults are now applied to absent exploded query arrays (#1116) and missing multipart form values (#1150), and array parameters accept JSON array defaults such as default:"[\"a\",\"b\"]" (#1125)
• Value-less query flags followed by other parameters (e.g. ?flag&foo=bar) are now detected correctly (#1097)
• PathBuffer.Pop restores the exact offset, fixing wrong error locations after discriminator errors (#1136)
• casing.Camel and casing.Join no longer panic or double-apply transforms when a transform removes a part (#1113)

Request Body Fixes

• A body of exactly MaxBodyBytes is now accepted instead of returning 413 (#1131)
• Multipart file handles are now closed after mime-type validation (#1085)

OpenAPI Fixes

• RawBody alongside Body no longer documents an extra application/octet-stream media type (#1134)
• The example tag on a Body field is now set as the media type example, since many tools ignore examples next to a $ref (#1101)

Adapter & Autopatch Fixes

• humafiber: multiple Set-Cookie headers are now sent as separate header lines instead of being comma-joined (#1137)
• humafiber (v2): autopatch now works, as its internal requests get a default Host (#1140)
• autopatch: PATCH responses are no longer compressed twice (#1130), and $refs are resolved when making the PUT schema optional (#1080)

Docs UI & Documentation

• Updated Scalar (1.76.0), Stoplight Elements (9.0.29) and SwaggerUI (5.34.0). Scalar no longer needs 'unsafe-eval' in its CSP, and its fonts now load (#1145)
• Clarified that router-agnostic middleware runs after route resolution (#1088)
• Documented that humafiber doesn't decode streamed request bodies (#1118)
• Added SwaggerUI persistAuthorization to the DocsRendererConfig example (#1122)

What's Changed

• fix(queryparam): correctly detect flag/bool value which is followed by a non-flag by @leonklingele in #1097
• docs: replace Zuplo sponsorship with SerpApi by @danielgtaylor in #1106
• feat: native support for stdlib UUIDs introduced in Go 1.27 by @leonklingele in #1051
• perf: keep Register's generic part small to cut compile time by @iyuneev in #1115
• fix(casing): stop transforming an index after its part is removed by @youdie006 in #1113
• perf: keep sse.Register and convenience generic parts small by @robtme in #1117
• fix: apply defaults to absent exploded query arrays by @Arvin-Lee in #1116
• docs(humafiber): note streamed request bodies are not decoded by @robtme in #1118
• docs: show SwaggerUI persistAuthorization in DocsRendererConfig example by @ize-302 in #1122
• fix: validate the null type by @jahirulislam-forgent in #1120
• fix: accept request bodies of exactly MaxBodyBytes by @APX403 in #1131
• fix: Allow autopatch to resolve refs, when making the put schema optional by @lucaspopp-wbd in #1080
• fix: don't document application/octet-stream for RawBody alongside Body by @HawkForge in #1134
• fix: restore the exact offset in PathBuffer.Pop by @vyrnsynx in #1136
• fix: apply default tags via TextUnmarshaler by @vulragrag-star in #1126
• fix: reject numeric request parameters which overflow the destination Go type by @leonklingele in #1096
• fix: reject overflowing default tags at registration by @robtme in #1142
• fix: advertise small int bounds and reject out-of-range bound tags by @robtme in #1143
• feat: support unmarshalling JSON into Schema by @robtme in #1144
• chore: update docs renderers to latest versions by @robtme in #1145
• fix(negotiation): don't panic on empty q param in SelectQValueFast by @dannyshafer in #1128
• fix: close multipart file handles after mime-type validation by @stareezy-1 in #1085
• fix: surface Body example tag as the media type example by @SillyZir in #1101
• feat: support string SSE event IDs by @stareezy-1 in #1086
• fix(autopatch): prevent double compression of PATCH responses by @Arvin-Lee in #1130
• fix: accept JSON array defaults on array parameters by @youdie006 in #1125
• chore: bump dependencies and minimum Go to 1.26 by @robtme in #1149
• fix(humafiber): default the Host so autopatch works on Fiber v2 by @APX403 in #1140
• fix(humafiber): keep multiple Set-Cookie headers separate by @APX403 in #1137
• fix(multipart): respect MaxBodyBytes limit by @leonklingele in #1094
• fix: respect MaxBodyBytes limit for raw bodies by @leonklingele in #1095
• docs: clarify router-agnostic middleware runs after route resolution by @stareezy-1 in #1088
• fix: apply the default tag to missing multipart form values by @youdie006 in #1150

New Contributors

• @iyuneev made their first contribution in #1115
• @youdie006 made their first contribution in #1113
• @Arvin-Lee made their first contribution in #1116
• @ize-302 made their first contribution in #1122
• @jahirulislam-forgent made their first contribution in #1120
• @APX403 made their first contribution in #1131
• @HawkForge made their first contribution in #1134
• @vyrnsynx made their first contribution in #1136
• @vulragrag-star made their first contribution in https://github.com/danielgtaylor/hu...

v2.39.1

Overview

A patch release: correctness fixes for resolvers, validation, and response handling, plus a dependency refresh.

Response Status Visible to Middleware Again

WithContext context propagation in v2.39.0 copied the response status by value, so middleware that called WithContext and then read Status() after next() always saw 0 instead of the status the handler set, breaking access logging and telemetry. The status is now shared by every context copy across all adapters, restoring the pre-2.39 invariant while keeping context propagation intact. (#1081)

Resolvers & Defaults in Arrays and Maps

• Nested resolvers now run for fixed-size arrays ([2]Item), not just slices (#1076)
• A resolver on a named collection type (e.g. type Coords [2]float64) no longer panics, and is no longer conflated with a resolver on its element type, which previously ran the element's resolver twice and the collection's never (#1082)
• Values reached through a map are now written back after being walked, so applying a default no longer panics with reflect: reflect.Value.Set using unaddressable value and resolver mutations are no longer silently discarded (#1082)

Stricter email and uri Formats

Validation for two string formats is tighter, so payloads that previously passed may now return 422:

• email / idn-email accept an addr-spec only; full mailbox forms with a display name (Name <[email protected]>) are rejected
• uri / iri require an absolute URI with a non-empty scheme, while relative references remain valid under uri-reference / iri-reference (#1068)

Validation Robustness

• An unresolvable schema $ref during Validate now reports expected schema $ref to resolve: ... instead of panicking on a nil dereference, covering discriminators and map[string]any / map[any]any values (#1065)
• Named numeric slice parameters (e.g. type IDs []int64) are built with their declared element type and validated with item, length, and uniqueness constraints intact (#1074)

Other Fixes

• Resolver errors that wrap a HeadersError now contribute their headers to the response, matching the handler error path (#1070)
• A nil interface response body no longer panics in the schema link transformer (#1072)
• Dependencies updated (#1066)

What's Changed

• fix: do not panic on unresolved schema $ref during Validate by @baiyuxi930826 in #1065
• chore: update dependencies by @wolveix in #1066
• fix: tighten format email and uri validation by @baiyuxi930826 in #1068
• fix: preserve wrapped resolver error metadata by @ggmolly in #1070
• fix: handle nil interface response bodies by @ggmolly in #1072
• fix: parse named numeric slice parameters by @ggmolly in #1074
• fix: share response status across WithContext copies by @wolveix in #1081
• fix: run nested resolvers in fixed arrays by @ggmolly in #1076
• fix: distinguish collection and element matches when walking input by @wolveix in #1082

New Contributors

• @baiyuxi930826 made their first contribution in #1065
• @ggmolly made their first contribution in #1070

Full Changelog: v2.39.0...v2.39.1

v2.39.0

Overview

This release adds a new framework adapter, a handful of developer-facing features, and a large batch of correctness fixes spanning SSE, the Fiber adapter, schema generation, and validation.

Echo v5 Support

The humaecho adapter now supports Echo v5 alongside the existing versions. (#959)

No More Faulty Duplicate-Schema Panics

Registering operations that use inline structs with differing field names (and an empty operation ID) previously panicked at startup on a false-positive duplicate-schema collision. Conflicting names are now auto-incremented deterministically (Request, Request1, Request2, ...), so the app starts and the generated spec stays readable. (#893)

Context Propagation to Adapters

WithContext now propagates the context directly into the underlying adapter's own context wrapper (bun, chi, echo, fiber, gin, go, httprouter) instead of relying on a generic sub-context, so cancellation and context values flow correctly through the request lifecycle. (#867)

SSE Streaming on Fiber / fasthttp

Server-Sent Events (and other streaming responses) previously failed on the Fiber adapters with unable to flush, since fasthttp doesn't implement http.Flusher. SSE now streams correctly on Fiber v2 and v3 via an internal streaming hook, with no new public API and fasthttp remaining an indirect dependency. (#1059)

More SSE Improvements

• Response headers are now flushed before the user handler runs, so EventSource.onopen fires immediately rather than waiting for the first event (#1038)
• Comments can now be sent over SSE streams, a common way to keep connections alive (#1054)

New Features

• Schema.Const for pinning a schema to a single allowed value (#1004)
• Customizable docs renderer config for finer control over the documentation UI (#1024)
• encoding.TextUnmarshaler support for slice query parameters, matching the existing behavior for scalar params (#1021)
• Non-file JSON form-data fields: multipart form fields tagged contentType:"application/json" are now unmarshalled and validated (#1060)

Validation & Schema Fixes

• Integer enums no longer always fail validation on query/path parameters; numeric enum values are now compared numerically rather than by strict Go type (#1050)
• Content-Type validation is now case-insensitive per RFC 9110, so e.g. Application/Json no longer returns 415 (#1052)
• Path parameters are always marked required: true in the generated spec, per the OpenAPI specification (#1011)
• Prevented a panic (and dropped response) in uniqueItems validation when array items are unhashable types, now returning 422 correctly (#1045)
• The json:",inline" tag is now honored for embedding anonymous fields in schemas (#1006)
• Hidden route schemas are no longer leaked into the generated spec (#1032)

Adapter & Robustness Fixes

• humafiber (v2): corrected EachHeader iteration (it previously invoked the callback once per byte, breaking cookie reads) and switched BodyReader to Body() for automatic request-body decompression (#1058)
• autopatch: prevented chi route-context reuse from recursing internal GET sub-requests back into the generated PATCH handler and panicking (#1049)
• Fixed a URL parsing panic in getAPIPrefix when server URLs contain template variables like {port} or {version} (#1027)
• The read deadline is now cleared after the request body is read, so a slow handler can't cause a background read to time out and cancel the connection context (#1028)

Docs UI & Documentation

• Forms are now permitted in the docs UI CSP (#1036)
• Added allow-downloads to the Stoplight CSP so the Export button works (#1048)
• Updated Restish references to v2 (#1041)

What's Changed

• Avoid leaking hidden route schemas by @wolveix in #1032
• fix: parse server vars on getAPIPrefix to avoid parsing URL panic by @kukymbr in #1027
• Add encoding.TextUnmarshaler support for slice query parameters by @B94715 in #1021
• fix: enforce required=true for path parameters per OpenAPI spec by @Yanhu007 in #1011
• huma: clear read deadline on reading by @atn18 in #1028
• feat: support customizing the docs renderer config by @johnletey in #1024
• feat: add Schema.Const by @seanwu1105 in #1004
• Permit forms in docs UI CSP by @wolveix in #1036
• fix(sse): flush response headers before user handler runs by @alswl in #1038
• docs: update Restish v2 references by @danielgtaylor in #1041
• fix: add 'allow-downloads' to CSP for stoplight by @ovikk13 in #1048
• Echov5 support by @sharath-09 in #959
• fix(autopatch): prevent chi route-context reuse in internal requests by @wolveix in #1049
• fix: support json inline tag for embedding anonymous fields in schema by @lsdch in #1006
• fix: compare numeric enum values numerically by @wolveix in #1050
• fix: content type validation should be case insensitive by @hlavacekvit in #1052
• fix(humafiber): correct Fiber v2 EachHeader iteration and body decompression by @wolveix in #1058
• feat: propagate context to adapters on WithContext by @costela in #867
• Support sending comments with SSE by @seanwu1105 in #1054
• fix(sse): support streaming responses on Fiber/fasthttp adapters by @wolveix in #1059
• fix: prevent panic in uniqueItems validation for unhashable types (#1042) by @ArdyJunata in #1045
• fix: avoid faulty duplicate detection by @Mcklmo in #893
• feat(form-data): handle unmarshalling and validation of non-file JSON form data fields by @lsdch in #1060

New Contributors

• @kukymbr made their first contribution in #1027
• @B94715 made their first contribution in #1021
• @Yanhu007 made their first contribution in #1011
• @atn18 made their first contribution in #1028
• @johnletey made their first contribution in #1024
• @seanwu1105 made their first contribution in #1004
• @alswl made their first contribution in #1038
• @ovikk13 made their first contribution in #1048
• @sharath-09 made their first contribution in #959
• @hlavacekvit made their first contribution in #1052
• @ArdyJunata made their first contribution in #1045
• @Mcklmo made their first contribution in #893

Full Changelog: v2.38.0...v2.39.0

Overview

Fiber v3

This release adds support for Fiber v3. Dedicated v2 functions have been added to ensure support for both.

What's Changed

• Fix header regression by @wolveix in #1007
• feat(humafiber): add Fiber v3 support by @wheinze in #962
• Accept empty base64 inputs by @wolveix in #1013
• chore(deps): bump github.com/gofiber/fiber/v3 from 3.1.0 to 3.2.0 by @dependabot[bot] in #1018
• Propagate underlying context to GET/PUT requests in the autopatch handler by @alixinne in #1019
• chore(deps): bump github.com/gofiber/fiber/v2 from 2.52.12 to 2.52.13 by @dependabot[bot] in #1022

New Contributors

• @wheinze made their first contribution in #962
• @alixinne made their first contribution in #1019

Full Changelog: v2.37.3...v2.38.0

Overview

This bugfix release fixes a few minor bugs and typos from previous releases.

This also adjusts the HTTP status code returned by Huma if marshaling a response fails, from 200 to 500.

What's Changed

• Fix: add allow-popups to CSP sandbox for OAuth popups by @Micaso in #987
• Fix: use epsilon tolerance in multipleOf float validation by @smazurov in #989
• Fix typo in groups.md documentation by @Its-Haze in #995
• Fix relative schema urls by @wolveix in #990
• Return HTTP 500 if marshaling fails by @wolveix in #997
• Handle contentEncoding and contentMediaType keys by @NPellet in #919
• Chore(deps): bump github.com/gofiber/fiber/v2 from 2.52.11 to 2.52.12 by @dependabot[bot] in #984

New Contributors

• @Micaso made their first contribution in #987
• @smazurov made their first contribution in #989
• @Its-Haze made their first contribution in #995
• @NPellet made their first contribution in #919

Full Changelog: v2.37.2...v2.37.3

Overview

This bugfix release fixes an issue with how form data was being documented in OpenAPI.

This also fixes embedded objects with valid JSON tags being incorrectly embedded in the OpenAPI docs.

What's Changed

• Don't embed embedded objects with valid JSON tags by @wolveix in #978
• Fix OpenAPI path prefix regression from $schema fix PR by @wolveix in #979
• Fix form param doc regression by @wolveix in #981

Full Changelog: v2.37.1...v2.37.2

Overview

This bugfix release fixes an issue regarding the Swagger UI docs renderer, as well as fixes an issue preventing Groups from using the configurable options released in v2.37.1.

This also brings interface constructors to humamux.

What's Changed

• Export Gorilla Mux interface constructors by @RangelReale in #965
• fix(api): use proper CSP hash for inline script in Swagger doc renderer by @leonklingele in #977
• fix(group): ensure "Group" satisfies the configProvider interface by @leonklingele in #976

Full Changelog: v2.37.0...v2.37.1

Overview

Dropped Explicit IDN-Hostname Validation

This validation unintentionally imported an external library to the base Huma library. Since this was not a requested feature, it has been removed for now. The idn-hostname format value has become an alias for hostname in the meantime.

Operation ID Normalization

Spaces in operation IDs get automatically converted to hyphens now.

Optimizations & Fixed Memory Leak

Various internal operations have been optimized (~7% overall improvement): #973 (comment)

A memory leak when using MultipartFormFiles has been resolved.

New Configurable Options

Allow Additional Properties By Default

A new config option has been added to allow additional properties by default. This can be set in the API config.

config.AllowAdditionalPropertiesByDefault = true

Fields Optional By Default

A new config option has been added to set fields to optional by default, rather than required by default. This can be set in the API config.

config.FieldsOptionalByDefault = true

Strict Query Parameters

A new config option has been added to forcibly reject unknown query parameters. This can be set in the API config, or per-operation.

config.RejectUnknownQueryParameters = true

Framework & Dependency Updates

• Upgraded to Go 1.25

What's Changed

• chore(registry): drop random suffix out of variable name by @leonklingele in #972
• Implement Registry and Query Validation Options by @wolveix in #925
• Resource optimizations, Go 1.25, remove IDNA library, add benchmark CI by @wolveix in #973
• Additional docs + normalize operation IDs by @wolveix in #974
• chore(api,docs): update unpkg libraries, specify SRI hash, add strict CSP by @leonklingele in #916

Full Changelog: v2.36.0...v2.37.0

Overview

This release is larger than usual. Key changes:

Unique Operation ID Enforcement

Operation IDs are now enforced to be unique, preventing collisions in generated OpenAPI specs. (Fixes #910)

Native Docs Renderer Support

Native support for Scalar and SwaggerUI alongside the default Stoplight Elements. Configure via config.DocsRenderer = huma.DocsRendererScalar.

Expanded Content-Type Handling

• Graceful handling when clients omit Content-Type for non-JSON endpoints
• Support for charset definitions in Content-Type header
• Updated OpenAPI media types to align with newer standards
• Validation support for non-JSON request body content types

Form Handling Improvements

• Form data now required by default for clearer validation behavior
• Fixed panic when text value sent to FormFile field

Schema & Validation Enhancements

• Fixed $schema field reusing links for identical objects
• Fixed duplicate example rendering in some docs renderers
• Improved $schema URL handling (with docs for disabling it)
• Extended netip.Addr to support IPv6; added new ip format for v4/v6
• Fixed incorrect schema generation for arrays

Framework & Dependency Updates

• Fiber adapter now uses Body() instead of BodyRaw() for automatic decompression
• Upgraded to Go 1.24

What's Changed

• Support Forcing Unique Operation IDs (Fixes #910) by @wolveix in #937
• Support charset definitions in content type header by @wolveix in #951
• chore(deps): bump github.com/gofiber/fiber/v2 from 2.52.9 to 2.52.11 by @dependabot[bot] in #955
• Fix various issues by @wolveix in #961
• Require form data by default by @wolveix in #963
• Fix: Support non-JSON content types for request body validation by @roidelapluie in #926
• Allow empty content type from client by @wolveix in #964
• Docs for disabling the $schema field by @wolveix in #966
• fix: use Body() instead of BodyRaw() in fiber to auto decompress the req body by @akkuman in #928
• proposal: extend netip.Addr support to ipv6 by @costela in #792
• Add missing ip format to docs by @wolveix in #967
• Update OpenAPI media types to newer standard format by @domdomegg in #899
• fix: prevent panic when text value sent to FormFile field by @alexisvisco in #932
• Improve $schema URL by @wolveix in #968
• Fix incorrect schema generation for arrays by @wolveix in #970

New Contributors

• @roidelapluie made their first contribution in #926
• @akkuman made their first contribution in #928
• @domdomegg made their first contribution in #899
• @alexisvisco made their first contribution in #932

Full Changelog: v2.35.0...v2.36.0

Overview

Moved this release as it was incorrectly tagged as v2.34.3.

Improved Error Messaging for Form Pointers

Pointer panic messages now explicitly include “Form” where applicable, making debugging clearer and resolving #892.

Expanded String Format Support

Added support for duration and idn-hostname string formats, improving schema expressiveness and validation coverage.

Header Parsing Fix

Fixed several subtle issues in header detection that occurred when output fields were slices, arrays, or maps, which could cause headers (notably []*http.Cookie) to be incorrectly applied or documented. The parsing logic now correctly inspects the root type of collection fields and adds support for hidden headers, allowing them to be excluded from generated OpenAPI documentation. These changes resolve multiple long-standing documentation and serialization bugs without introducing new behavior.

What's Changed

• fix: include “Form” in pointer panic message (fixes #892) by @wolveix in #938
• feat: support duration and IDN-hostname string formats by @wolveix in #939
• docs: add simple HTML docs by @wolveix in #941
• fix: header parsing by @wolveix in #944
• perf(schema): optimize convertType with fast paths for compatible types by @baagod in #931
• Added exhaustive error code wrappers by @rhodeon in #876

New Contributors

• @baagod made their first contribution in #931
• @rhodeon made their first contribution in #876

Full Changelog: https://github.com/danielgtaylor/huma/compare/v2.34.2...v2.34.3