Update spectra to 0.14.1: nested doc annotations

[andreashasse]

What

Bumps the spectra dependency from ~> 0.13.1 to ~> 0.14.0 (which now resolves to 0.14.1) and bumps Spectral to 0.14.0. The ~> 0.14.0 constraint already covers every future 0.14.x patch release — it excludes 0.15.0 and above, where spectra's pre-1.0 versioning may carry breaking changes.

spectra 0.14.0 fixes doc annotations being dropped when a type is inlined into another schema. title, description, deprecated, examples and examples_function set with the spectral/1 macro now reach:

• struct and map field values
• list and non-empty list elements
• union branches
• optional map values
• remote types from other modules

Previously only the type schema generation was entered with kept its annotations, so deprecated: true on a type used as a struct field produced nothing in the output.

spectra 0.14.1 additionally fixes encoding a struct with non-map data (a string, integer, list, or atom): it crashed with a raw badmap error instead of returning {:error, [spectra:error()]}. Only the struct branch of encoding was affected; plain map types, list types, record types, and decoding were unaffected.

Wrapper compatibility

No API change was needed. The existing test suite passes unchanged against 0.14.1, and no callback signature, option, or delegation in Spectral, Spectral.OpenAPI, Spectral.TypeInfo or Spectral.Codec is affected.

One wrapper improvement is included. An examples value that does not encode as its own type raises {invalid_example, Type, Term, Errors} from spectra, which handle_erlang_error/4 previously re-raised as a raw ErlangError. 0.14.0 validates examples at every position a type appears in rather than only at entry points, so this error is far more reachable. It is now translated to an ArgumentError naming the offending example and type, matching how the other spectra errors are handled.

Behaviour change to be aware of

Generated JSON Schema and OpenAPI output changes for annotated sub-schemas: nested properties now carry the titles, descriptions, deprecation flags and examples their types declare. Consumers asserting on exact schema output may need updating.

examples_function is now invoked once per position the type appears in, rather than once per schema, so such functions should stay cheap and free of side effects.

Encoding a struct with non-map data now returns {:error, [%Spectral.Error{type: :type_mismatch}]} (or raises Spectral.Error from the bang variant) instead of crashing with a raw badmap error.

Tests

test/spectral_nested_doc_test.exs with two support modules covers:

• each inlined position (struct and map field values, list and non-empty list elements, union branches, optional map values, remote types)
• alias merging — the annotation nearest the use site wins, keys only one side sets are kept from both
• example validation at an inlined position
• examples_function call counts — a fixture counts its own invocations, and a type inlining it twice asserts two calls
• OpenAPI rendering — the response body $ref is followed into components.schemas and the nested titles and descriptions asserted there

test/spectral_struct_encode_test.exs (new) locks in the 0.14.1 fix: encoding non-map data against a struct type returns a type_mismatch error instead of crashing, for both encode/3 and encode!/3.

Suite is now 234 tests (20 doctests, 3 properties).

make ci is green: compile with --warnings-as-errors, tests, credo --strict, ex_dna, dialyzer, format check.

Docs

README gains a section on annotation propagation, alias merging, the three positions that still do not carry an annotation (all-literal unions, custom-codec types, parameterized types), and the per-position cost of examples_function. Install instructions and CHANGELOG updated for both the 0.14.0 and 0.14.1 spectra changes.

Note

make cover_diff fails on this branch, but it fails identically on main with spectra 0.13.1: 14 tests error under cover compilation with {:beam_lib_error, :cover_compiled, ...} because cover-compiled modules cannot be read back through beam_lib. Not caused by this change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XTMXez4gy2fHp6HgovtfGG

[Copilot]

🟡 Changes recommended

Two moderate test-coverage findings remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Updates Spectral to spectra 0.14.0, enabling nested annotation propagation and clearer invalid-example errors.

Changes:

• Bumps project and dependency versions.
• Adds nested annotation fixtures and tests.
• Improves invalid-example error handling.
• Documents annotation propagation and behavior.

File summaries

File	Summary	Findings
test/support/nested_doc_module.ex	Adds nested annotation fixtures.	—
test/support/nested_doc_bad_example_module.ex	Adds invalid-example fixture.	—
test/spectral_nested_doc_test.exs	Tests nested annotation propagation and validation.	Moderate (2 votes): add examples_function call-count coverage. Moderate (1 vote): add nested OpenAPI rendering coverage. Nit (3 votes): fix grammar.
README.md	Documents annotation behavior and alias merging.	—
mix.lock	Locks spectra at 0.14.0.	—
mix.exs	Updates project and dependency versions.	—
lib/spectral.ex	Translates invalid-example errors to ArgumentError.	—
CHANGELOG.md	Records the release changes.	—

Review details

Suppressed comments (1)

test/spectral_nested_doc_test.exs:14

• The new tests only render JSON Schema, but the PR also changes the generated OpenAPI schemas through :spectra_openapi. Without an OpenAPI rendering assertion for these nested annotations, a regression in that path could pass the suite.

  describe "annotations on inlined types" do
    test "a remote annotated type keeps its metadata as a map field value" do

• Files reviewed: 7/8 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.