[andreashasse]

Draft: waiting for user feedback before merge and release. This is one of four aligned PRs. The Elixir ones depend on the others through git branches, so the whole set can be tried together. Nothing is released yet; the git dependencies go back to Hex versions after feedback.

nil_fields has three values. It applies to a field whose type can be missing (T | undefined, or Elixir T | nil).

{spectra, [{nil_fields, ...}]}	Schema	Encoding of the missing value	Allowed per-call {nil_fields, _}
omit_or_null (new default)	not required, allows null	left out	null or omit
omit (the old default)	not required, no null, the old schema	left out	omit
null (0.16)	required, allows null	null	null

• Per-call option: encode/5 accepts {nil_fields, null | omit}, which changes only that call's encoding, nested values included. Schemas and OpenAPI always follow the global setting. Any one type therefore has one schema, and a type shared by an API response and a webhook payload needs no second component.
• Rejected combinations: an option that would break the schema raises badarg with error_info, which Elixir sees as ArgumentError. The raised error does not carry the encoded data, so it cannot end up in logs.
• Upgrading: with no config change, encoding output stays the same. Schemas of fields that can be missing gain null, which matches what the decoder already accepted. Set nil_fields to omit to keep the old schema.
• Null placement: a missing value at the top level, or as a list element such as [integer() | nil], now encodes as null instead of "nil" or "undefined". Its schema allows null, except under omit. allow_null is idempotent, so a field typed through a nullable alias gets one null, not two.

Fixes:

• A documented parameter or response header no longer repeats description and deprecated inside its schema.
• Error ctx messages are always binaries.

make build-test passes (833 tests, eqwalizer, lint, dialyzer and the rest), as do make doc and rebar3 proper. The encoded output is validated against the generated schema with jesse, and the OpenAPI output with openapi-spec-validator.

🤖 Generated with Claude Code