Proposal: OpenAPI endpoint DSL #760

Zaba505 · 2026-10-17T23:01:30Z

Zaba505
Oct 17, 2026
Maintainer

Important

Amended by revision 1. The package is openapi, and NewAPI returns an *API that is an http.Handler. Paths are built from typed values rather than templates, an operation is one call with its parts, and the router is chi. It adds a fourth open question.

Revision 2 answers question 2. The package is openapi/v3, and its document follows the latest minor version of OpenAPI 3: 3.2.0 today.

Revision 3 replaces how bodies are encoded. Every body names a typed codec, a Decoder[T] or an Encoder[T], on its operation, and nothing is assumed: no JSON default and no closed set of encodings. humus ships an opt-in openapi/v3/jsoncodec.

Revision 4 logs a response that fails after its status: an ERROR record, and the response cut short. Trailers are out of scope until a user asks for them.

Revision 5 answers questions 1, 3 and 4. A panic is answered by the catch-all, and the example keeps Postgres. The end user answers 404 and 405 with a required openapi.Unmatched, and the package's own rejections with openapi.RequestErrors. Problem details move to an opt-in openapi/v3/problem. No open questions remain.

Note

Part of the humus re-evaluation; see Proposal: humus on the bedrock process model, wave 4. It builds on Proposal: HTTP server foundation, which has landed as httpserver and httpservertest, and on wave 1. It depends on no other wave-4 proposal. It replaces the REST half of rest.Run and bedrock's runtime/http/rest DSL, and owns the rebuilt example/rest/shoppingcart. It blocks Proposal: authentication and authorization (wave 5), which adds security to REST's operations and to its document, and the wave-6 walkthroughs and AI tooling, which are written against this API.

Summary

A new package, rest, in the core module, builds an http.Handler from typed endpoints and serves the API's OpenAPI document. It is the DSL that bedrock v0.21.0 shipped as runtime/http/rest and that humus's rest.Run wrapped before the reset, kept where it works and changed where it breaks the process model or humus's principles:

The handler is an http.Handler, and its Service is httpserver's. The end user's Init calls rest.NewHandler, hands the handler to httpserver.NewService, and main is httpserver.Main. REST adds no Service, no Main and no test package. It inherits TLS, HTTP/2, the drain, the grace period, otelhttp and the server's settings, and its tests use httpservertest.
The DSL keeps its shape. An endpoint is composed inside out: GET, POST, PUT, PATCH and DELETE take a typed handler, then parameters, a body reader, a response writer and typed errors are layered on, and CatchAll completes it as a Route. Only a Route can be served, so every operation has an answer for every error.
Routing is net/http's ServeMux, not chi. Path parameters come from r.PathValue, and ServeMux sets Request.Pattern, so httpserver's spans are named after the route, such as GET /carts/{cartId}.
Mistakes fail when the handler is built, not on a request. NewHandler returns an error for a path parameter that the path and the endpoint disagree on, a response type that doesn't match the handler's, two bodies for one status, and the other mistakes the old DSL found only at request time, or never. ParamFrom panics for a parameter the endpoint didn't read, instead of returning a zero value.
REST's own error responses are problem details (RFC 9457), application/problem+json, and they are in the document. A panic of the end user's handler is answered by the route's catch-all, and recorded.
The OpenAPI document is generated with swaggest/openapi-go, as it was before the reset, once, when the handler is built, and served at the path the end user names.
The shoppingcart example comes back in the example nested module, as the reference service: its Init sources its settings from the Process, opens its Postgres pool through the Host, and registers the pool's close with OnStop.

func main() {
	httpserver.Main(app.Init, humus.WithTelemetry(app.BuildTelemetry))
}

Background

The DSL was bedrock's, and bedrock removed it. runtime/http/rest in bedrock v0.21.0 is the inside-out DSL: Endpoint, Route, Request[B], typed Param[T]s, ReadJSON, WriteJSON, ErrorJSON, CatchAll, and Build, which returns a bedrock.Builder[http.Handler]. bedrock v0.22.0 removed it with the rest of the Builder/Runtime layer. humus's rest.Run wrapped it in the server #680 replaced. story(rest): own the OpenAPI endpoint DSL inside humus #620 planned to copy the DSL into humus unchanged, and was closed for this re-evaluation.
The design is sound, and the end user's code reads well. The old shoppingcart's addcartitem.go declares each operation in one function, and its document is generated from the same declarations that decode the request. This proposal keeps that.
What breaks the process model. Build returns a bedrock.Builder, which is gone. The handler logs nothing and records nothing: an error answered by the catch-all disappears, since the example's catch-all drops it. And ReadFormFile calls r.FormFile, which writes a large upload to a temp file with os.CreateTemp, on the real filesystem rather than the Host's.
What fails silently or late.
- ParamFrom returns the zero value for a parameter the endpoint never read.
- Pattern drops a regular expression that doesn't compile, and then every request fails with 400.
- A parameter of an unsupported type fails on every request, with 400, as if the client were wrong.
- WriteJSON[Resp] documents Resp whatever the handler returns.
- Responses are written with json.NewEncoder(w).Encode(v), its error ignored, after the status is written, so a value that can't be encoded is a 200 with a broken body.
- Two ErrorJSONs at one status overwrite each other in the document.
REST's own errors are outside the document. A bad parameter or body is answered by writeValidationError with {"param": …, "error": …} and a 400 that no operation documents. The example's own errors are problem details, which it defined itself, and v0.15.0's rest had a ProblemDetail type (story(rest): Implement RFC 7807 Problem Details for error responses #385).
story(rest): add options for setting additional openapi values #283 asked for the document's optional fields, such as an operation's summary and description. The reset closed it. API.Description, and Summary, EndpointDescription, Tags, OperationID and MarkDeprecated on an operation, cover what it asked for.
The router is chi. chi was needed when the DSL was written. Since Go 1.22, http.ServeMux matches methods and {name} wildcards, and since Go 1.23 it sets Request.Pattern, which httpserver's instrumentation names spans after.
The example built its dependencies in main. main.go reads os.Getenv("DATABASE_URL"), opens a pgxpool on the real network and closes it with defer, around rest.Run. The charter lists exactly this as a question the process model raises.
What Proposal: HTTP server foundation #680 hands on. "REST produces an http.Handler, and its Service is this Service serving that handler. … So REST inherits TLS, HTTP/2, the instrumentation and the panic handling. Its services use httpserver.Main and httpservertest, unless REST's proposal gives it a Main of its own." And: "A protocol that defines an error response, such as REST, recovers in its own handler and writes that response itself."

Proposed API

package rest // github.com/z5labs/humus/rest

// API describes the API as a whole, for its OpenAPI document.
type API struct {
	// Title is the document's info.title. Required.
	Title string

	// Version is the document's info.version: the version of the API, not
	// of humus or of OpenAPI. Required.
	Version string

	// Description is the document's info.description. Optional.
	Description string

	// OpenAPIPath is the path the handler serves the OpenAPI document at,
	// with GET, such as "/openapi.json". "" serves no document.
	OpenAPIPath string
}

// NewHandler returns an http.Handler that serves routes on an
// http.ServeMux, and the OpenAPI document of api and routes at
// api.OpenAPIPath. It builds and encodes the document once.
//
// It returns an error naming every mistake it finds in api and routes:
// a missing Title or Version, a path OpenAPI and ServeMux would read
// differently, a path parameter that the path and the endpoint disagree
// on, a type that doesn't match the handler's, an option that doesn't
// fit its parameter, and two responses for one status. Two routes whose
// patterns conflict make ServeMux panic, naming both.
//
// It logs through s.Telemetry's LoggerProvider, with the logger name
// "github.com/z5labs/humus/rest".
func NewHandler(s *humus.Setup, api API, routes ...Route) (http.Handler, error)

// Endpoint is an operation that isn't complete: CatchAll completes it.
type Endpoint struct{ /* unexported */ }

// Route is a complete operation: every error its handler returns has an
// answer. Only a Route can be served.
type Route struct{ /* unexported */ }

// The operations. path is an OpenAPI path, such as "/carts/{cartId}".
func GET[Resp any](path string, h func(context.Context, Request[EmptyBody]) (Resp, error)) Endpoint
func DELETE[Resp any](path string, h func(context.Context, Request[EmptyBody]) (Resp, error)) Endpoint
func POST[B, Resp any](path string, h func(context.Context, Request[B]) (Resp, error)) Endpoint
func PUT[B, Resp any](path string, h func(context.Context, Request[B]) (Resp, error)) Endpoint
func PATCH[B, Resp any](path string, h func(context.Context, Request[B]) (Resp, error)) Endpoint

// The operation's metadata in the document.
func Summary(s string, ep Endpoint) Endpoint
func EndpointDescription(s string, ep Endpoint) Endpoint
func Tags(tags []string, ep Endpoint) Endpoint
func OperationID(id string, ep Endpoint) Endpoint
func MarkDeprecated(ep Endpoint) Endpoint

// EmptyBody is the body of a request that has none, and the response of a
// handler whose endpoint writes none.
type EmptyBody struct{}

// Request is everything the handler reads: its parameters and its body.
type Request[B any] struct{ /* unexported */ }

// Body returns the decoded body.
func (r Request[B]) Body() B

// ParamFrom returns p's value in req. It panics if req's endpoint didn't
// read p, naming p.
func ParamFrom[T ParamValue, B any](req Request[B], p Param[T]) T

// ParamValue is the type of a parameter's value.
type ParamValue interface {
	~string | ~bool | ~int | ~int64 | ~float64
}

// Param is a declared parameter. Read adds it to an endpoint, which then
// decodes and validates it, and documents it.
type Param[T ParamValue] struct{ /* unexported */ }

func PathParam[T ParamValue](name string, opts ...ParamOption) Param[T]
func QueryParam[T ParamValue](name string, opts ...ParamOption) Param[T]
func HeaderParam[T ParamValue](name string, opts ...ParamOption) Param[T]
func (p Param[T]) Read(ep Endpoint) Endpoint

type ParamOption func(*paramOptions)

func Required() ParamOption
func Optional() ParamOption
func ParamDescription(desc string) ParamOption
func ParamExample[T ParamValue](v T) ParamOption
func Pattern(re *regexp.Regexp) ParamOption
func Minimum(n float64) ParamOption
func Maximum(n float64) ParamOption
func MinLength(n int) ParamOption
func MaxLength(n int) ParamOption
func Enum[T ParamValue](values ...T) ParamOption
func DefaultValue[T ParamValue](v T) ParamOption

// ReadJSON decodes the request body as JSON into the handler's B, which
// must be T. ReadBinary hands the handler the body as it is: B must be
// io.Reader.
func ReadJSON[T any](ep Endpoint) Endpoint
func ReadBinary(contentType string, ep Endpoint) Endpoint

// WriteJSON answers with status and the handler's response, which must be
// Resp, as JSON. WriteBinary copies the handler's io.Reader. WriteEmpty
// answers with status and no body: the handler's response must be EmptyBody.
func WriteJSON[Resp any](status int, ep Endpoint) Endpoint
func WriteBinary(status int, contentType string, ep Endpoint) Endpoint
func WriteEmpty(status int, ep Endpoint) Endpoint

// ErrorJSON answers an error that matches E, with errors.As, with status
// and E as JSON.
func ErrorJSON[E error](status int, ep Endpoint) Endpoint

// CatchAll completes ep: an error no ErrorJSON matched is answered with
// status, and E as JSON: the error itself when it matches E, and wrap(err)
// otherwise.
func CatchAll[E error](status int, wrap func(error) E, ep Endpoint) Route

// Problem is a problem detail, RFC 9457. Every error response REST writes
// itself is a Problem, as application/problem+json. A type that is Problem,
// or embeds it, is written as application/problem+json by ErrorJSON and
// CatchAll too, and as application/json otherwise.
type Problem struct {
	Type     string `json:"type,omitempty"`
	Title    string `json:"title,omitempty"`
	Status   int    `json:"status,omitempty"`
	Detail   string `json:"detail,omitempty"`
	Instance string `json:"instance,omitempty"`
}

// Error returns Detail, or Title when Detail is empty.
func (p Problem) Error() string

The package is in the core module, as the charter places it. Its one new dependency is swaggest/openapi-go (see The document below). chi is not a dependency.

In the end user's `Init`

The shoppingcart's Init, in full apart from its settings:

func Init(ctx context.Context, s *humus.Setup) ([]humus.Service, error) {
	settings, err := readSettings(ctx, s) // httpserver.Settings and the database URL, sourced with config.Struct
	if err != nil {
		return nil, err
	}
	pool, err := openPool(ctx, s, settings.DatabaseURL) // dials through s.Host; s.OnStop closes it
	if err != nil {
		return nil, err
	}
	api, err := rest.NewHandler(s, rest.API{
		Title:       "Shopping Cart API",
		Version:     "1.0.0",
		Description: "REST API for managing shopping carts on an e-commerce platform.",
		OpenAPIPath: "/openapi.json",
	}, endpoint.Routes(database.New(pool))...)
	if err != nil {
		return nil, err
	}
	svc, err := httpserver.NewService(s, settings.HTTP, api)
	if err != nil {
		return nil, err
	}
	return []humus.Service{svc}, nil
}

And one of its operations, which changes from before the reset only in its imports and its not-found type:

var cartID = rest.PathParam[string]("cartId", rest.ParamDescription("Shopping cart identifier (UUID)"))

func AddCartItem(store database.Store) rest.Route {
	ep := rest.POST("/carts/{cartId}/items", func(ctx context.Context, req rest.Request[AddItemRequest]) (database.CartItem, error) {
		id, err := uuid.Parse(rest.ParamFrom(req, cartID))
		if err != nil {
			return database.CartItem{}, notFound("cart not found")
		}
		item, err := store.AddCartItem(ctx, id, req.Body().toDatabase())
		if errors.Is(err, database.ErrCartNotFound) {
			return database.CartItem{}, notFound("cart not found")
		}
		return item, err
	})
	ep = cartID.Read(ep)
	ep = rest.ReadJSON[AddItemRequest](ep)
	ep = rest.OperationID("addCartItem", ep)
	ep = rest.Summary("Add an item to a shopping cart", ep)
	ep = rest.WriteJSON[database.CartItem](http.StatusCreated, ep)
	ep = rest.ErrorJSON[NotFound](http.StatusNotFound, ep)
	return rest.CatchAll(http.StatusInternalServerError, internalError, ep)
}

// NotFound is a problem detail, so it is written as application/problem+json.
type NotFound struct{ rest.Problem }

rest has no Settings. What an operator changes is the server's, in httpserver.Settings, and the document's title and version are the end user's code.

Routing

NewHandler registers each route on a new http.ServeMux, as METHOD path, and returns the mux.

Paths are OpenAPI paths that ServeMux reads the same way. A path starts with /, and its parameters are {name}, where the name is a Go identifier, as ServeMux requires. NewHandler rejects {name...} and {$}, which OpenAPI has no form for, and a host. A path that ends in / is registered with {$} after it, so /carts/ matches /carts/ and not every path below it, as OpenAPI means.
The path and the endpoint agree. Every {name} in the path has a PathParam the endpoint reads, and every PathParam it reads is in the path. Before, a parameter missing from either was missing from the document, or read as "".
Conflicts panic, as ServeMux does. GET /carts/{id} next to GET /carts/{cartId} matches the same requests, and ServeMux.Handle panics with a message naming both. That is a programming error, reported by the first test or start, as grpcserver panics on a service registered twice. OpenAPI forbids the same pair too.
Unmatched requests get ServeMux's answers: 404 for an unknown path, and 405 with an Allow header for a known path and an unknown method. They are plain text and not in the document.
Spans are named after the route. ServeMux sets Request.Pattern on the request it is given, and httpserver's otelhttp names the server span from it once the handler returns: POST /carts/{cartId}/items. Before the reset, every span was named rest.
Composing. The handler is a plain http.Handler. An end user who serves something REST doesn't describe mounts it next to REST's handler on a mux of their own, with mux.Handle("/", api). Those routes aren't in the document.

Requests

Parameters. A Param[T] is declared once, usually as a package-level value, and read by each endpoint that takes it. T is a string, bool, int, int64 or float64 type, named types such as type Sort string included, so an unsupported type is a compile error. When a request arrives, each parameter the endpoint reads is decoded and validated before the handler runs:

path parameters come from r.PathValue, and are always required;
query parameters are optional by default. One that appears more than once is a 400, since a parameter's value is one value;
header parameters are optional by default.

An optional parameter that is absent gets its DefaultValue, or T's zero value. A value that doesn't parse as T, or breaks one of its constraints, is answered with a 400 Problem whose detail names the parameter, and the handler isn't called.

NewHandler checks each parameter's options against its type: Pattern, MinLength and MaxLength need a string type, Minimum and Maximum a number type, Enum, DefaultValue and ParamExample values of the parameter's own type, and Optional isn't allowed on a path parameter. Pattern takes a compiled *regexp.Regexp, so a bad expression is the end user's regexp.MustCompile panicking, not every request failing.

ParamFrom panics for a parameter the endpoint didn't read. The handler's Request holds a value for every parameter its endpoint reads, present or not, so a missing one is a mistake in the endpoint's declaration. Returning the zero value, as before, turned the mistake into a wrong answer.

JSON bodies. ReadJSON[T] decodes the body into T, before the handler runs:

a Content-Type other than application/json or a +json type is a 415 Problem;
an empty body, malformed JSON, a value of the wrong type, and anything after the first JSON value are a 400 Problem with the decoder's message;
unknown fields are ignored, as encoding/json does, so a client that sends a newer field doesn't break;
REST sets no size limit. An end user who wants one wraps the handler with the standard library's http.MaxBytesHandler, and a body over the limit is a 413 Problem.

REST doesn't validate a body against its schema: the schema documents the body, and the handler checks what it needs.

Binary bodies. ReadBinary hands the handler the request body as an io.Reader, unread, and documents it as contentType.

Responses

WriteJSON encodes before it writes. The response is marshalled into a buffer, and the status and body are written only once that succeeds. A value encoding/json can't encode is an error, answered by the catch-all, rather than a 200 with a broken body.
WriteBinary writes the status and contentType, copies the handler's io.Reader, and closes it if it is an io.Closer.
WriteEmpty writes the status and no body, for a 204. Before, the example wrote a 204 with WriteBinary, an empty Content-Type and an empty reader, and the document described a binary body.
A failed write is the client's. Once the status is written, an error writing the body, which is almost always the client going away, can't change the response. It is recorded on the request's span and not logged.
The types must match. NewHandler returns an error when WriteJSON[Resp]'s Resp isn't the handler's response type, WriteBinary's isn't an io.Reader, WriteEmpty's isn't EmptyBody, or ReadJSON[T]'s T isn't the handler's body type. An endpoint with no writer is an error too. Before, a mismatch documented one type and served another.

Errors

An endpoint answers its handler's error with the first ErrorJSON whose type matches, with errors.As, and otherwise with its catch-all. That is the old DSL's model, kept as it was, with three changes.

REST's own errors are problem details. Before the handler runs, REST answers with a Problem, as application/problem+json, with type about:blank and the status's name as title, as RFC 9457 says for about:blank:

Status	When	Documented on
400	a parameter or a JSON body fails to decode or validate	every operation that reads a parameter or a body
413	a body over `http.MaxBytesHandler`'s limit	every operation that reads a body
415	a JSON body with another `Content-Type`	every operation that reads a JSON body

The content type follows the error's type. ErrorJSON and CatchAll write a type that is Problem, or embeds it, as application/problem+json, and any other type as application/json. The end user's errors become problem details by embedding Problem, as NotFound does above.

One response per status. An operation has one response for each status in the document. NewHandler returns an error for an operation that names a status twice, with different types, or that names 400, 413 or 415, where REST answers with a Problem itself, with a type other than Problem. A handler that answers its own validation errors with 400 does so with ErrorJSON[rest.Problem](http.StatusBadRequest, ep), and the document has one 400 response.

The catch-all records what it answers. An error that only the catch-all answered is one the end user didn't plan for. REST records it on the request's span as an exception event, and emits one ERROR record, request failed, in the request's context, so the record carries the span's trace and span IDs, with http.request.method, http.route, error.type and exception.message. With the default telemetry, which exports no spans, that record is where the error is found. When the request's context is done because the client went away, the error is recorded on the span only.

wrap decides what the client sees, and should not put the error's text in the body: the record has it. The example's internalError returns a fixed Problem.

Panics

The charter leaves a panic inside one request to each protocol, and #680 leaves REST's to REST. A REST handler never writes to the http.ResponseWriter: it returns a value that REST encodes. So when it panics, nothing has been written, and REST can answer cleanly:

REST recovers a panic of the end user's handler function, and nothing else. The recovery is around the call to the handler, inside REST's per-route code. A panic in REST's own code, or in middleware the end user wraps around the handler, reaches httpserver, which records it and aborts the response.
The panic is recorded as httpserver records one: an exception event on the request's span with exception.type, exception.message and exception.stacktrace, the span's status set to Error, and one ERROR record, handler panicked, in the request's context, under the logger github.com/z5labs/humus/rest.
The route's catch-all answers it, with its status and wrap of an error that doesn't carry the panic's value. So the response is the one the document lists for the catch-all, and the panic's value never reaches the client.
A handler that panics with http.ErrAbortHandler is passed through untouched, so it can still abort its response on purpose.

This is open question 1. The cost is grpcserver's: whatever the handler left half-changed stays that way, for the requests that follow.

The document

NewHandler builds the document with swaggest/openapi-go's openapi3 reflector, which generates the JSON Schema of each Go type from its fields and json tags. Each operation lists its parameters with their constraints, its request body, required, its success response, its ErrorJSON responses, REST's own problem responses from the table above, and its catch-all. The document is encoded to JSON once, so every request for it gets the same bytes, and a golden test can compare them.

OpenAPI 3.0.3, as before the reset. 3.1.0 is open question 2: swaggest's openapi31 reflector takes the same operation contexts, so the choice changes one reflector.
Served at API.OpenAPIPath, with GET, as application/json. The end user names the path, so no path is imposed. An empty path serves no document, for an API that keeps its document private.
The document doesn't describe itself, the 404 and 405 answers, or anything mounted next to REST's handler.

swaggest/openapi-go is the one new dependency, with its own swaggest/jsonschema-go and swaggest/refl. It was used for the same purpose by humus v0.15.0's rest and by bedrock's DSL. Writing JSON Schema from Go types by hand is most of what a reflector does, and keeping it in step with OpenAPI is not humus's business. Its modern API, NewOperationContext and AddRespStructure with a content type and a status, replaces the deprecated SetJSONResponse the old DSL used, and is what writes application/problem+json responses. chi was the old DSL's other dependency, and ServeMux replaces it.

Telemetry

REST takes everything from s.Telemetry and never touches OTel's globals. It adds no spans or metrics: httpserver's otelhttp gives every request a server span named after its route, and the HTTP server metrics with the response's status. REST's records go through s.Telemetry.LoggerProvider.Logger("github.com/z5labs/humus/rest"):

Record	Severity	When
`request failed`	ERROR	the catch-all answered an error, and the client is still there
`handler panicked`	ERROR	the end user's handler panicked

A 400, 413 or 415 is the client's mistake: it is answered and not logged, and otelhttp records its status. An error answered by an ErrorJSON is an answer the API documents, and is not logged either.

What waves 5 and 6 build on this

Proposal: authentication and authorization (wave 5) adds security requirements to REST's operations and security schemes to its document. An operation's options compose as Summary and Tags do, so it adds its own, and its stories add whatever it needs here. REST answers no 401 or 403 of its own until then.
Proposal: failure injection (wave 5) strips scenarios in httpserver's handler chain, after otelhttp's extraction and before REST's handler, so REST needs nothing for it.
Proposal: walkthroughs and a humus MIGRATING.md (wave 6) builds on the shoppingcart, and maps v0.15.0's rest.NewApi API to this one.
Proposal: AI tooling (wave 6) generates code against this DSL.

Design decisions

The package is rest, in the core module. The charter puts REST in the core, and its one dependency is a schema reflector. It doesn't import httpserver: its handler is an http.Handler, and the end user's Init hands it to httpserver.NewService.
No Main, no Service and no test package. A REST service is an HTTP service: its drain, grace period and certificate are httpserver's, and a test of it is httpservertest.Start and httpservertest.NewClient. A rest.Main would be httpserver.Main under another name.
NewHandler takes the Setup, as every humus constructor does, for its logger. The handler is still built and served in Init, from what Init builds.
The DSL keeps its shape and its names. It is the most recent design, it has a user, the shoppingcart, and nothing in the process model asks for another one. The changes are the ones listed under Background.
ServeMux over chi. It does what REST needs, it names the spans, and it is one dependency fewer.
Mistakes in declarations are errors from NewHandler, or a compile error, never a 400 on every request. ServeMux's own conflict panic stays a panic, as grpcserver's registration mistakes do.
REST's own error responses are problem details and are documented. The client of a REST API sees one error format, and the document lists every status an operation answers with.
Problem is exported. It is the type of the responses REST writes itself, so it is in REST's API and its document either way, and the end user embeds it rather than copying it, as the old example did.
No ProblemDetailsErrorHandler, no error handler interface. v0.15.0's per-operation error handlers and HttpResponseWriter errors are replaced by ErrorJSON and CatchAll, which the document is generated from.
A panic is answered by the catch-all. See Panics above, and open question 1.
Unknown JSON fields are ignored, and bodies aren't validated against their schema. Rejecting unknown fields breaks a client that is ahead of the server, and schema validation is a second implementation of the end user's checks.
No body size limit of REST's own. http.MaxBytesHandler already is one, and REST answers its error with 413.
No response headers, cookies or HTML. The old DSL had none, and the example needs none. See Out of scope.
Form bodies are dropped. ReadFormFile wrote large uploads to the real temp directory, and nothing that uses the DSL needs it.

Testing

These tests are sketches and have not been run. Every test runs inside a testing/synctest bubble on a humustest Host, with a certificate from humustest.NewCA, and asserts with testify/require, except the example's container tests below.

A whole service, through httpservertest, with its telemetry recorded:

func TestNewHandler_serves_a_route_and_records_its_span(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		ca := humustest.NewCA(t)
		cert := ca.Issue(t, "localhost")
		h := humustest.NewHost(t)
		tel := humustest.NewTelemetry()

		cartID := rest.PathParam[string]("cartId")
		ep := rest.GET("/carts/{cartId}", func(_ context.Context, req rest.Request[rest.EmptyBody]) (cart, error) {
			id := rest.ParamFrom(req, cartID)
			if id == "missing" {
				return cart{}, notFound{rest.Problem{Title: "Not Found", Status: http.StatusNotFound, Detail: "no cart " + id}}
			}
			return cart{ID: id}, nil
		})
		ep = cartID.Read(ep)
		ep = rest.WriteJSON[cart](http.StatusOK, ep)
		ep = rest.ErrorJSON[notFound](http.StatusNotFound, ep)
		route := rest.CatchAll(http.StatusInternalServerError, internalError, ep)

		p, status := httpservertest.Start(t, func(ctx context.Context, s *humus.Setup) ([]humus.Service, error) {
			api, err := rest.NewHandler(s, rest.API{Title: "Carts", Version: "1.0.0", OpenAPIPath: "/openapi.json"}, route)
			if err != nil {
				return nil, err
			}
			settings := httpserver.DefaultSettings()
			settings.Addr = ":8443"
			settings.TLS = &tls.Config{Certificates: []tls.Certificate{cert.TLS()}}
			svc, err := httpserver.NewService(s, settings, api)
			if err != nil {
				return nil, err
			}
			return []humus.Service{svc}, nil
		}, humustest.WithApp(humus.WithHost(h.Host()), humus.WithTelemetry(tel.Builder())))
		<-h.Listening("localhost:8443")
		client := httpservertest.NewClient(h, ca.Pool())

		resp, err := client.Get("https://localhost:8443/carts/c-1")
		require.NoError(t, err)
		requireJSON(t, resp, http.StatusOK, "application/json", `{"id":"c-1"}`)

		resp, err = client.Get("https://localhost:8443/carts/missing")
		require.NoError(t, err)
		requireJSON(t, resp, http.StatusNotFound, "application/problem+json",
			`{"title":"Not Found","status":404,"detail":"no cart missing"}`)

		p.Signal(syscall.SIGTERM)
		require.Zero(t, (<-status).Code())
		require.Equal(t, []string{"GET /carts/{cartId}", "GET /carts/{cartId}"}, spanNames(tel))
	})
}

requireJSON, spanNames, cart, notFound and internalError are the test file's own helpers and types.

The tests also show the following:

NewHandler's errors. One table case for each mistake it reports: a missing title or version, a path with {name...}, {$} or a host, a {name} with no PathParam and a PathParam not in the path, each type mismatch, each option on the wrong type, Optional on a path parameter, an endpoint with no writer, two types at one status, a non-Problem type at 400. Two bad routes are reported in one error.
A conflict panics with ServeMux's message, naming both patterns.
ParamFrom panics for a parameter the endpoint didn't read, naming it.
Parameters. Each type decodes; a missing required parameter, a value that doesn't parse and each broken constraint are a 400 Problem naming the parameter, with the handler not called; an absent optional parameter is its default; a repeated query parameter is a 400.
JSON bodies. A 415 for text/plain, a 400 for an empty body, malformed JSON, a wrong type and trailing data, a 413 behind http.MaxBytesHandler, and an unknown field ignored.
Responses. A value with a channel in it is answered by the catch-all and logged; WriteEmpty writes a 204 with no body and no Content-Type; WriteBinary closes the handler's reader.
The catch-all. An unplanned error is answered with wrap's value and produces one request failed record carrying the request span's trace_id and span_id, with http.route and exception.message; an ErrorJSON error and a 400 produce no record; an error returned after the client went away is on the span and not logged.
Panics. The client gets the catch-all's status and body, without the panic's value; the span has an exception event with the stack and status Error; one handler panicked record carries its IDs; nothing is written to p.Stderr(); the next request succeeds. A handler panicking with http.ErrAbortHandler has its response aborted, as httpserver does.
The document. It is served at OpenAPIPath with application/json, isn't served with an empty path, is the same bytes on every request, and lists REST's 400, 413 and 415 problem responses on the operations that read a parameter or a body.
No globals. With OTel's global providers set to recorders of their own, a request records nothing in them.

The package is held to the 80% coverage gate, and its example is an Example function. humustest.TestService isn't run: REST adds no Service.

The shoppingcart

The example is the reference service, in the example nested module, github.com/z5labs/humus/example, as the charter's module layout has it, so pgx, uuid and testcontainers stay out of the core module's graph. Its go.mod replaces github.com/z5labs/humus with ../, as grpc's does. CI already lists every module with go-modules.sh, and already exempts the packages under example/ from the coverage gate.

main.go is httpserver.Main(app.Init, humus.WithTelemetry(app.BuildTelemetry)). Nothing in it reads the environment.
Init sources httpserver.Settings, with the certificate as a PKCS#12 bundle read through s.Host.FS, and DATABASE_URL, from s.Process.Environment, with config.Struct, so a missing variable exits 78. It builds the pool with pgxpool.NewWithConfig, with DialFunc set to s.Host.Dial, and LookupFunc returning the host unresolved so that the Host's dial resolves it. It registers pool.Close with s.OnStop, and builds the handler from the six routes of before: create, get and delete a cart, and add, update and remove an item.
pgx's ambient leaks are documented, not hidden. pgconn.ParseConfig reads the real environment's PG* variables, and the real ~/.pgpass, for whatever the URL leaves out, and pgx has no way to build a config without it. The example's URL sets every field it uses, and the docs page lists the leak, as the lifecycle page's ambient leaks do for others.
app_test.go runs the whole service with httpservertest.Start, on an in-memory Store that an unexported seam of Init swaps in, since Postgres can't run on humustest's Host. It sends the requests of each endpoint through httpservertest.NewClient, and compares the served document with a golden file, testdata/openapi.json.
Container tests, behind the testcontainers build tag as queue/kafka's are, run the Postgres Store against postgres in a container, and the whole service once on humus.OSHost(), with the schema applied from schema.sql. They run in a CI job of their own, which is not a required check, and the Build job's vet step vets them, as it does Kafka's.

This is open question 3.

Migration from today

Before the reset	With this proposal
`rest.Run(ctx, rest.Title(…), rest.Version(…), rest.Handle(route))`	`httpserver.Main(Init)`, with `Init` calling `rest.NewHandler(s, rest.API{…}, routes...)` and `httpserver.NewService`
`bedrockrest.Build(opts...)`, a `bedrock.Builder[http.Handler]`	`rest.NewHandler(s, api, routes...)`, an `http.Handler` and an error
`Title`, `Version`, `APIDescription`, `SpecPath`; defaults `"API"`, `"0.0.0"`, `/openapi.json`	`rest.API`'s fields; `Title` and `Version` required; no path unless `OpenAPIPath` names one
`route.Route()`	the route, passed to `NewHandler`
`GET` … `DELETE`, `Request`, `EmptyBody`, `Summary`, `Tags`, `OperationID`, …	the same names, in `rest`
`ParamFrom` returns the zero value for a parameter the endpoint didn't read	it panics, naming the parameter
`PathParam[T any]`, an unsupported `T` failing every request with 400	`PathParam[T ParamValue]`, a compile error
`Pattern(string)`, a bad expression failing every request	`Pattern(*regexp.Regexp)`
chi, `chi.URLParam`	`http.ServeMux`, `r.PathValue`; spans named after the route
`ReadJSON[T]`	the same, plus 415, 413 and trailing data
`ReadFormFile`, `ReadFormField`	dropped
`WriteJSON`, `WriteBinary`, written with the encoder's error ignored	the same, encoded before the status is written
a 204 with `WriteBinary(204, "", …)` and an empty reader	`WriteEmpty(http.StatusNoContent, …)`
`ErrorJSON[E]`, `CatchAll[E]`, as `application/json`	the same, as `application/problem+json` when `E` embeds `rest.Problem`
a bad parameter or body: `{"param", "error"}` and a 400 outside the document	a `rest.Problem` and a documented 400, 413 or 415
an error the catch-all answered: lost	an ERROR record and a span event
a panic: bedrock's `RecoverPanics` around the runtime	the route's catch-all, recorded
`otelhttp.NewHandler(h, "rest")` on the globals, spans named `rest`	`httpserver`'s instrumentation
`example/rest/shoppingcart` in the root module; `os.Getenv("DATABASE_URL")` and `pgxpool.New` in `main`	the `example` module; `Init` sources the URL, the pool dials through the `Host`, and `OnStop` closes it
the example's `specs/` (a hand-written `api.yaml`, sequence diagrams)	dropped; the served document is the golden file

The changes outside rest are this proposal's stories:

the example module and the shoppingcart, the container tests' CI job, and the vet step;
a docs page, "REST APIs", whose Go samples are taken from tests, as TestDocs_code_samples requires;
the Migration from rest.Run section of the "Serving HTTP" page, which now points at REST's page;
the "Being rebuilt" sections of doc.go, the README and the docs site's index.

Open questions

Panics. Answer a panic of the end user's handler with the route's catch-all, as proposed, or don't recover, so that httpserver records it and aborts the response, as for any http.Handler? Aborting matches Proposal: HTTP server foundation #680's decision for plain HTTP, but a REST client then sees a reset stream where the document promises a status, and nothing has been written yet that answering would contradict. Recommendation: the catch-all, as grpcserver answers a panic with Internal.
OpenAPI 3.0.3 or 3.1.0? 3.0.3 is what the document was before the reset, and what every client generator reads. 3.1.0 is the current version, whose schemas are JSON Schema, such as type: [string, "null"] for a pointer. swaggest generates either. Recommendation: 3.0.3.
The example's database. Keep Postgres, through pgx, with an in-memory Store for app_test.go and container tests in a CI job of their own, as proposed? Or an in-memory store only, which runs anywhere but shows no dependency built in Init? Recommendation: Postgres. The reference service is where the end user sees a real dependency built in Init, dialled through the Host and released with OnStop.

Out of scope

Serving health probes for a REST service: Proposal: exposing health probes (wave 4). REST serves no probes, and its handler is an http.Handler that composes with whatever that proposal provides.
Authentication, authorization, and OpenAPI security schemes: Proposal: authentication and authorization (wave 5).
Failure injection: Proposal: failure injection (wave 5), in httpserver's chain.
Walkthroughs, and mapping v0.15.0's rest.NewApi API: Proposal: walkthroughs and a humus MIGRATING.md (wave 6). Generating REST code: Proposal: AI tooling (wave 6).
Response headers, cookies, content negotiation, HTML and template responses (story(rest): Implement HTML template response helpers #395), and interceptors (story(rest): add parameter option for user provided request interceptors #276). A route that needs them is a plain http.Handler mounted next to REST's handler, outside the document.
Form and multipart bodies.
Array and repeated query parameters, and parameters of other types.
Validating request bodies against their schema.
Problem detail bodies for ServeMux's 404 and 405.
Serving the document as YAML, or a documentation UI.
Generating Go code from an OpenAPI document.

References

Proposal: humus on the bedrock process model, the charter, and its wave plan
Proposal: HTTP server foundation and its revisions: the Service REST is served by, httpserver.Main, httpservertest, and "What waves 4 and 5 build on this"
httpserver's package doc and panic layer
Proposal: gRPC services, for recovering a panic per protocol
bedrock v0.21.0's runtime/http/rest, the DSL
Before the reset: rest/rest.go, example/rest/shoppingcart; story(rest): own the OpenAPI endpoint DSL inside humus #620, story(rest): add options for setting additional openapi values #283, story(rest): Implement RFC 7807 Problem Details for error responses #385
RFC 9457, Problem Details for HTTP APIs
net/http's ServeMux patterns, and http.MaxBytesHandler
swaggest/openapi-go v0.2.61
OpenAPI 3.0.3 and 3.1.0

Zaba505 · 2026-10-18T03:37:11Z

Zaba505
Oct 18, 2026
Maintainer Author

Revision 1: `openapi`, `NewAPI`, typed paths, one call per operation, and chi

This revision answers the review of the post:

The package is openapi, github.com/z5labs/humus/openapi. It follows OpenAPI: operations, parameters, responses and a document. It does none of what REST's constraints ask for, such as hypermedia, so rest named the wrong thing. The discussion's title becomes Proposal: OpenAPI endpoint DSL. Throughout the post, rest. reads openapi., and "REST's own errors" reads "the package's own errors".
NewAPI returns an *API, which implements http.Handler. NewHandler gave "handler" a second meaning, next to the operations' handlers, and an API is what developers call the routes and their metadata together. The post's API struct is now Info, OpenAPI's own name for the title, version and description.
Paths are built from typed Go values, not parsed from templates. openapi.Root().Lit("carts").Param(cartID) is /carts/{cartId}. There is no template language, so there is nothing to parse or to reject, and a path declares its own path parameters.
An operation is one call with its parts: openapi.Post(path, handler, parts...). The handler's types fix the request body and the response, so no reader or writer is declared, and the catch-all is given once, to NewAPI.
The router is chi, not ServeMux. The API answers a path it doesn't serve, and a method it doesn't serve, with problem details too.

The composition was chosen from three prototypes, each of which compiles and serves the shoppingcart's operations: this one, a chain of generic methods on a typed endpoint, and a struct literal per operation. Design decisions says why. A fourth prototype compared three shapes of typed path. The compile errors this revision claims were checked with the compiler.

Open questions 1–3 are still open, and this revision adds a fourth.

Each section below replaces the part of the same name in the post. Panics, The shoppingcart and the rest of Background are unchanged, apart from the renames.

Summary

A new package, openapi, in the core module, serves an API of typed operations and the API's OpenAPI document. It is the DSL that bedrock v0.21.0 shipped as runtime/http/rest. It is kept where it works, and changed where it breaks the process model or humus's principles, or reads inside out:

NewAPI returns an *API, an http.Handler, and httpserver's Service serves it. The end user's Init calls openapi.NewAPI, hands the API to httpserver.NewService, and main is httpserver.Main. The package adds no Service, no Main and no test package.
An operation is one call. Get, Post, Put, Patch and Delete take a typed path, a typed handler, and the operation's parts:
- its metadata;
- its query and header parameters;
- its success status;
- the errors it answers.
The handler's types decide how the body is read and how the response is written.
Paths are typed values. A path is built segment by segment, from literals and path parameters, so there is no template to parse. A prefix such as /carts/{cartId} is a value that several operations share.
Every error has an answer. NewAPI takes a catch-all, and leaving it out is a compile error. It also takes the errors that every operation answers, such as a not-found.
Routing is chi. The API answers a path or method it doesn't serve with a problem detail. httpserver's spans are named after the route, such as GET /carts/{cartId}.
Mistakes are compile errors, or fail when NewAPI runs, never as a 400 on every request. The one left for a request is ParamFrom of a parameter the operation doesn't read, which panics, as in the post:
- A response or body type that doesn't match the handler's can't be written: the handler's types are the only place they are declared.
- These don't compile: a query parameter used as a path parameter, a missing catch-all, and an enum value of the wrong type.
- NewAPI returns one error that names every other mistake it finds.
As in the post:
- The package's own error responses are problem details (RFC 9457), and they are in the document.
- A panic of the end user's handler is answered by the catch-all, and recorded.
- The document is generated with swaggest/openapi-go.
- The shoppingcart comes back in the example module.

func main() {
	httpserver.Main(app.Init, humus.WithTelemetry(app.BuildTelemetry))
}

Background

The bullet "The router is chi" is replaced:

The router is chi, and stays chi. Since Go 1.22, http.ServeMux matches methods and {name} wildcards. But it answers a path it doesn't serve, and a method it doesn't serve, by itself, with plain text that no handler can replace. An API whose other errors are all problem details would then answer in two formats. chi takes a handler for each of the two answers. chi v5.5.0 also sets Request.Pattern and the request's path values, as ServeMux does, though on a copy of the request (see Routing).

Proposed API

package openapi // github.com/z5labs/humus/openapi

// Info is the document's info object.
type Info struct {
	// Title is the document's info.title. Required.
	Title string

	// Version is the document's info.version: the version of the API, not
	// of humus or of OpenAPI. Required.
	Version string

	// Description is the document's info.description. Optional.
	Description string
}

// API serves its operations, routed with chi. It is an http.Handler.
type API struct{ /* unexported */ }

// NewAPI returns an API that serves ops. catchAll is the catch-all of every
// operation that doesn't give its own, so every error of every operation
// has an answer. opts are given to every operation, before the operation's
// own parts, which add to them or override them. NewAPI builds and encodes
// the document once.
//
// It returns an error naming every mistake it finds in info, catchAll, ops
// and opts: a missing Title or Version, a literal or parameter name a path
// can't have, a parameter given twice, a constraint that doesn't fit its
// parameter's type, two responses at one status, two operations at one
// method and path, two paths that differ only in their parameters' names,
// and the others under Routing, Requests, Responses and Errors.
//
// It logs through s.Telemetry's LoggerProvider, with the logger name
// "github.com/z5labs/humus/openapi".
func NewAPI(s *humus.Setup, info Info, catchAll Fallback, ops []Operation, opts ...APIOption) (*API, error)

func (a *API) ServeHTTP(w http.ResponseWriter, r *http.Request)

// Document returns the operation that serves the API's OpenAPI document at
// p, with GET, as application/json. The document doesn't describe it. An
// API whose operations include no Document serves no document.
func Document(p Path) Operation

// Path is a path of the API, built from the root one segment at a time.
// Each method returns a new Path, so a prefix can be shared.
type Path struct{ /* unexported */ }

// Root returns the root path, "/".
func Root() Path

// Lit returns p followed by the literal segment s, such as "carts".
func (p Path) Lit(s string) Path

// Param returns p followed by the path parameter pp, such as {cartId}.
func (p Path) Param[T ParamValue](pp PathParameter[T]) Path

// String returns p as an OpenAPI path, such as "/carts/{cartId}/items".
func (p Path) String() string

// Operation is one operation of an API: a method, a path, a typed handler
// and its parts. Only an API serves it.
type Operation struct{ /* unexported */ }

// The operations. The handler's types fix the request body and the
// response: EmptyBody is none, a Stream[M] is bytes of M's media type, and
// any other type is JSON.
func Get[Resp any](p Path, h func(context.Context, Request[EmptyBody]) (Resp, error), opts ...Option) Operation
func Delete[Resp any](p Path, h func(context.Context, Request[EmptyBody]) (Resp, error), opts ...Option) Operation
func Post[B, Resp any](p Path, h func(context.Context, Request[B]) (Resp, error), opts ...Option) Operation
func Put[B, Resp any](p Path, h func(context.Context, Request[B]) (Resp, error), opts ...Option) Operation
func Patch[B, Resp any](p Path, h func(context.Context, Request[B]) (Resp, error), opts ...Option) Operation

// Option is a part of one operation. An APIOption is a part that NewAPI
// takes too, for every operation. A Fallback is a catch-all.
type Option interface{ /* unexported */ }
type APIOption interface{ Option /* and unexported */ }
type Fallback interface{ Option /* and unexported */ }

// The operation's metadata in the document.
func Summary(s string) Option
func Description(s string) Option
func OperationID(id string) Option
func Tags(tags ...string) Option
func Deprecated() Option

// Status is the status of the operation's success response. Without it,
// the status is 204 for an EmptyBody response and 200 otherwise.
func Status(code int) Option

// Query and Header add a parameter that the operation reads. An
// operation's path parameters are its path's.
func Query[T ParamValue](p QueryParameter[T]) Option
func Header[T ParamValue](p HeaderParameter[T]) Option

// Error answers an error that matches E, with errors.As, with status and E
// as JSON. Given to NewAPI, it answers on every operation, and every
// operation documents it. An operation's own Error for E overrides it.
func Error[E error](status int) APIOption

// CatchAll answers an error that no Error matched, and a panic of the
// handler, with status and E as JSON: the error itself when it matches E,
// and wrap(err) otherwise. NewAPI requires one. An operation's own
// CatchAll overrides it.
func CatchAll[E error](status int, wrap func(error) E) Fallback

// Request is everything the handler reads: its parameters and its body.
type Request[B any] struct{ /* unexported */ }

// Body returns the decoded body.
func (r Request[B]) Body() B

// EmptyBody is the body of a request that has none, and the response of a
// handler that writes none.
type EmptyBody struct{}

// MediaType names the media type of a Stream, such as text/csv.
type MediaType interface{ MediaType() string }

// Stream is a body of bytes of M's media type. As a request body, the
// handler reads it as it arrived. As a response, the API copies it to the
// client, and closes it if it is an io.Closer.
type Stream[M MediaType] struct{ io.Reader }

// ParamValue is the type of a parameter's value.
type ParamValue interface {
	~string | ~bool | ~int | ~int64 | ~float64
}

// Param is a path, query or header parameter, as ParamFrom takes it.
type Param[T ParamValue] interface{ /* unexported */ }

// ParamFrom returns p's value in req. It panics if req's operation doesn't
// read p, naming p and the operation.
func ParamFrom[T ParamValue, B any](req Request[B], p Param[T]) T

// A parameter of each kind. A path parameter is always required. A query
// or header parameter is optional unless it is Required.
type PathParameter[T ParamValue] struct{ /* unexported */ }
type QueryParameter[T ParamValue] struct{ /* unexported */ }
type HeaderParameter[T ParamValue] struct{ /* unexported */ }

func PathParam[T ParamValue](name string) PathParameter[T]
func QueryParam[T ParamValue](name string) QueryParameter[T]
func HeaderParam[T ParamValue](name string) HeaderParameter[T]

// Each method returns a copy of the parameter with one more part of its
// declaration. A PathParameter[T] has these:
func (p PathParameter[T]) Description(s string) PathParameter[T]
func (p PathParameter[T]) Example(v T) PathParameter[T]
func (p PathParameter[T]) Enum(values ...T) PathParameter[T]
func (p PathParameter[T]) Pattern(re *regexp.Regexp) PathParameter[T]
func (p PathParameter[T]) MinLength(n int) PathParameter[T]
func (p PathParameter[T]) MaxLength(n int) PathParameter[T]
func (p PathParameter[T]) Minimum(v T) PathParameter[T]
func (p PathParameter[T]) Maximum(v T) PathParameter[T]

// A QueryParameter[T] and a HeaderParameter[T] have the same eight, and
// these two:
func (p QueryParameter[T]) Required() QueryParameter[T]
func (p QueryParameter[T]) Default(v T) QueryParameter[T]

// Problem is a problem detail, RFC 9457. Every error response the package
// writes itself is a Problem, as application/problem+json. A type that is
// Problem, or embeds it, is written as application/problem+json by Error
// and CatchAll too, and as application/json otherwise.
type Problem struct {
	Type     string `json:"type,omitempty"`
	Title    string `json:"title,omitempty"`
	Status   int    `json:"status,omitempty"`
	Detail   string `json:"detail,omitempty"`
	Instance string `json:"instance,omitempty"`
}

// Error returns Detail, or Title when Detail is empty.
func (p Problem) Error() string

Path.Param is a generic method, which Go 1.27 allows. humus's go.mod already requires Go 1.27. The package is in the core module, and has two new dependencies:

swaggest/openapi-go (see The document);
chi v5, which has no dependencies of its own.

In the end user's `Init`

The shoppingcart's Init, in full apart from its settings:

func Init(ctx context.Context, s *humus.Setup) ([]humus.Service, error) {
	settings, err := readSettings(ctx, s) // httpserver.Settings and the database URL, sourced with config.Struct
	if err != nil {
		return nil, err
	}
	pool, err := openPool(ctx, s, settings.DatabaseURL) // dials through s.Host; s.OnStop closes it
	if err != nil {
		return nil, err
	}
	api, err := openapi.NewAPI(s,
		openapi.Info{
			Title:       "Shopping Cart API",
			Version:     "1.0.0",
			Description: "API for managing shopping carts on an e-commerce platform.",
		},
		openapi.CatchAll(http.StatusInternalServerError, endpoint.InternalError),
		endpoint.Carts{Store: database.New(pool)}.Operations(),
		// Every operation addresses a cart that may not exist.
		openapi.Error[endpoint.NotFound](http.StatusNotFound),
	)
	if err != nil {
		return nil, err
	}
	svc, err := httpserver.NewService(s, settings.HTTP, api)
	if err != nil {
		return nil, err
	}
	return []humus.Service{svc}, nil
}

Its operations read as a table of the API. Each handler is a method value:

var (
	cartID = openapi.PathParam[string]("cartId").Description("Shopping cart identifier (UUID)")
	itemID = openapi.PathParam[string]("itemId").Description("Cart item identifier (UUID)")

	carts = openapi.Root().Lit("carts") // /carts
	cart  = carts.Param(cartID)         // /carts/{cartId}
	items = cart.Lit("items")           // /carts/{cartId}/items
	item  = items.Param(itemID)         // /carts/{cartId}/items/{itemId}
)

// Carts serves the shoppingcart's operations from its Store.
type Carts struct{ Store database.Store }

func (c Carts) Operations() []openapi.Operation {
	return []openapi.Operation{
		openapi.Post(items, c.addCartItem,
			openapi.OperationID("addCartItem"),
			openapi.Summary("Add an item to a shopping cart"),
			openapi.Status(http.StatusCreated),
		),
		openapi.Delete(item, c.removeCartItem,
			openapi.OperationID("removeCartItem"),
			openapi.Summary("Remove an item from a shopping cart"),
		),
		// createCart, getCart, deleteCart and updateCartItem alike.
		openapi.Document(openapi.Root().Lit("openapi.json")),
	}
}

func (c Carts) addCartItem(ctx context.Context, req openapi.Request[AddItemRequest]) (database.CartItem, error) {
	id, err := uuid.Parse(openapi.ParamFrom(req, cartID))
	if err != nil {
		return database.CartItem{}, notFound("cart not found")
	}
	item, err := c.Store.AddCartItem(ctx, id, req.Body().toDatabase())
	if errors.Is(err, database.ErrCartNotFound) {
		return database.CartItem{}, notFound("cart not found")
	}
	return item, err
}

// NotFound is a problem detail, so it is written as application/problem+json.
type NotFound struct{ openapi.Problem }

Before the reset, AddCartItem was built with seven wrapping statements. Now it is one call. A handler's body changes in only three ways: its imports, its not-found type, and being a method.

The package has no Settings, as in the post.

Routing

NewAPI registers each operation on a new chi router, at its method and path, and the *API serves the router.

Paths are typed. A Path is a list of segments, and each is a literal or a path parameter. Both the OpenAPI path and chi's pattern are written from that list, such as /carts/{cartId}/items, and the end user writes neither.
- There is no way to write {name...}, {$}, a regular expression, a host or a trailing slash, so there is nothing to reject.
- A path parameter is a PathParameter[T], a type of its own. A query or header parameter in a path is a compile error.
NewAPI checks the segments. It returns an error rather than panicking. Paths are usually package-level variables, and a panic while a package initialises fails every test in it, before any output.
- A literal is made only of unreserved characters: letters, digits, -, ., _ and ~. It isn't empty, . or ... So it never needs escaping, in the document or on the wire.
- A parameter's name is an ASCII Go identifier, and appears once in its path.
A path declares its path parameters. An operation reads every parameter of its path. So the post's "the path and the endpoint agree" check is gone, along with the two mistakes it caught.
Conflicts are NewAPI errors. These are rejected:
- two operations at one method and path;
- two paths that differ only in their parameters' names, such as /carts/{id} and /carts/{cartId}, which OpenAPI forbids.
chi accepts both pairs. In the first, and in the second at one method, the later operation silently replaces the earlier one. At two methods, it serves both, with different path value names. chi tells other overlapping paths apart segment by segment, preferring a literal to a parameter, as OpenAPI matches concrete paths before templated ones.
What no operation serves is answered with a problem detail. Both answers are Problems, as application/problem+json, set as chi's NotFound and MethodNotAllowed handlers:
- a path no operation serves is a 404;
- a method its path doesn't serve is a 405, with an Allow header listing the methods it does serve. chi doesn't tell a handler of its own the allowed methods, so the API finds them with chi's Find.
Neither answer is in the document, and neither is logged. chi redirects nothing: /carts/ and //carts are 404s, where ServeMux answers //carts with a redirect.
Spans are named after the route. chi sets Request.Pattern, such as /carts/{cartId}. otelhttp names the span after it once the handler returns: GET /carts/{cartId}.
- chi sets it on its own copy of the request, which otelhttp never sees. So ServeHTTP hands chi a copy that already carries a chi routing context, which chi routes without copying again. It then sets the pattern chi found on the request it was given.
- Without that step, every span is named GET. That was checked with chi v5.5.0 under otelhttp v0.72.0.
- A 404 and a 405 have no route, so their spans are named after the method alone. The root path's span is GET /.
Path values are unescaped. When a request's path has an escaped form, chi matches that, so /carts/a%2Fb gives a%2Fb, where ServeMux gives a/b. The API unescapes each path value before it decodes it, so the handler gets a/b.
Composing, as in the post. The API is a plain http.Handler. An end user who serves something the API doesn't describe mounts it next to the API on a mux of their own, with mux.Handle("/", api), and those routes aren't in the document. chi isn't part of the package's API, and the end user never imports it.

Requests

Parameters. A parameter is declared once, usually as a package-level value, with its constructor and methods. Each method returns a copy with one more part:

var include = openapi.QueryParam[Include]("include").
	Description("What the cart includes").
	Enum(IncludeItems, IncludeCount).
	Default(IncludeItems)

A path parameter belongs to its path. A query or header parameter is read by each operation that gives it as a part, with openapi.Query(include) or openapi.Header(p). Decoding and validation are as in the post: a bad or missing value is a 400 Problem naming the parameter, and the handler isn't called.

What the types check. These are compile errors:

a value of another type in Enum, Default, Example, Minimum or Maximum, which take the parameter's own T;
Required or Default on a path parameter, which has neither method, since it is always present;
a path parameter given to Query, and a query parameter given to Path.Param.

NewAPI checks the rest:

Pattern, MinLength and MaxLength need a string type, and Minimum and Maximum a number type;
a Default or an Example must pass the parameter's own constraints;
an operation gives a parameter only once.

Pattern takes a compiled *regexp.Regexp, as in the post.

ParamFrom panics for a parameter the operation doesn't read, as in the post. Two such mistakes remain: a path parameter of another path, and a query parameter the operation doesn't give. The catch-all answers the panic, and it is recorded (see Panics). A path type that carries its parameters' types would make the first a compile error. Design decisions says why it wasn't chosen.

Bodies. The handler's body type decides how the body is read, with no reader to declare:

EmptyBody: nothing is read, and the operation documents no body. Get and Delete always have it.
Stream[M]: the body as an io.Reader, unread, documented as M's media type.
Any other type is JSON, read as the post's ReadJSON[T]:
- 415 for another Content-Type;
- 400 for an empty body, malformed JSON, a wrong type or trailing data;
- unknown fields are ignored;
- no size limit of the package's own: behind http.MaxBytesHandler, a body over the limit is a 413.

A body type that is an io.Reader but not a Stream is a NewAPI error, and the error names Stream. Go's constraints can't exclude such a type.

Responses

The handler's response type decides how the response is written. No writer is declared, so a writer that doesn't match the handler, and an operation without a writer, can't be written:

EmptyBody: the status and no body.
Stream[M]: the status, M's media type, and the handler's reader, copied and then closed if it is an io.Closer.
Any other type: JSON, encoded into a buffer before the status is written, as in the post.

Status sets the success status. Without it, the status is 204 for EmptyBody and 200 otherwise. Status(http.StatusNoContent) on a response with a body is a NewAPI error. A failed write is the client's, as in the post.

Errors

An operation answers its handler's error with the first Error whose type matches, with errors.As: its own Errors first, then the API's. Otherwise its catch-all answers: its own CatchAll, or NewAPI's. The post's model has three changes:

The catch-all is NewAPI's. NewAPI takes it as an argument, so leaving it out is a compile error, and nil is a NewAPI error. An Operation isn't an http.Handler, so only an API serves it, and every API has a catch-all. So every operation is complete by construction. An operation that answers with another catch-all gives CatchAll as a part.

Errors can be API-wide. An Error given to NewAPI answers on every operation, and every operation documents it, since every operation would answer with it. Listing it on only some operations would make the document wrong about the others.

An error that only some operations return isn't API-wide. It becomes a shared value, given to those operations: var cartNotFound = openapi.Error[NotFound](http.StatusNotFound). An operation's own Error for a type replaces the API's Error for it.

One response per status, as in the post. This now holds across all of an operation's answers together:

the API's Errors;
the operation's own Errors;
the catch-all;
the package's own 400, 413 and 415.

The package's own 404 and 405 (Routing) aren't any operation's responses.

The catch-all records what it answers, as in the post.

The document

The document is served by the operation Document(path) returns, at that path, with GET, as application/json. An API that doesn't include one serves no document, and a document path with a parameter is a NewAPI error. The rest is as in the post:

OpenAPI 3.0.3, which is open question 2;
swaggest's openapi3 reflector;
encoded once;
the document doesn't describe itself, nor anything mounted next to the API.

Telemetry

As in the post, under the logger name github.com/z5labs/humus/openapi. The package's 404 and 405 aren't logged: otelhttp records their status.

What waves 5 and 6 build on this

Proposal: authentication and authorization (wave 5) adds openapi.Security(…), an APIOption.
- Given to NewAPI, it is every operation's requirement. Given to an operation, it replaces the API's. This is how OpenAPI's top-level and per-operation security work too.
- NewAPI collects the schemes into the document's components.securitySchemes, so a requirement can't name a scheme the document lacks.
- The parts' interfaces have unexported methods, so that proposal's stories add the option to openapi itself. In the prototype it was one file.
Proposal: failure injection (wave 5) is as in the post.
Proposal: walkthroughs and a humus MIGRATING.md (wave 6) is as in the post.
Proposal: AI tooling (wave 6) is as in the post.

Design decisions

These bullets replace "The package is rest", "The DSL keeps its shape and its names", "ServeMux over chi" and "Mistakes in declarations are errors from NewHandler":

The package is openapi, in the core module. It follows OpenAPI, not REST.
NewAPI returns an *API. An API is the routes and their metadata together, and "handler" is kept for the end user's functions.
Paths are typed values, built from the root. Three shapes were prototyped:
- Variadic segments, openapi.Path(openapi.Lit("carts"), cartID). They need Lit on every literal, and read less like the URL.
- A path whose type carries its parameters' types, such as Path2[string, string]. Its operations are its methods, and the handler takes the parameters as arguments, so reading a parameter the path lacks doesn't compile. It was rejected for four reasons:
  - it caps a path at a fixed number of parameters;
  - it roughly quadruples the path API;
  - it decides how operations are composed;
  - two parameters of one type swapped in the handler still compile, and swap.
- The builder, which this revision chose. It reads left to right, as the URL does, and a prefix is a value.
One call per operation, with its parts. Two other compositions were prototyped:
- A chain of generic methods, openapi.Post(path, h).Summary(…).WriteJSON(201).Error[NotFound](404).CatchAll(…). Its type states make a missing writer and a missing catch-all compile errors. But:
  - its steps have a fixed order;
  - it has about forty methods;
  - its state types need phantom fields to stay distinct;
  - a later package such as auth adds itself through a different-looking .With(…).
- A struct literal per operation, openapi.Operation[B, Resp]{Method: …, Path: …, Handler: …}. It reads as a table. But it repeats the type arguments, makes a missing method, handler or catch-all a NewAPI error rather than a compile error, and gives zero values meanings to learn.
The constructor with parts is the shortest of the three. Its catch-all is a compile-time argument, and a later package adds a part as Error is added, at either level. Its cost: a part list holds parts of several kinds.
The handler's types fix the encodings. ReadJSON[T], WriteJSON[Resp], ReadBinary, WriteBinary and WriteEmpty are gone, and with them every mismatch between them and the handler. The cost is a default to learn: a response with a body is 200 unless Status says otherwise.
Path, query and header parameters are three types, so the compiler checks where a parameter goes. The constraints are methods that take T, so the compiler checks their values too.
The catch-all and the shared errors are given to NewAPI. Before the reset, every shoppingcart route repeated CatchAll(500, internalError) and ErrorJSON[NotFound](404).
chi over ServeMux. Every answer the API gives is then a problem detail, the not-found and the wrong method included, which ServeMux can't do. chi has no dependencies of its own, and it was the old DSL's router. The cost is in Routing: the pattern's copy-back, unescaping path values, and the conflict checks ServeMux would have made.
Declaration mistakes are compile errors, or one NewAPI error that names them all. They are never a panic during package initialization, and never a 400 on every request.

Testing

The sketch is replaced:

func TestNewAPI_serves_an_operation_and_records_its_span(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		ca := humustest.NewCA(t)
		cert := ca.Issue(t, "localhost")
		h := humustest.NewHost(t)
		tel := humustest.NewTelemetry()

		cartID := openapi.PathParam[string]("cartId")
		getCart := openapi.Get(openapi.Root().Lit("carts").Param(cartID), func(_ context.Context, req openapi.Request[openapi.EmptyBody]) (cart, error) {
			id := openapi.ParamFrom(req, cartID)
			if id == "missing" {
				return cart{}, notFound{openapi.Problem{Title: "Not Found", Status: http.StatusNotFound, Detail: "no cart " + id}}
			}
			return cart{ID: id}, nil
		})

		p, status := httpservertest.Start(t, func(ctx context.Context, s *humus.Setup) ([]humus.Service, error) {
			api, err := openapi.NewAPI(s,
				openapi.Info{Title: "Carts", Version: "1.0.0"},
				openapi.CatchAll(http.StatusInternalServerError, internalError),
				[]openapi.Operation{getCart},
				openapi.Error[notFound](http.StatusNotFound),
			)
			if err != nil {
				return nil, err
			}
			settings := httpserver.DefaultSettings()
			settings.Addr = ":8443"
			settings.TLS = &tls.Config{Certificates: []tls.Certificate{cert.TLS()}}
			svc, err := httpserver.NewService(s, settings, api)
			if err != nil {
				return nil, err
			}
			return []humus.Service{svc}, nil
		}, humustest.WithApp(humus.WithHost(h.Host()), humus.WithTelemetry(tel.Builder())))
		<-h.Listening("localhost:8443")
		client := httpservertest.NewClient(h, ca.Pool())

		resp, err := client.Get("https://localhost:8443/carts/c-1")
		require.NoError(t, err)
		requireJSON(t, resp, http.StatusOK, "application/json", `{"id":"c-1"}`)

		resp, err = client.Get("https://localhost:8443/carts/missing")
		require.NoError(t, err)
		requireJSON(t, resp, http.StatusNotFound, "application/problem+json",
			`{"title":"Not Found","status":404,"detail":"no cart missing"}`)

		resp, err = client.Post("https://localhost:8443/carts/c-1", "application/json", nil)
		require.NoError(t, err)
		requireJSON(t, resp, http.StatusMethodNotAllowed, "application/problem+json",
			`{"type":"about:blank","title":"Method Not Allowed","status":405}`)
		require.Equal(t, []string{"GET"}, resp.Header.Values("Allow"))

		p.Signal(syscall.SIGTERM)
		require.Zero(t, (<-status).Code())
		require.Equal(t, []string{"GET /carts/{cartId}", "GET /carts/{cartId}", "POST"}, spanNames(tel))
	})
}

The list of what the tests show changes in these items. The rest is as in the post:

NewAPI's errors. One table case for each mistake it reports, and two bad operations reported in one error. The mistakes are:
- a missing title or version, and a nil catch-all;
- a literal that is empty, holds /, {, % or a space, or is ..;
- a parameter name that isn't an identifier, and a parameter twice in one path;
- a parameter given twice to an operation, and each constraint on the wrong type;
- a default outside its enum;
- a body or response type that is a bare io.Reader, and a 204 status with a body;
- two types at one status, including against an API-wide Error, the catch-all, and a non-Problem at 400;
- one method and path twice, and two paths that differ only in their parameters' names;
- a document path with a parameter, and an operationId used twice.
Routing:
- a 404 and a 405 are Problems, the 405 with Allow;
- //carts is a 404, with no redirect;
- /carts/a%2Fb reads as a/b;
- spans are named after the route, and the root's span is GET /.
ParamFrom of a parameter the operation doesn't read is answered by the catch-all, and recorded.
Bodies and responses:
- a Stream[M] round trip, with its media type in the document and its reader closed;
- an EmptyBody response is a 204 with no body and no Content-Type.
The compile errors aren't tested. They are the compiler's.

Migration from today

The table is replaced:

Before the reset	With this proposal
`rest.Run(ctx, rest.Title(…), rest.Version(…), rest.Handle(route))`	`httpserver.Main(Init)`, with `Init` calling `openapi.NewAPI(s, openapi.Info{…}, openapi.CatchAll(…), ops)` and `httpserver.NewService`
`bedrockrest.Build(opts...)`, a `bedrock.Builder[http.Handler]`	`openapi.NewAPI`, an `*openapi.API` and an error
`Title`, `Version`, `APIDescription`; defaults `"API"` and `"0.0.0"`	`openapi.Info`; `Title` and `Version` required
`SpecPath`, default `/openapi.json`	`openapi.Document(path)`, an operation; no document unless the operations include one
`rest.GET("/carts/{cartId}", h)` … `DELETE`, a path template	`openapi.Get(cart, h, parts...)` … `Delete`, with `cart := openapi.Root().Lit("carts").Param(cartID)`
`cartID.Read(ep)` for a path parameter	nothing: the path declares it
`p.Read(ep)` for a query or header parameter	`openapi.Query(p)` or `openapi.Header(p)`, a part
`Summary(s, ep)`, `EndpointDescription`, `Tags`, `OperationID`, `MarkDeprecated`	`openapi.Summary(s)`, `Description`, `Tags`, `OperationID`, `Deprecated()`, as parts
`PathParam[T any](name, opts...)`, an unsupported `T` failing every request with 400	`openapi.PathParam[T ParamValue](name)`, a compile error, with constraints as methods
`Pattern(string)`, a bad expression failing every request	`.Pattern(*regexp.Regexp)`
`ParamFrom` returns the zero value for a parameter the endpoint didn't read	it panics, naming the parameter
chi, `chi.URLParam`	chi inside the API, read with `openapi.ParamFrom`; spans named after the route
`ReadJSON[T]`	the handler's body type: JSON unless it is `EmptyBody` or a `Stream`; plus 415, 413 and trailing data
`ReadBinary(ct)`, `WriteBinary(status, ct)`	`openapi.Stream[M]`, with `M` naming the media type
`ReadFormFile`, `ReadFormField`	dropped
`WriteJSON[Resp](status)`, written with the encoder's error ignored	the handler's response type, and `openapi.Status`; encoded before the status is written
a 204 with `WriteBinary(204, "", …)` and an empty reader	an `EmptyBody` response, 204 by default
`ErrorJSON[E](status, ep)` on every route	`openapi.Error[E](status)`, given to an operation or to `NewAPI`
`CatchAll[E](status, wrap, ep)` on every route	`openapi.CatchAll(status, wrap)`, given to `NewAPI`, and to an operation that overrides it
a bad parameter or body: `{"param", "error"}` and a 400 outside the document	an `openapi.Problem` and a documented 400, 413 or 415
chi's plain-text 404 and 405	`openapi.Problem`s, with `Allow` on the 405
an error the catch-all answered: lost	an ERROR record and a span event
a panic: bedrock's `RecoverPanics` around the runtime	the catch-all, recorded
`otelhttp.NewHandler(h, "rest")` on the globals, spans named `rest`	`httpserver`'s instrumentation
`example/rest/shoppingcart` in the root module; `os.Getenv("DATABASE_URL")` and `pgxpool.New` in `main`	the `example` module; `Init` sources the URL, the pool dials through the `Host`, and `OnStop` closes it
the example's `specs/` (a hand-written `api.yaml`, sequence diagrams)	dropped; the served document is the golden file

The changes outside openapi are this proposal's stories, as in the post. The docs page is called "Serving an API with OpenAPI", and the "Serving HTTP" page's Migration from rest.Run section points at it.

Open questions

Questions 1–3 are as in the post. Question 4 is new:

Can the end user replace the 404 and 405 answers? As proposed, the package answers both with a Problem, and nothing replaces them. An APIOption for each, such as openapi.NotFound(h http.Handler), would let an API answer in another format, or serve a page. The cost is an API whose 404 isn't a problem detail while its other errors are. Recommendation: no option. Every answer the API gives is then a Problem. An end user who wants a different answer for paths outside the API mounts the API on a mux of their own, at the paths it serves.

Out of scope

"Problem detail bodies for ServeMux's 404 and 405" is removed: they are in scope now. These are added:

chi's middleware, sub-routers and regular-expression parameters. chi is how the API routes, and isn't part of its API.
Path parameters that match more than one segment, such as chi's *, and paths with a trailing slash.

References

These are added:

chi v5.5.0: Mux.NotFound, Mux.MethodNotAllowed and Mux.Find
The Go spec's method declarations, for the type parameter of Path.Param, a generic method

The ServeMux patterns link is removed.

0 replies

Zaba505 · 2026-10-18T03:45:14Z

Zaba505
Oct 18, 2026
Maintainer Author

Revision 2: open question 2 answered: `openapi/v3`, on the latest OpenAPI 3

Open question 2:

The package is openapi/v3, and its document follows the latest minor version of OpenAPI 3, which is 3.2.0 today. Like other versioned packages, the import path names the major version of OpenAPI that the package implements, so the end user can see which OpenAPI their service adheres to. Within that major version, the package follows the latest minor version, because OpenAPI's minor versions are meant to add to the one before, not break it. The post recommended 3.0.3. That recommendation is dropped, along with its reason: some client generators still read only 3.0.

Questions 1, 3 and 4 are still open.

Each section below replaces or adds to the part of the same name, as revision 1 left it. Throughout, the import path is github.com/z5labs/humus/openapi/v3, and the package's name is still openapi.

Summary

The first sentence becomes:

A new package, openapi/v3, in the core module, serves an API of typed operations and the API's OpenAPI 3.2 document.

Proposed API

The package clause becomes:

// Package openapi serves an API of typed operations, and its OpenAPI
// document, following the latest minor version of OpenAPI 3: 3.2.0.
package openapi // import "github.com/z5labs/humus/openapi/v3"

The import path and the package's name.

v3 is a directory of the core module, not a module of its own.
Its package is named openapi. So import "github.com/z5labs/humus/openapi/v3" is used as openapi.NewAPI, as github.com/go-chi/chi/v5 is used as chi.
Go tools that guess a package's name from its import path, such as goimports, skip a trailing /vN, so no alias is needed.
go vet and humus's golangci-lint config pass on this layout (checked).

It stays in the core module. As a nested module, its module path would end in /v3. Go reads that suffix as the module's own major version, so every release of it would have to be v3.x.y, and humus's versions would be tied to OpenAPI's.

The document

The bullet on OpenAPI 3.0.3 is replaced:

OpenAPI 3.2.0, published in September 2025, is the latest minor version of OpenAPI 3.
- 3.2 is a feature release on 3.1: it keeps 3.1's document format and JSON Schema 2020-12.
- Schemas are JSON Schema, so a pointer field is type: ["null", "boolean"], where 3.0 wrote nullable: true.
swaggest's openapi31 reflector generates it.
- swaggest/openapi-go v0.2.61, its latest release, has reflectors for 3.0.3 and 3.1.0, and none for 3.2. So the package uses the 3.1 reflector and sets the document's openapi field to 3.2.0.
- This was checked. The shoppingcart's add-item operation, generated this way, validates against the OpenAPI Initiative's published 3.2 schema. It also validates against the schema's schema-base variant, which checks each Schema Object against the 3.2 dialect too. A 3.1.0 document fails the 3.2 schema, as it should.
- A test keeps it so (see Testing), and the post's note on the reflector stands: openapi31 takes the same operation contexts as openapi3.
Following the latest 3.x. When OpenAPI publishes a new minor version of 3, humus moves the document to it in a release of its own, once the package can generate it, and the release notes say so. The end user's code doesn't change. Their served document states the new version, and their golden file, if they keep one, changes with it.

Testing

This is added:

The document is valid OpenAPI 3.2. The package's document tests validate every document they generate against the published 3.2 schema-base. So a swaggest release that writes something 3.2 rejects fails the build, not an end user's client generator.
- The OpenAPI Initiative's schemas, with the 3.2 dialect and meta-schema, are kept in testdata, so the test reads nothing from the network.
- The validator is santhosh-tekuri/jsonschema, a test-only dependency of the core module.

Migration from today

This row is added:

Before the reset	With this proposal
an OpenAPI 3.0.3 document	an OpenAPI 3.2.0 document, from `github.com/z5labs/humus/openapi/v3`; following the latest 3.x

Open questions

Question 2 is answered above. Questions 1, 3 and 4 stand.

Out of scope

These are added:

Serving a 3.0 or 3.1 document, or choosing which minor version the document is.
A package for a later major version of OpenAPI, which would be openapi/v4.

References

The OpenAPI 3.0.3 and 3.1.0 links are replaced:

OpenAPI 3.2.0, and its published schema-base
Go modules: major version suffixes

0 replies

Zaba505 · 2026-10-18T04:36:58Z

Zaba505
Oct 18, 2026
Maintainer Author

Revision 3: every body names its codec, and humus assumes none

Revision 1 fixed a body's encoding by the handler's types: EmptyBody was no body, Stream[M] was raw bytes, and anything else was JSON. Error[E] and CatchAll wrote E as JSON, and the package's own problems were application/problem+json. The review of that design found two faults:

It's closed. Serving XML, protobuf, msgpack, CBOR or CSV takes a change to humus.
It assumes JSON. That imposes an architecture decision on the end user.

This revision replaces it. Three designs were prototyped, and each compiles and serves the shoppingcart:

codec values that work on any, given once per API, in connect-go's style;
typed codecs, named on every operation;
body types that say how they are encoded, through methods.

Each one served the same API in JSON, in XML from a codec in a package of its own, and in streamed CSV. The typed codecs are chosen. They are the best from a types perspective. And because every operation names the content types it reads and writes, the API's code documents itself. Design decisions says why the other two weren't chosen.

What changes:

Every body names its codec. That covers an operation's request body, its response, each Error and CatchAll, and the package's own problems.
- A codec is typed: a Decoder[T] reads a body, and an Encoder[T] writes one.
- An operation takes them as functions. So a generic codec such as jsoncodec.Decoder is passed uninstantiated, and the compiler infers T from the handler.
- Nothing in openapi refers to JSON, and nothing has a default.
openapi/v3/jsoncodec ships JSON, because nearly every API will use it. It is opt-in, built on openapi's exported API alone, and named on each operation, as a third party's codec would be.
Stream[M], MediaType, the JSON default and the +json rule are gone. A stream is a codec of a type that streams, such as io.Reader or iter.Seq[T].
NewAPI takes the problems' encoder as an argument, as it takes the catch-all, so leaving it out doesn't compile.
The package writes the document itself, from each codec's media type and schema.

Questions 1, 3 and 4 are still open.

Each section below replaces the part of the same name, as revisions 1 and 2 left it. The parts of a section that aren't mentioned stand.

Summary

The bullet "An operation is one call" becomes:

An operation is one call, and it names its content types. Get, Post, Put, Patch and Delete take a typed path, a typed handler, a decoder for the request body (Post, Put and Patch), an encoder for the response, and the operation's parts. Every error answer names its encoder too. humus ships a JSON codec, openapi/v3/jsoncodec, and an end user or a third party writes any other. Nothing is assumed: an operation without its codecs doesn't compile.

Proposed API

These replace revision 1's operations, Error, CatchAll, NewAPI, EmptyBody, MediaType and Stream:

// Decoder reads request bodies of type T in one media type.
type Decoder[T any] interface {
	// MediaType is the body's media type, such as application/xml. A request
	// whose Content-Type names another media type, parameters aside, is
	// answered with a 415.
	MediaType() string

	// Schema describes T's bodies in the document. NewAPI calls it once,
	// and returns its error: a codec that can't handle T says so here.
	Schema() (Schema, error)

	// Decode reads r's body. An error that wraps *http.MaxBytesError is
	// answered with a 413, and any other with a 400 whose detail is the
	// error's text. A decoder that streams returns a T that reads the body
	// as the handler reads it.
	Decode(r *http.Request) (T, error)
}

// Encoder writes bodies of type T in one media type.
type Encoder[T any] interface {
	// MediaType is the body's media type. "" is no body: the document lists
	// no content, and nothing is written.
	MediaType() string

	// Schema is as Decoder's.
	Schema() (Schema, error)

	// Encode prepares v to be written, before the status is. Its error is
	// answered by the catch-all. The API then writes the status and calls
	// the WriterTo. A failure there is the client's: the response is cut
	// short. An encoder that buffers returns its encoded bytes, such as a
	// *bytes.Reader. An encoder that streams returns a WriterTo that writes
	// as it goes.
	Encode(v T) (io.WriterTo, error)
}

// Schema is a body's JSON Schema, as JSON, as the document lists it under
// the body's media type. A nil Schema lists the media type alone, as for
// raw bytes.
type Schema []byte

// SchemaOf returns T's JSON Schema, reflected from its fields, with each
// property named after the struct tag tag, such as "json" or "xml". A codec
// whose bodies are T's fields calls it from its Schema method.
func SchemaOf[T any](tag string) (Schema, error)

// EmptyBody is the body of a request that has none, and the response of a
// handler that writes none.
type EmptyBody struct{}

// EmptyDecoder and EmptyEncoder are EmptyBody's codecs: no body is read or
// written. A response with no body is a 204, unless Status says otherwise.
func EmptyDecoder() Decoder[EmptyBody]
func EmptyEncoder() Encoder[EmptyBody]

// The operations. Each takes a decoder for its request body (Post, Put and
// Patch) and an encoder for its response, as functions, so a generic codec
// function is passed uninstantiated and its type argument inferred from the
// handler. Get and Delete read no body.
func Get[Resp any](p Path, h func(context.Context, Request[EmptyBody]) (Resp, error), resp func() Encoder[Resp], opts ...Option) Operation
func Delete[Resp any](p Path, h func(context.Context, Request[EmptyBody]) (Resp, error), resp func() Encoder[Resp], opts ...Option) Operation
func Post[B, Resp any](p Path, h func(context.Context, Request[B]) (Resp, error), body func() Decoder[B], resp func() Encoder[Resp], opts ...Option) Operation
func Put[B, Resp any](p Path, h func(context.Context, Request[B]) (Resp, error), body func() Decoder[B], resp func() Encoder[Resp], opts ...Option) Operation
func Patch[B, Resp any](p Path, h func(context.Context, Request[B]) (Resp, error), body func() Decoder[B], resp func() Encoder[Resp], opts ...Option) Operation

// Error answers an error that matches E, with errors.As, with status and E,
// written by enc. Given to NewAPI, it answers on every operation, and every
// operation documents it. An operation's own Error for E overrides it.
func Error[E error](status int, enc func() Encoder[E]) APIOption

// CatchAll answers an error that no Error matched, and a panic of the
// handler, with status and E, written by enc: the error itself when it
// matches E, and wrap(err) otherwise. NewAPI requires one. An operation's
// own CatchAll overrides it.
func CatchAll[E error](status int, wrap func(error) E, enc func() Encoder[E]) Fallback

// Problems gives the encoder of the package's own problem responses:
//   - the 400 for a parameter or body that doesn't decode;
//   - the 413 and the 415;
//   - the 404 and 405 of a path or method the API doesn't serve.
//
// NewAPI requires one. Given to an operation, it replaces the API's for that
// operation's 400, 413 and 415.
func Problems(enc func() Encoder[Problem]) ProblemEncoding

// ProblemEncoding is the encoder Problems gives. It is an Option, as a
// Fallback is.
type ProblemEncoding interface{ Option /* and unexported */ }

// NewAPI returns an API that serves ops. problems encodes the package's own
// problem responses. catchAll is the catch-all of every operation that
// doesn't give its own. opts are given to every operation. The rest is
// revision 1's.
func NewAPI(s *humus.Setup, info Info, problems ProblemEncoding, catchAll Fallback, ops []Operation, opts ...APIOption) (*API, error)

// Problem is a problem detail, RFC 9457, in the encoding of the encoder
// Problems gives. Its tags name its members as RFC 9457 does, in both of the
// serializations the RFC defines, JSON and XML. A codec of another encoding
// names them itself.
type Problem struct {
	XMLName  xml.Name `json:"-" xml:"urn:ietf:rfc:7807 problem"`
	Type     string   `json:"type,omitempty" xml:"type,omitempty"`
	Title    string   `json:"title,omitempty" xml:"title,omitempty"`
	Status   int      `json:"status,omitempty" xml:"status,omitempty"`
	Detail   string   `json:"detail,omitempty" xml:"detail,omitempty"`
	Instance string   `json:"instance,omitempty" xml:"instance,omitempty"`
}

And the shipped JSON codec:

package jsoncodec // import "github.com/z5labs/humus/openapi/v3/jsoncodec"

// Decoder and Encoder are T's codecs as application/json. Problem is T's
// encoder as application/problem+json, for openapi.Problem and the types
// that embed it. Pass them uninstantiated:
//
//	openapi.Post(items, c.addCartItem, jsoncodec.Decoder, jsoncodec.Encoder)
func Decoder[T any]() openapi.Decoder[T]
func Encoder[T any]() openapi.Encoder[T]
func Problem[T any]() openapi.Encoder[T]

jsoncodec handles the details that are easy to get wrong:

It decodes one JSON value, and an empty body, malformed JSON, a value of the wrong type and data after the value are 400s.
Unknown fields are ignored.
http.MaxBytesHandler's error stays a 413.
Its Schema rejects a T that JSON can't decode into or encode, such as a channel, a function or an io.Reader, so the mistake is a NewAPI error rather than every request's.
It encodes into a buffer, so a value that can't be encoded is answered by the catch-all.

The core module's new dependencies change from swaggest/openapi-go to these two:

swaggest/jsonschema-go, for SchemaOf;
chi v5.

In the end user's `Init`

The NewAPI call becomes:

	api, err := openapi.NewAPI(s,
		openapi.Info{
			Title:       "Shopping Cart API",
			Version:     "1.0.0",
			Description: "API for managing shopping carts on an e-commerce platform.",
		},
		openapi.Problems(jsoncodec.Problem),
		openapi.CatchAll(http.StatusInternalServerError, endpoint.InternalError, jsoncodec.Problem),
		endpoint.Carts{Store: database.New(pool)}.Operations(),
		// Every operation addresses a cart that may not exist.
		openapi.Error[endpoint.NotFound](http.StatusNotFound, jsoncodec.Problem),
	)

And the operations name their codecs:

func (c Carts) Operations() []openapi.Operation {
	return []openapi.Operation{
		openapi.Post(items, c.addCartItem, jsoncodec.Decoder, jsoncodec.Encoder,
			openapi.OperationID("addCartItem"),
			openapi.Summary("Add an item to a shopping cart"),
			openapi.Status(http.StatusCreated),
		),
		openapi.Delete(item, c.removeCartItem, openapi.EmptyEncoder,
			openapi.OperationID("removeCartItem"),
			openapi.Summary("Remove an item from a shopping cart"),
		),
		// createCart, getCart, deleteCart and updateCartItem alike.
		openapi.Document(openapi.Root().Lit("openapi.json")),
	}
}

The handlers are unchanged from revision 1. A handler doesn't know its encoding: addCartItem takes an openapi.Request[AddItemRequest] and returns a database.CartItem.

Requests and responses

Revision 1's Bodies (under Requests) and Responses are replaced. The decoder reads the body before the handler runs, and the encoder writes the response:

A request's Content-Type must name the decoder's media type, parameters such as charset aside. Any other is a 415, and so is a missing one. application/merge-patch+json is a decoder of its own.
A decoder's error is a 400 whose detail is its text, and the handler isn't called. An error that wraps *http.MaxBytesError is a 413.
An encoder's Encode runs before the status is written. Its error is answered by the catch-all, so a value that can't be encoded is never a 200 with a broken body. An encoder that buffers returns its bytes. The API sets Content-Length when the WriterTo has a Len, as a *bytes.Reader does.
An encoder that streams returns a WriterTo that writes as it goes. The API hands it a writer that flushes each write, so the client gets each part as it is written. A failure after the status cuts the response short, so the client never sees what looks like a complete body. It is recorded on the request's span.
Whether a codec buffers or streams is the codec's to say, in its doc, not its type's. A stream is a codec of a type that streams.

A raw upload is three methods of the end user's own:

// rawCSV hands the handler the request body, unread.
func rawCSV() openapi.Decoder[io.Reader] { return rawCSVDecoder{} }

type rawCSVDecoder struct{}

func (rawCSVDecoder) MediaType() string                         { return "text/csv" }
func (rawCSVDecoder) Schema() (openapi.Schema, error)           { return nil, nil }
func (rawCSVDecoder) Decode(r *http.Request) (io.Reader, error) { return r.Body, nil }

openapi.Post(itemsCSV, c.importItems, rawCSV, jsoncodec.Encoder)

A typed stream works the same way: an Encoder[iter.Seq[CartItem]] whose WriteTo writes one CSV row for each item the handler's iterator yields. Both were prototyped, with tests that deadlock if either side buffers:

the handler stores the first uploaded row while the client is still sending the second;
the client reads the first exported row before the iterator yields the second.

An operation can use another encoding throughout. With a third party's XML codec, it overrides the API's problems, errors and catch-all:

openapi.Patch(item, c.updateCartItem, xmlcodec.Decoder, xmlcodec.Encoder,
	openapi.OperationID("updateCartItem"),
	openapi.Problems(xmlcodec.Problem),
	openapi.Error[NotFound](http.StatusNotFound, xmlcodec.Problem),
	openapi.CatchAll(http.StatusInternalServerError, internalError, xmlcodec.Problem),
)

Its 400, 404, 415 and 500 are application/problem+xml, with root <problem xmlns="urn:ietf:rfc:7807">. A 404 or 405 for a path no operation serves uses the API's Problems, since no operation matched.

Mistakes. Most mistakes are compile errors. The compile errors were checked with the compiler.

Mistake	Result
a body or response with no codec	compile error: not enough arguments
a decoder and an encoder swapped, such as `jsoncodec.Encoder, jsoncodec.Decoder`	compile error
a decoder given to `Error`, `CatchAll` or `Problems`	compile error
a non-generic codec of another type, such as a `protocodec.Cart` for an `AddItemRequest`	compile error
a constrained generic codec given a type outside its constraint, such as a protobuf codec's `T proto.Message`	compile error
a decoder given to `Get` or `Delete`	compile error
`Error(404, jsoncodec.Problem)` without `[E]`	compile error: cannot infer E
no `Problems` or no catch-all for `NewAPI`	compile error
a generic codec that can't handle its type, such as `jsoncodec` given a channel or an `io.Reader`	`NewAPI` error, from the codec's `Schema`
two encodings, or two types, at one status	`NewAPI` error, naming both
a `nil` codec function	`NewAPI` error
a request with another Content-Type	a 415, in the operation's `Problems` encoding
an error value that fails to encode	the catch-all answers it. If its own encoder fails too, the status alone is sent
a generic codec whose `Schema` doesn't check its type	found on a request
a codec that says it streams but buffers	not checkable: it's the codec's contract

Errors

Revision 1's model stands, with three changes:

Every answer names its encoder: Error[E](status, enc), CatchAll(status, wrap, enc), and Problems(enc) for the package's own problems.
Embedding Problem decides nothing. The encoder decides: jsoncodec.Problem writes application/problem+json, and jsoncodec.Encoder writes application/json.
The package's own problems are NewAPI's second argument, as the catch-all is its third. So an API can't be built without both.

The document

The package writes the document itself. Under each body's media type, it lists the schema the codec's Schema returns:

SchemaOf's reflection, named by the codec's own struct tag, such as xml, with the codec's additions such as OpenAPI's xml object;
a description, such as a protobuf message's name;
nothing, for raw bytes.

swaggest/openapi-go's operation reflector isn't used. It assumes every body is JSON: it writes any other request body as {"type":"string"}, and reads only json tags. SchemaOf reflects with swaggest/jsonschema-go.

A schema is inline rather than in components, because one Go type can have a different schema under each codec. The 3.2 validation of revision 2 covers every media type the tests generate, XML and CSV included.

Testing

These are added:

Each mistake in the table above.
- The compile errors have files behind a build tag, which a test builds to check that each one fails.
- The NewAPI errors are table cases.
Openness. A codec in a test package of its own, using only openapi's exported API, serves XML and problem+xml.
Streaming, with the two tests above that deadlock if a body is buffered, and a stream that fails mid-way cutting its response short.
jsoncodec:
- trailing data and a wrong type are 400s;
- an unknown field is ignored;
- a body over http.MaxBytesHandler's limit is a 413;
- a channel, a function or an io.Reader type is a NewAPI error.

Migration from today

These rows replace revision 1's:

Before the reset	With this proposal
`ReadJSON[T]`	`jsoncodec.Decoder`, given to the operation
`WriteJSON[Resp](status)`	`jsoncodec.Encoder`, and `openapi.Status`
`ReadBinary(ct)`, `WriteBinary(status, ct)`	a decoder or encoder of `io.Reader` in that media type, the end user's own
`ErrorJSON[E](status, ep)`	`openapi.Error[E](status, jsoncodec.Problem)`, or `jsoncodec.Encoder` for `application/json`
`CatchAll[E](status, wrap, ep)`	`openapi.CatchAll(status, wrap, jsoncodec.Problem)`
a bad parameter or body: `{"param", "error"}`	a `Problem`, in the encoding `Problems` gives

Design decisions

Revision 1's "The handler's types fix the encodings" is replaced:

Every body names its codec, and nothing has a default. humus doesn't know what an API's bodies are, so it doesn't guess. Naming the content types on every operation makes the API's code document itself. The cost is that a JSON-only API names jsoncodec on every operation.
Typed codecs, over the two other designs:
- Codec values on any, given once to NewAPI (Consumes, Produces, ProducesErrors) and overridden per operation. They read the shortest. But a codec that can't handle its type is found only by NewAPI, and only when the codec checks, never by the compiler.
- Body types with methods, such as json.Unmarshaler's. These make a body with no encoding a compile error. But they cost three methods on every request and response type, or a wrapper with a .Value field in every handler. They also give a Go type one encoding unless it is wrapped, and an embedded type's methods silently drop the fields added next to it.
Decoder and Encoder are separate. With one Codec interface for both directions, two generic codecs swapped between the body and response positions compiled. And a codec that only writes, given for a request body, failed every request with a 400. With two, both mistakes are compile errors (checked).
Codecs are passed as functions, so a generic codec needs no type argument. Passing a generic function uninstantiated is a less common Go idiom, and the compiler's messages name both types. A Go 1.27.0 compiler bug crashes when a generic function from another package is given to a struct-literal field. Function arguments compile. So operations take codecs only as arguments, and the docs page says why.
jsoncodec ships, opt-in. JSON will be used everywhere, and its details are easy to get wrong. It is a package of its own, named on each operation like any third party's codec, and openapi never uses it.
Problem has json and xml tags, because RFC 9457 defines exactly those two serializations. The tags name members; they choose no encoding.
The package writes the document. The reflector it used assumed JSON.

Out of scope

This is added:

More than one media type for a body, chosen by Content-Type or Accept (content negotiation). An operation's body has one codec. A second media type is a second operation.

References

These are added:

swaggest/jsonschema-go, for SchemaOf
RFC 9457 §6 and Appendix B: application/problem+json, application/problem+xml, and the XML form

The swaggest/openapi-go reference is removed.

0 replies

Zaba505 · 2026-10-18T04:44:01Z

Zaba505
Oct 18, 2026
Maintainer Author

Revision 4: a response that fails after its status is logged

Revision 3 says that once the status is written, an error from the encoder's WriterTo is "the client's". That holds when the copy fails because the client went away. It doesn't hold when the WriterTo does the server's own work after the status. For example:

copying an object from S3 to the client fails partway, because S3 does;
a database update that runs once the copy completes, such as marking the object downloaded, fails.

Those failures are the server's. Revision 3 recorded them on the span alone, and with the default telemetry, which exports no spans, they would be lost. This revision gives them the catch-all's rule.

Trailers are left out. They would let a response report a failure after its body, as gRPC reports a stream's status. They are revisited when a user asks for them. Until then, a failure after the status can only cut the response short.

Questions 1, 3 and 4 are still open.

Each section below replaces or adds to the part of the same name, as revision 3 left it.

Proposed API

Encoder.Encode's doc becomes:

	// Encode prepares v to be written, before the status is. Its error is
	// answered by the catch-all. The API then writes the status and calls
	// the WriterTo, which may do more work once it has written the body,
	// such as recording that a download completed. An error from the
	// WriterTo cuts the response short, and is the server's unless the
	// request's context is done. An encoder that buffers returns its
	// encoded bytes, such as a *bytes.Reader. An encoder that streams
	// returns a WriterTo that writes as it goes.
	Encode(v T) (io.WriterTo, error)

Requests and responses

The bullet "An encoder that streams" becomes:

An encoder that streams returns a WriterTo that writes as it goes. The API hands it a writer that flushes each write, so the client gets each part as it is written. The WriterTo runs on the request's goroutine, with the request's context still live. So it may do work once the body is written, and the handler's context, captured in the value the handler returned, is still usable there.
A WriterTo that returns an error cuts the response short. The status, and whatever part of the body was written, have already gone out. So the API aborts the response, by panicking with http.ErrAbortHandler, which httpserver and net/http pass through without logging. On HTTP/2 the stream is reset, and on HTTP/1.1 the connection is closed before the final chunk. The client sees a failed response rather than one that looks complete.
The error is recorded as the catch-all records one. It goes on the request's span as an exception event, and the span's status is set to Error. It also gets one ERROR record, response failed, in the request's context, with http.request.method, http.route, error.type and exception.message. When the request's context is done because the client went away, the error is recorded on the span alone.
A body that is all written may still look complete. When the WriterTo has a Len, the API sets Content-Length. A failure after the last byte then leaves the client with a body of the length it was promised. An encoder whose WriterTo does work after the body leaves Len out, so its response is chunked, and a failure is seen.

For example, an object copied from S3, then recorded in a database:

// download is what the handler returns: what to copy, and what to do once
// it has been copied.
type download struct {
	body io.ReadCloser // the S3 object's body
	done func() error  // runs after the last byte is written
}

func (f Files) getFile(ctx context.Context, req openapi.Request[openapi.EmptyBody]) (download, error) {
	key := openapi.ParamFrom(req, fileKey)
	obj, err := f.S3.GetObject(ctx, &s3.GetObjectInput{Bucket: &f.Bucket, Key: &key})
	if err != nil {
		return download{}, err // no status yet: answered by Error or CatchAll
	}
	return download{body: obj.Body, done: func() error {
		return f.DB.MarkDownloaded(ctx, key) // ctx is still the request's
	}}, nil
}

func objectStream() openapi.Encoder[download] { return downloadEncoder{} }

type downloadEncoder struct{}

func (downloadEncoder) MediaType() string                      { return "application/octet-stream" }
func (downloadEncoder) Schema() (openapi.Schema, error)        { return nil, nil }
func (downloadEncoder) Encode(d download) (io.WriterTo, error) { return d, nil }

func (d download) WriteTo(w io.Writer) (int64, error) {
	defer d.body.Close()
	n, err := io.Copy(w, d.body)
	if err != nil {
		return n, err // S3 failed partway: response failed, and the response is cut short
	}
	return n, d.done() // a failed update: the same
}

openapi.Get(file, f.getFile, objectStream, openapi.OperationID("getFile"))

The status is written before the first byte of the body, as HTTP requires and as http.ResponseWriter does. So a status that depends on the update needs the object copied somewhere else first. Its Encode copies the object to a temporary file and runs the update, then returns a WriterTo over the file.

Telemetry

This row is added to the table of records:

Record	Severity	When
`response failed`	ERROR	the encoder's `WriterTo` failed after the status was written, and the client is still there

Testing

These are added:

A WriterTo that fails partway through the body, or after all of it, produces one response failed record carrying the request span's trace_id and span_id, and an exception event on the span. Without a Content-Length, the client sees its response cut short: io.ErrUnexpectedEOF over HTTP/1.1, and a stream error over HTTP/2.
A WriterTo that fails because the client went away is recorded on the span, and isn't logged.
httpserver records no handler panicked for the abort.

Design decisions

This is added:

The encoder keeps http.ResponseWriter's order. Encode runs before the status, and its error still gets a status of its own. The WriterTo runs after the status, as a handler's writes follow its WriteHeader, and can do work once the body is written. An end user moving from a plain handler writes their code in the order they already know. A failure after the status is the server's to log, as it would be in that handler.

Out of scope

This is added:

Trailers, and headers known only once the body is written. They are revisited when a user asks for them.

0 replies

Zaba505 · 2026-10-18T04:54:39Z

Zaba505
Oct 18, 2026
Maintainer Author

Revision 5: the open questions answered

The three questions still open:

A panic is answered by the catch-all, as recommended. An API must keep its contract: every operation answers as its document says. A panic that crashes the request doesn't, so the package recovers it and answers with the catch-all. This revision extends the same rule to the operation's codecs (see Panics).
The example keeps Postgres, as recommended. The reference service is where the end user sees a real dependency built in Init, dialed through the Host and released with OnStop.
The end user answers 404 and 405, and must give both. The package forces no error format anywhere else: revision 3 made every other answer's encoding the end user's choice. So the 404 and 405 are the end user's too, as two http.Handlers in a struct NewAPI requires: openapi.Unmatched.

With that, nothing in openapi needs a problem type. The package's own 400, 413 and 415 become *openapi.RequestErrors. The end user answers them through openapi.RequestErrors(wrap, enc), which replaces revision 3's Problems, in whatever type and encoding they choose. So problem details become a package of their own, openapi/v3/problem, opt-in, as jsoncodec is. It holds RFC 9457's Details, a wrap for RequestErrors, and a handler for Unmatched.

The proposal has no open questions left.

Each section below replaces or adds to the part of the same name, as revisions 1 to 4 left it.

Proposed API

These replace revision 3's Problems, ProblemEncoding, Problem and NewAPI:

// Unmatched answers the requests no operation matches. Its answers aren't
// in the document. NewAPI requires both handlers.
type Unmatched struct {
	// NotFound answers a request whose path no operation serves.
	NotFound http.Handler

	// MethodNotAllowed answers a request whose path an operation serves,
	// but not with the request's method. The API sets the Allow header,
	// listing the path's methods, before it calls MethodNotAllowed.
	MethodNotAllowed http.Handler
}

// RequestError is a request an operation rejected before its handler ran.
type RequestError struct {
	// Status is:
	//   - 400 for a parameter or a body that doesn't decode or validate;
	//   - 413 for a body over http.MaxBytesHandler's limit;
	//   - 415 for a Content-Type the operation's decoder doesn't read, or
	//     none.
	Status int

	// Param names the parameter that doesn't decode, for a 400 about one,
	// and is "" otherwise.
	Param string

	// Err is why: the parameter's error or the decoder's.
	Err error
}

func (e *RequestError) Error() string
func (e *RequestError) Unwrap() error

// RequestErrors answers every RequestError with its Status and with
// wrap's value, written by enc. Every operation documents it: at 400 when
// the operation reads a parameter or a body, and at 413 and 415 when it
// reads a body. NewAPI requires one. Given to an operation, it replaces
// the API's for that operation.
func RequestErrors[E any](wrap func(*RequestError) E, enc func() Encoder[E]) RequestErrorAnswer

// RequestErrorAnswer is what RequestErrors returns. It is an Option, as a
// Fallback is.
type RequestErrorAnswer interface{ Option /* and unexported */ }

// NewAPI returns an API that serves ops:
//   - unmatched answers the requests no operation matches;
//   - requestErrors answers the requests an operation rejects;
//   - catchAll is the catch-all of every operation that doesn't give its
//     own;
//   - opts are given to every operation.
//
// A nil handler in unmatched is a NewAPI error. The rest is as revision 1
// describes it.
func NewAPI(s *humus.Setup, info Info, unmatched Unmatched, requestErrors RequestErrorAnswer, catchAll Fallback, ops []Operation, opts ...APIOption) (*API, error)

openapi no longer has a Problem type. Nothing in it names a problem type or an error format.

And the opt-in package:

package problem // import "github.com/z5labs/humus/openapi/v3/problem"

// Details is a problem detail, RFC 9457. Its tags name its members as RFC
// 9457 does, in both of the serializations the RFC defines: JSON and XML.
// A type that embeds it is a problem detail of its own.
type Details struct {
	XMLName  xml.Name `json:"-" xml:"urn:ietf:rfc:7807 problem"`
	Type     string   `json:"type,omitempty" xml:"type,omitempty"`
	Title    string   `json:"title,omitempty" xml:"title,omitempty"`
	Status   int      `json:"status,omitempty" xml:"status,omitempty"`
	Detail   string   `json:"detail,omitempty" xml:"detail,omitempty"`
	Instance string   `json:"instance,omitempty" xml:"instance,omitempty"`
}

// Error returns Detail, or Title when Detail is empty.
func (d Details) Error() string

// FromRequestError returns e as a problem detail: type about:blank, the
// name of e's status as its title, and e's error's text as its detail. It is
// a wrap for openapi.RequestErrors.
func FromRequestError(e *openapi.RequestError) Details

// Handler answers every request with status and a problem detail, written
// by enc. The detail's type is about:blank and its title is the status's
// name. It is a handler for openapi.Unmatched.
func Handler(status int, enc func() openapi.Encoder[Details]) http.Handler

problem and jsoncodec use only openapi's exported API, as a third party's packages would. jsoncodec.Problem stays where it is: it is T's encoder as application/problem+json, whatever T is.

In the end user's `Init`

The NewAPI call becomes:

	api, err := openapi.NewAPI(s,
		openapi.Info{
			Title:       "Shopping Cart API",
			Version:     "1.0.0",
			Description: "API for managing shopping carts on an e-commerce platform.",
		},
		openapi.Unmatched{
			NotFound:         problem.Handler(http.StatusNotFound, jsoncodec.Problem),
			MethodNotAllowed: problem.Handler(http.StatusMethodNotAllowed, jsoncodec.Problem),
		},
		openapi.RequestErrors(problem.FromRequestError, jsoncodec.Problem),
		openapi.CatchAll(http.StatusInternalServerError, endpoint.InternalError, jsoncodec.Problem),
		endpoint.Carts{Store: database.New(pool)}.Operations(),
		// Every operation addresses a cart that may not exist.
		openapi.Error[endpoint.NotFound](http.StatusNotFound, jsoncodec.Problem),
	)

endpoint.NotFound is struct{ problem.Details }, and endpoint.InternalError returns a fixed problem.Details. RequestErrors infers E from its wrap, and problem.Handler takes jsoncodec.Problem uninstantiated. Both were checked with the compiler.

An operation in another encoding overrides RequestErrors as it overrides Error and CatchAll:

	openapi.RequestErrors(problem.FromRequestError, xmlcodec.Problem),

Routing

The bullet "What no operation serves is answered with a problem detail" is replaced:

What no operation serves is answered by the end user's Unmatched. A path no operation serves goes to NotFound. A method its path doesn't serve goes to MethodNotAllowed, after the API has set the Allow header. chi doesn't pass its own handlers the allowed methods, so the API finds them with chi's Find, as before.
- The package writes nothing itself. Its answers aren't in the document, and it doesn't log them.
- problem.Handler answers with a problem detail, for an end user who wants one.
- chi redirects nothing, as before.

Requests and responses

Wherever revision 3 answers in "the operation's Problems encoding", the operation's RequestErrors answers instead. These rows of the table of mistakes change:

Mistake	Result
no `RequestErrors` or no catch-all for `NewAPI`	compile error
a nil `NotFound` or `MethodNotAllowed`	`NewAPI` error
a request with another Content-Type	a 415, answered by the operation's `RequestErrors`

Errors

The bullet "The package's own problems are NewAPI's second argument" is replaced:

The package's own rejections are *RequestErrors, answered by RequestErrors, NewAPI's fourth argument. The requests no operation matches are answered by Unmatched, its third. So an API can't be built without an answer to each.

Panics

"This is open question 1" and the sentence after it are replaced. The rule covers the operation's codecs as well as its handler:

A panic of the handler, or of the operation's decoder in Decode or encoder in Encode, is answered by the catch-all. All of these run before the status is written. It is recorded as revision 1 records a panic: an exception event with the stack, the span's status set to Error, and one ERROR record. The record is renamed operation panicked, since it now covers the codecs too.
A panic in the encoder's WriterTo, after the status, cuts the response short, as its error does in revision 4, and is recorded the same way.
A panic while answering can't be answered by the catch-all again. This covers a panic in a wrap, or in the encoder of an Error, a CatchAll or RequestErrors. httpserver records it and aborts the response, as for any http.Handler. So do Unmatched's handlers, which aren't operations.
A handler that panics with http.ErrAbortHandler is passed through untouched, as before.

The cost stays grpcserver's: whatever the handler left half-changed stays that way, for the requests that follow.

Telemetry

The record handler panicked is renamed operation panicked. It is emitted when the handler, or one of the operation's codecs, panicked.

Testing

These are added:

Unmatched:
- each handler is called, the MethodNotAllowed one with Allow already set;
- a nil NotFound or MethodNotAllowed is a NewAPI error;
- the package writes and logs nothing of its own for either.
RequestErrors:
- its E is documented at 400, 413 and 415 on the operations that can answer with them;
- an operation's own replaces the API's;
- its wrap gets the RequestError with its Status, its Param and the decoder's error.
Panics:
- a panic in a decoder's Decode or an encoder's Encode is answered by the catch-all, with one operation panicked record;
- a panic in a WriterTo cuts the response short;
- a panic in a wrap is aborted by httpserver.
problem:
- FromRequestError names the status and carries the error's text;
- Handler writes its status and detail through the encoder it is given;
- Details encodes as RFC 9457's JSON and XML forms, the XML in the urn:ietf:rfc:7807 namespace.

Migration from today

These rows replace revision 3's:

Before the reset	With this proposal
a bad parameter or body: `{"param", "error"}`	a `*openapi.RequestError`, answered by `RequestErrors`, such as `RequestErrors(problem.FromRequestError, jsoncodec.Problem)`
chi's plain-text 404 and 405	the end user's `openapi.Unmatched` handlers, such as `problem.Handler`
the example's own problem type	`problem.Details`, embedded

Design decisions

Revision 1's "A panic is answered by the catch-all" is replaced, and these are added:

A panic is answered by the catch-all, of the handler and of the operation's codecs. The API keeps the contract its document states.
The end user answers every error, the 404 and 405 included. openapi forces no error format, so it has no answer of its own to give. Both handlers are required, so no request is answered by something the end user didn't choose.
Unmatched is a struct, so its two handlers are named and can't be swapped. The cost: a nil field is a NewAPI error, not a compile error.
Problem details are a package of their own. Nothing in openapi makes an API use them. Like jsoncodec, problem is opt-in, built on openapi's exported API, and named where it is used.

Open questions

None.

0 replies

Zaba505 · 2026-10-18T14:36:42Z

Zaba505
Oct 18, 2026
Maintainer Author

Closing: the OpenAPI endpoint DSL has landed

The revisions' stories are done:

story(openapi): serve typed operations on typed paths with openapi.NewAPI #835 served typed operations on typed paths with openapi.NewAPI, routed by chi, with the end user's Unmatched and RequestErrors answering what no operation does (story(openapi): serve typed operations on typed paths with openapi.NewAPI #847);
story(openapi): declare query, header and path parameters with typed constraints #836 declared query, header and path parameters with typed constraints (story(openapi): declare query, header and path parameters with typed constraints #849);
story(openapi): serve the API's OpenAPI 3.2 document from its operations and codecs #837 served the API's OpenAPI 3.2 document from its operations and codecs, with SchemaOf and a test that validates generated documents against the 3.2 schema-base (story(openapi): serve the API's OpenAPI 3.2 document from its operations and codecs #852);
story(openapi): stream bodies both ways, and log a response that fails after its status #838 streamed bodies both ways, and cut a response short with one response failed record when its encoder fails after the status (story(openapi): stream bodies both ways, and log a response that fails after its status #854);
story(openapi): answer a panic in a handler or codec with the catch-all #839 answered a panic in a handler or codec with the catch-all, recorded as operation panicked (story(openapi): answer a panic in a handler or codec with the catch-all #856);
story(jsoncodec): read and write JSON bodies with openapi/v3/jsoncodec #840 read and wrote JSON bodies with the opt-in openapi/v3/jsoncodec (story(jsoncodec): read and write JSON bodies with openapi/v3/jsoncodec #858);
story(problem): answer with RFC 9457 problem details from openapi/v3/problem #841 answered with RFC 9457 problem details from the opt-in openapi/v3/problem (story(problem): answer with RFC 9457 problem details from openapi/v3/problem #860);
story(example): rebuild the shoppingcart as the reference service on openapi/v3 and Postgres #842 rebuilt the shoppingcart as the reference service on openapi/v3 and Postgres (story(example): rebuild the shoppingcart as the reference service on openapi/v3 and Postgres #861);
story(docs): document serving an API with OpenAPI #843 documented serving an API with OpenAPI, on a new page that follows "Serving HTTP" (story(docs): document serving an API with OpenAPI #865).

Revision 5 left no open questions. The package is openapi at github.com/z5labs/humus/openapi/v3 and follows OpenAPI's latest 3.x minor; each operation names its Decoder[T] and Encoder[T], and no format is imposed; panics are answered by the catch-all; and the end user supplies the 404 and 405.

The rest is out of scope or belongs to other proposals, as "Out of scope" and its revisions list:

Authentication, authorization and OpenAPI security schemes are Proposal: authentication and authorization (wave 5).
Failure injection is Proposal: failure injection (wave 5), in httpserver's chain.
Walkthroughs and mapping v0.15.0's rest.NewApi are Proposal: walkthroughs and a humus MIGRATING.md (wave 6). Generating code for the DSL is Proposal: AI tooling (wave 6).
Response headers, cookies, content negotiation, HTML and template responses, interceptors, form and multipart bodies, array and repeated query parameters, validating request bodies against their schema, trailers, chi's middleware and sub-routers, multi-segment path parameters, a 3.0 or 3.1 document, openapi/v4, a YAML document or documentation UI, and generating Go code from a document stay out of scope.

0 replies

Navigation Menu

Repository navigation

Proposal: OpenAPI endpoint DSL #760

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 6 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Proposal: OpenAPI endpoint DSL #760

Uh oh!

Uh oh!

Zaba505 Oct 17, 2026 Maintainer

Summary

Background

Proposed API

In the end user's Init

Routing

Requests

Responses

Errors

Panics

The document

Telemetry

What waves 5 and 6 build on this

Design decisions

Testing

The shoppingcart

Migration from today

Open questions

Out of scope

References

Replies: 6 comments

Uh oh!

Zaba505 Oct 18, 2026 Maintainer Author

Revision 1: openapi, NewAPI, typed paths, one call per operation, and chi

Summary

Background

Proposed API

In the end user's Init

Routing

Requests

Responses

Errors

The document

Telemetry

What waves 5 and 6 build on this

Design decisions

Testing

Migration from today

Open questions

Out of scope

References

Uh oh!

Zaba505 Oct 18, 2026 Maintainer Author

Revision 2: open question 2 answered: openapi/v3, on the latest OpenAPI 3

Summary

Proposed API

The document

Testing

Migration from today

Open questions

Out of scope

References

Uh oh!

Zaba505 Oct 18, 2026 Maintainer Author

Revision 3: every body names its codec, and humus assumes none

Summary

Proposed API

In the end user's Init

Requests and responses

Errors

The document

Testing

Migration from today

Design decisions

Out of scope

References

Uh oh!

Zaba505 Oct 18, 2026 Maintainer Author

Revision 4: a response that fails after its status is logged

Proposed API

Requests and responses

Telemetry

Testing

Design decisions

Out of scope

Uh oh!

Zaba505 Oct 18, 2026 Maintainer Author

Zaba505
Oct 17, 2026
Maintainer

In the end user's `Init`

Zaba505
Oct 18, 2026
Maintainer Author

Revision 1: `openapi`, `NewAPI`, typed paths, one call per operation, and chi

In the end user's `Init`

Zaba505
Oct 18, 2026
Maintainer Author

Revision 2: open question 2 answered: `openapi/v3`, on the latest OpenAPI 3

Zaba505
Oct 18, 2026
Maintainer Author

In the end user's `Init`

Zaba505
Oct 18, 2026
Maintainer Author

Zaba505
Oct 18, 2026
Maintainer Author

In the end user's `Init`

Zaba505
Oct 18, 2026
Maintainer Author