Document Ecto jsonb usage, fix two codec spec gaps

[andreashasse]

Why

Spectral already handles jsonb columns. Ecto encodes and decodes those values as Elixir maps, and :pre_encoded / :pre_decoded convert those maps to and from your types. That was never written down, so it kept getting reported as a missing feature.

Library fixes

Working through this surfaced two places where Spectral.Codec promised one thing and did another. Both are fixed here.

Recursive helpers ignored type references. Spectral.Codec.encode/5, decode/5 and schema/4 are spec'd to take sp_type_or_ref(), which is sp_type() | sp_type_reference(), and a reference is exactly {:type, name, arity} or {:record, name}. Passing one did not work. It fell through the traversal as an unrecognised term and surfaced as a type_mismatch naming a type the caller never asked about. The helpers now resolve references, mirroring spectra's own private resolve_type_ref/2.

The schema/5 callback could not decline a type. The README already said to return :continue for types a codec does not handle, and spectra_json_schema matches on continue and falls through. Only the @callback disagreed, declaring map(). Now map() | :continue, with the doc noting that once implemented, the callback receives every type in the module.

Covered by test/spectral_codec_helpers_test.exs. Verified it fails against the previous implementation: 3 of 7 tests fail without the change, all 7 pass with it.

Documentation fixes

The codec docs had drifted since the arity change in 0.12.0. Anyone copying the custom codec example got callbacks that do not match the declared behaviour, which is a two-release-old bug rather than a tidy-up, so it is in the changelog under Fixed.

• The MyGeoModule example defined encode/7, decode/7 and schema/6 with a separate params argument. It now uses encode/6, decode/6 and schema/5 with caller_type_info and target_type, matching the Spectral.Codec moduledoc, plus the schema/5 catch-all the section below it recommends.
• The "Type Parameters" section described params as a callback argument. It was removed in 0.12.0; codecs read type_parameters with :spectra_type.parameters/1 on target_type.
• The Optional schema/6 callback heading is now schema/5.

New documentation

A README section, "Spectral and Ecto", covering the map boundary and two ways to handle a column whose type varies per row:

	Discriminator	Ecto field type
Self-describing union	inside the document	static
Sibling column	its own column	plain :map

The tagged variants carry their tag as a struct default, so %Circle{radius: 1.5} encodes with kind filled in and callers never write it by hand.

The section also flags a silent failure mode worth knowing about. Unions are first-match-wins and extra JSON keys are ignored, so an untagged variant whose fields are a subset of another's swallows documents meant for the later variant and drops the extra keys with no error. The literal tag is what prevents it, which is why the docs push it rather than mention it.

What is deliberately not here

The Ecto.ParameterizedType wrapper. It belongs in a separate spectral_ecto library, tracked in #41, which can depend on Ecto normally and test against a real Postgres. Keeping it out avoids optional-dependency gymnastics here, and avoids pulling in decimal and its unfixed MEDIUM advisory (CVE-2026-32686) for every contributor.

Tests for the jsonb patterns. An earlier revision had them. They exercised Spectral's existing encode and decode without touching Ecto or a database, so they were removed in review. The meaningful tests need Ecto and Postgres, which is spectral_ecto's job.

Verification

make format && make ci passes on the current head: 224 tests, Credo strict clean, no duplication, Dialyzer 0 errors.

mix test --cover reports 14 TypeInfoEquivalenceTest failures. Those reproduce on unmodified main and are unrelated. Cover-compilation rewrites the BEAM those tests read abstract code from.

Merges from main

main picked up #42 (non-empty list shorthand) while this was open. Merged in; the only conflict was both branches adding entries under the same ### Fixed heading in the changelog, resolved by keeping both.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WvE2JYfi1tDoVW8pfrc4UU

[Copilot]

🟡 Changes recommended

README examples and callback documentation contain the noted inconsistencies and need correction before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Documents Ecto jsonb usage and fixes codec reference resolution and schema callback typing.

Changes:

• Resolves type and record references in codec helpers.
• Allows schema callbacks to return :continue, with regression tests.
• Adds Ecto guidance and changelog updates.

File summaries

File	Summary
test/support/codec_ref_module.ex	Adds codec reference fixtures.
test/spectral_codec_helpers_test.exs	Tests reference resolution and schema fallback.
README.md	Adds Ecto documentation. Five nit findings remain regarding callback contracts, stale arities, example validity, nested struct qualification, and Ecto schema placement (1–2 votes each).
mix.exs	Excludes new fixtures from generated documentation.
lib/spectral/codec.ex	Resolves references and updates callback specifications.
CHANGELOG.md	Records the fixes and documentation additions.

Review details

Suppressed comments (3)

README.md:388

• Ecto.Type.dump/3 itself returns {:ok, term} or :error, not a bare map. This comment makes the Ecto callback contract misleading; describe the map as the value encoded inside the dump callback instead.

# Ecto.Type.dump/3 returns a map for Ecto to store

README.md:345

• The new heading and paragraph use schema/5, but the following existing "Type Parameters" section still says the schema callback is schema/6 at README.md:482. Please update that reference too so the README does not present both callback arities.

The `schema/5` callback is optional. If a codec module does not export it, calling `Spectral.schema/3` for a type owned by that codec raises `{:schema_not_implemented, Module, TypeRef}`. Once you do export it, it receives every type defined in the codec module, so give it a catch-all clause returning `:continue` for the types the codec does not handle, exactly as with `encode/6` and `decode/6`.

README.md:473

• This code block is not valid as presented: MyApp.Notification is closed before field and def decode_payload, so field/3 and the function definition are at top level, __MODULE__ resolves to the wrong module, and the shown module does not enable Ecto.Schema. Keep these declarations and the function inside the Ecto schema module, or explicitly label and show them as an insertion fragment.

def decode_payload(%__MODULE__{kind: kind, payload: payload}) do
  Spectral.decode(payload, MyApp.Notification, kind, :json, [:pre_decoded])
end

• Files reviewed: 6/6 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.