v2.39.0

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

v2.38.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

v2.37.3

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

v2.37.2

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

v2.37.1

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

v2.37.0

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

v2.36.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

v2.35.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

v2.34.2

Overview

TLS-Aware URL Scheme Detection

Huma now correctly uses the https URL scheme when TLS is configured, and http when it is not. Previously, the scheme detection could be incorrect in certain scenarios.

Time Wrapper Parsing Fix

Fixed an issue where time wrapper types failed to parse correctly, resolving #844.

What's Changed

• fix: correct example format for tags in Pet struct by @vikyw89 in #858
• docs: add links to hire me by @danielgtaylor in #869
• Revert "docs: add links to hire me" by @danielgtaylor in #890
• chore(deps): bump github.com/gofiber/fiber/v2 from 2.52.7 to 2.52.9 by @dependabot[bot] in #882
• Fix code samples in the response output documentation by @prnvbn in #927
• fix: use "http" URL scheme only if no TLS is used by @leonklingele in #905
• fix: failed to parse time wrapper, close #844 by @zhenzou in #924
• Minor linting/formatting by @wolveix in #936

New Contributors

• @vikyw89 made their first contribution in #858
• @prnvbn made their first contribution in #927
• @leonklingele made their first contribution in #905
• @zhenzou made their first contribution in #924

Full Changelog: v2.34.1...v2.34.2

v2.34.1

Overview

This bugfix release fixes an issue regarding content types that was inadvertently introduced while adding a feature in v2.34.0. The previous behavior is restored while still supporting the new feature.

What's Changed

• fix: content type bug introduced in #850 by @danielgtaylor in #854

Full Changelog: v2.34.0...v2.34.1