binder / Docs / Compatibility

Compatibility

binder follows Semantic Versioning. Within a major version the list below will not change incompatibly, and the list after it may change in any release. Being explicit about the second list is what makes the first one worth anything.

Stable within a major version

The exported functions Bind, BindWithOptions and BindStruct.
The exported types BindOptions, BindError and Validator, and the meaning of their fields.
The sentinel errors ErrMalformedBody, ErrBodyTooLarge, ErrInvalidTarget, ErrMissingRequired and ErrUnknownField. Match on these with errors.Is rather than on message text.
The struct tags path, query, body, json, cookie and header, the order in which they take precedence, and the omitempty and required options.

Not part of the contract

The text of error messages. Only the sentinels and BindError's fields are stable; parsing a message is not supported.
The default value of MaxBodySize. Set it explicitly if your service depends on a particular limit.
The order in which fields are bound, and how many allocations binding takes.

Go version support

binder requires the two most recent major Go releases. It currently requires Go 1.27, for the standard library uuid package and native path values. Raising that minimum is a minor version bump, not a major one, in line with the wider Go ecosystem.

Built with Go 1.27, encoding/json is implemented on json/v2 and returns different error types, so errors.As(err, &*json.SyntaxError{}) no longer matches a malformed body. Test for ErrMalformedBody instead.

Upgrading from 1.0 to 1.1

1.1.0 is the first release intended for general use; 1.0 ran only on our own client projects. If you are arriving at binder fresh, none of this applies to you — it is written for those two codebases.

No exported function changed shape, so 1.1.0 is source compatible. It does change behaviour in cases that previously failed quietly, which is the point of most of it:

Change	What to expect
Request bodies are capped at 10 MB	Anything larger is `ErrBodyTooLarge` instead of being read into memory. The change most likely to be noticed — set `binder.MaxBodySize` at startup to raise, lower or remove it.
A body that cannot be parsed is an error	Malformed JSON previously bound nothing and reported success. Expect new 400s where there were quiet successes with empty fields.
Tag options now bind	`body:"email,omitempty"` searched for a key literally named `email,omitempty` and never bound. Such fields will start receiving values, which may surface data a handler never saw.
Chunked request bodies are read	They were skipped entirely, because the body was gated on a positive `Content-Length` and a chunked request declares none.
Repeated values fill slices	A query parameter, header or form field given more than once now binds every value to a slice field rather than the first. Non-slice fields are unaffected.
Go 1.27 is required	The previous release declared `go 1.25.1`; the documentation's claim of 1.22+ was never accurate.

The full list is in the changelog.

Security

binder parses untrusted input by design, so the body limit, the refusal to truncate and the absence of panics are treated as security properties rather than niceties. Report anything that looks like a vulnerability through the process in SECURITY.md rather than a public issue.