Library / SDK
danielgtaylor/huma avatar
danielgtaylor/huma

Huma turns Go structs into an OpenAPI 3.1 contract without taking your router

Huma REST/HTTP API Framework for Golang with OpenAPI 3.1

4,532 stars302 forksGoMIT

At a glance

What is it?
Huma sits between your HTTP router and your handler functions, deriving the OpenAPI 3.1 document, request validation and content negotiation from annotated Go types. The trade is a large dependency surface and a Go 1.26 floor in exchange for documentation that a code change cannot silently invalidate.
Who is it for?
Adopt huma when the spec is the deliverable, external clients depend on it, and you already run a router you do not want to replace. Do not adopt it for a small internal service that needs one handler and a JSON body, or on a team pinned below Go 1.26, and look past it if a lean dependency graph matters more than generated documentation.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 3 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • danielgtaylor/huma4,532 ★ · +112
Star history
Repository2026-09-232026-11-14
danielgtaylor/huma4.4k4.5k

112 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The struct tags are the schema, not a comment beside it

Huma's central claim is that the documentation and the code cannot drift apart, because both come from the same Go type. When you register an operation you pass a pointer to a request struct and a pointer to a response struct. Huma generates JSON Schema from those Go types, and that schema ends up in the OpenAPI 3.1 document. No separate spec file exists to fall behind.

The same reflection pass powers input validation. A field marked required and given a length constraint in its struct tag becomes both a validation rule and a documented constraint, so the error a client receives and the line in the spec come from one declaration. This is the FastAPI model: the project states it was inspired by FastAPI, and the mechanism is the same one, that a Pydantic class is simultaneously the serializer, the validator and the schema source.

The part that is not FastAPI is the router. The adapters/ directory holds the glue for concrete routers. The README puts incremental adoption first among its goals: document routes you already have, keep your middleware, keep your logging and metrics, and only let huma handle schema generation, serialization and error formatting for the operations you register.

Every operation carries its own size limit and an RFC 9457 error shape

Registering an operation gives you a request size limit with a sane default, per operation rather than per server. That matters for a service where one upload endpoint and one JSON endpoint sit behind the same port, which is the common case in Go services that started as a monolith.

Errors default to `application/problem+json`, the media type defined in RFC 9457, so a failed validation returns a structured problem document instead of a hand-rolled error string. error.go and validate.go produce it. You can change the content type, but the default is the standard one, and clients written against RFC 9457 will parse it without a special case.

Content negotiation reads the `Accept` header and picks between JSON and, if you enable it, CBOR. The formats/ directory and the cbor dependency in go.mod hold that. Two other pieces are easy to miss. Conditional requests have helper support for headers such as `If-Match` and `If-Unmodified-Since` under conditional/. And huma can emit a JSON Schema `$schema` property, plus `describedby` link relation headers, on returned objects, so an editor in a consumer's IDE can validate and complete against the same schema the server uses.

One PATCH handler for merge patch, JSON Patch and shorthand

The autopatch/ directory generates a `PATCH` operation from an existing resource type. One model declaration yields three patch dialects: RFC 7386 JSON Merge Patch, RFC 6902 JSON Patch, and shorthand patches from github.com/danielgtaylor/shorthand, which the module requires at v2.4.0. The JSON Patch side is backed by github.com/evanphx/json-patch/v5 at v5.9.11.

This removes a category of hand-written code that tends to be inconsistent: a service that ships `PUT` only usually means partial update is either unsupported or does a read, mutate, write cycle in each handler. With autopatch, the diff semantics are declared once and the same handler serves clients that prefer merge semantics and clients that send an operation array.

Generated docs use Stoplight Elements, so a running service exposes its own interactive documentation. Since the spec comes from the handler registration, a route that no longer exists disappears from the docs on the next start. That property is worth more than the documentation itself for a service with contract consumers.

Installing on Go 1.25 and pointing huma at an existing router

Installation is a `go get` of the module path `github.com/danielgtaylor/huma/v2`, and because the major version lives in the path, every import carries the v2 suffix. The README states that Go 1.26 or newer is required, and go.mod declares the same floor.

That floor is the first thing to check on an existing team. A service pinned to an older Go toolchain cannot take the dependency at all. Two files at the repository root handle UUID generation differently depending on the Go release, which is a hint that the project tracks the standard library closely enough to branch on it.

The maintenance picture is simple: the last push on the default branch was on 2026-10-28, the newest release listed is v2.40.0 from 2026-10-27, and the repository ships an MIT LICENSE.md.

Your first real use is short. Build a config around the router you already run, hand it a service name and version, register one operation with a typed input struct, and start the binary. The CLI inside humacli/ reads its port from arguments or the environment, so `-p 8000`, `--port=8000` and `SERVICE_PORT=8000` all work without touching code, and startup actions and graceful shutdown come built in. The OpenAPI document is then served by the running binary, so you can read the generated schema before writing a single client.

The module depends on seven routers while asking you to bring your own

This is the detail a skim misses. go.mod lists github.com/go-chi/chi/v5, gin, echo v4 and echo v5, fiber v2 and fiber v3, gorilla/mux, julienschmidt/httprouter and uptrace/bunrouter, plus cobra and pflag, as direct requirements of a project whose pitch is that you bring your own router. Even cobra and pflag come along, which is the cost of humacli shipping a built-in command line.

The reading is not that huma forces gin on you. It is that the adapters live inside the same module, so its go.mod pulls the other routers into your dependency graph. Teams who chose a router for a dependency audit will notice this in go.mod. The alternative arrangement, moving each adapter to its own module, is not what the repository does today.

The same pass flags the Go version story. The README advertises bringing your own router including Go 1.22 and later, while the module itself declares `go 1.26.0`. Both are true of different things, and the pair is easy to misread in either direction.

Where huma is the wrong tool

It is the wrong tool when the API is not the product. A service with three routes, one JSON body and no external consumers gains nothing from an OpenAPI document, and pays for the reflection pass, the schema layer and the adapter dependencies on every request path. For internal endpoints consumed only by code you also write, the standard library plus encoding/json is less machinery, and the RFC 9457 problem envelope that huma returns by default is another shape to work around.

It is also the wrong tool when you cannot move the Go version. The 1.26 floor is stated in the README and in go.mod, and there is no compatibility shim offered for older toolchains.

Read the repository layout before assuming coverage. There is no authentication layer, no database access and no migration tooling among the top level entries. There is humatest/ for tests, sse/ for server sent events, queryparam/, casing/, validation/, negotiation/, yaml/, formats/ and examples/, which is a framework of concerns rather than a full stack. The README also names documentation that cannot get out of date as a goal, yet the repository root carries README.md, README_CN.md and README_JA.md alongside a docs/ directory. The claim holds for the OpenAPI document, which is generated from code. It does not hold for the prose around it.

What actually differs from gin or echo

Gin and echo are routers first. You register a path, bind and validate a request inside the handler, and if you want a spec you add a generator such as swaggo or write the annotation layer yourself, then keep it in step with the handlers by hand. Huma inverts the order: the schema comes from the type, the validation comes from the tags, and the router is a pluggable interface, so the spec is a byproduct of the registration call rather than a second artifact to maintain.

The other difference is where the opinions sit. Gin and echo own the router, the middleware chain and the context object. Huma owns serialization, validation, error formatting, content negotiation and the OpenAPI document, and leaves the router, middleware and logging to whatever you already run. That is why incremental adoption is listed first among the project goals, and why the same operation can be served over chi, the Go 1.22 standard library mux, or a router you wrote.

The cost of that arrangement is the dependency surface described earlier, and the fact that handlers must use huma's registration signature rather than the router's own. Swapping away later means going through huma's API, not the router's.

Editorial conclusion

Adopt huma when the spec is the deliverable, external clients depend on it, and you already run a router you do not want to replace. Do not adopt it for a small internal service that needs one handler and a JSON body, or on a team pinned below Go 1.26, and look past it if a lean dependency graph matters more than generated documentation. Verify the schema shape first: register one operation with a typed request struct, start the binary with `-p 8000`, and read the OpenAPI document the service serves before you commit to the pattern, because every model you write afterwards inherits whatever that first output looks like.

Frequently asked questions

What is huma API?

Huma is a micro framework for building HTTP REST or RPC APIs in Go, described by OpenAPI 3.1 and JSON Schema. It generates the OpenAPI document, request validation and RFC 9457 problem errors from annotated Go types, and runs on top of a router you supply.

What Go version does huma require?

The README states that Go 1.26 or newer is required, and the module file declares go 1.26.0. The module path is github.com/danielgtaylor/huma/v2, so the /v2 suffix is part of every import.

Which routers can huma run on?

The README says to bring your own router, including the Go 1.22 and later standard library mux, and adapters exist in the adapters/ directory. The module also depends directly on chi, gin, echo v4 and v5, fiber v2 and v3, gorilla/mux, httprouter and bunrouter.

Does huma support CBOR and JSON Patch?

JSON is supported by default through content negotiation on the Accept header, and CBOR is optional. Automatic PATCH operations can be generated for RFC 7386 JSON Merge Patch, RFC 6902 JSON Patch, and shorthand patches.

Official sources

  1. danielgtaylor/huma on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/danielgtaylor-huma.svg)](https://hysenlabs.com/projects/danielgtaylor-huma)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/danielgtaylor-huma.svg)](https://hysenlabs.com/projects/danielgtaylor-huma)

Was this useful?