How danielgtaylor/huma works
Purpose and entry points
Huma is a Go library/framework for HTTP REST/RPC APIs. It layers typed operation registration, OpenAPI 3.1 generation, JSON Schema generation, validation, serialization, and standardized errors over an application-owned router and server. Consumers typically construct an API through a router adapter, register generic operations, then start net/http themselves. Core public surfaces are huma.go, api.go, and defaults.go.
API construction and router boundary
The API abstraction decouples Huma’s request/response pipeline from routing implementations. Router-specific packages translate route registration and request context behavior for Chi, stdlib Go mux, Gin, Echo, Fiber, Flow, httprouter, mux, and BunRouter:
• adapters/humachi/humachi.go
• adapters/humago/humago.go
• adapters/humagin/humagin.go
This is the principal integration boundary: applications retain their router, middleware, telemetry, and HTTP server lifecycle; Huma owns operation semantics.
Operation registration and execution pipeline
Generic registration helpers define an operation’s method, path, metadata, typed input, typed output, and handler. Registration both mounts a runtime route and contributes to the generated API description. At request time, the pipeline binds path/query/header/cookie/body inputs, applies defaults/resolvers, validates, invokes the handler, and serializes typed output or errors:
• api.go
• huma.go
• chain.go
Groups provide shared route prefixes, metadata, and middleware-like composition around sets of operations:
• group.go
Schema and OpenAPI model
Reflection over annotated Go input/output types produces reusable JSON Schema definitions and OpenAPI operation components. The registry manages schema identity/reuse, while OpenAPI types and generation maintain the externally consumable contract:
• schema.go
• registry.go
• openapi.go
Generated OpenAPI and per-resource schemas support documentation, code generators, mock servers, SDK/CLI tooling, and editor integrations without a separate design artifact.
Input validation and error boundary
Request parsing and validation enforce typed parameters, body constraints, and schema annotations before application handlers execute. Failures are converted to API error responses, defaulting to RFC 9457 application/problem+json; handlers can return structured errors through the same response boundary:
• validate.go
• validation/messages.go
• error.go
Supporting request concerns include form decoding, cookies, query parsing, and naming conversion:
• formdata.go
• cookie.go
• queryparam/queryparam.go
Response negotiation, transforms, and advanced HTTP behavior
Response production selects a registered representation from Accept, serializes output, applies transformers, and can stream server-sent events. JSON is the baseline; CBOR is an optional format registered by importing its package. Conditional-request helpers and automatic PATCH operations extend standard operation behavior:
• negotiation/negotiation.go
• transforms.go
• sse/sse.go
• formats/cbor/cbor.go
• conditional/params.go
• autopatch/autopatch.go
Runtime tooling and repository infrastructure
humacli optionally supplies argument/environment configuration, startup hooks, and graceful lifecycle integration; it does not replace the application’s HTTP server:
• humacli/humacli.go
humatest supports in-process API testing with the same runtime abstractions:
• humatest/humatest.go
The module is Go-based (go.mod), with CI, benchmarks, and documentation-site builds managed through GitHub Actions and MkDocs:
• go.mod
• .github/workflows/ci.yaml
• docs/mkdocs.yml
Main entry points: huma.go Operation registration · transforms.go Response production · chain.go Request pipeline · api.go API abstraction
Components 18
Application Integration
Application-owned router and server lifecycle.
- Application · Owns router, middleware, and HTTP server.
- Router adapters · Bridge supported routers to Huma's API abstraction.
adapters/humachi/humachi.go
Core Runtime
Typed operation registration and request execution.
- API abstraction · Decouples operation semantics from router implementations.
api.go - Operation registration · Defines typed operations and mounts runtime routes.
huma.go - Operation groups · Shares prefixes, metadata, and middleware-like behavior.
group.go - Request pipeline · Binds, resolves, validates, invokes, and serializes.
chain.go - Input validation · Enforces typed parameters and schema constraints.
validate.go - Problem error boundary · Produces RFC 9457 problem responses.
error.go - Response production · Negotiates representations and applies transformers.
transforms.go
API Contract
Generated OpenAPI and reusable JSON Schema.
- JSON Schema generation · Builds schemas from annotated Go types.
schema.go - Schema registry · Manages reusable schema identity and definitions.
registry.go - OpenAPI 3.1 model · Maintains the generated external API contract.
openapi.go
Extensions
Optional runtime behaviors and tooling.
- Content negotiation · Selects a registered response representation from Accept.
negotiation/negotiation.go - SSE streaming
sse/sse.go - CBOR format · Registers CBOR as an additional representation.
formats/cbor/cbor.go - Conditional & PATCH helpers · Adds conditional request and automatic PATCH behavior.
conditional/params.go - humacli · Provides configuration, hooks, and graceful lifecycle integration.
humacli/humacli.go - humatest · Runs APIs in process through the same abstractions.
humatest/humatest.go
Connections 20
- Application → Router adapters: selects router integration
- Router adapters → API abstraction: implements boundary
- Application → Operation registration: registers operations
- Operation registration → API abstraction: mounts routes through
- Operation groups → Operation registration: composes operations
- Operation registration → Request pipeline: creates runtime handler
- Operation registration → OpenAPI 3.1 model: contributes operations
- Operation registration → JSON Schema generation: reflects typed I/O
- JSON Schema generation → Schema registry: reuses definitions
- Schema registry → OpenAPI 3.1 model: supplies components
- Request pipeline → Input validation: validates bound input
- Input validation → Problem error boundary: converts failures
- Request pipeline → Response production: serializes handler result
- Problem error boundary → Response production: uses response boundary
- Response production → Content negotiation: selects representation
- CBOR format → Content negotiation: registers format
- SSE streaming → Response production: adds streaming output
- Conditional & PATCH helpers → Operation registration: extends operations
- humacli → Application: integrates startup lifecycle
- humatest → API abstraction: exercises in process