Changelog

Rupa follows Semantic Versioning. Before 1.0, a minor version may rename or remove; each such change is listed here with the migration in one line.

0.1.0 — 2026-09-28

M8c — every format means what JSON Schema's does. The suite's optional/format corpus is vendored for the ten formats Rupa has, and test/rupa/format_suite_test.exs runs every string case in it through Rupa.Format and both backends: 474 of 474 agree, where 74 did not. Every change is a tightening, and these are the ones a caller will notice:

• T.time() needs an offset ("10:00:00" is an error) and decodes to UTC, as T.datetime() does. It encodes with a Z.
• A leap second (23:59:60, in UTC) decodes to the second before it; Calendar has no 60.
• T.datetime() and T.date() refuse a sign or a fifth digit on the year and a space for the T, and take t and z in lower case. A DateTime in another zone encodes in UTC, and a year outside 0000–9999 is refused in both directions.
• T.duration() is RFC 3339 appendix A: no fractions, weeks only alone, units nested (P1Y0M2D, never P1Y2D). The encoder writes the zeros the grammar needs.
• T.email() is RFC 5321's Mailbox. Quoted local parts, address literals and single-label domains are in; a leading, trailing or doubled dot, non-ASCII, and unquoted ;:(), are out.
• T.hostname() checks an xn-- label as an IDNA2008 A-label (Punycode, NFC, RFC 5892's properties and contextual rules; not the Bidi rule), from a table dev/idna/generate.exs derives from Unicode 17.0.
• T.uri() refuses malformed percent-encoding, T.ipv4() a leading +, T.ipv6() a zone id.

T.email() and T.hostname() are scanned rather than matched by a regex now, which makes them three to five times faster.

M10 — comparisons, docs, and everything but the publish. Both remaining open items in the design doc are settled, the README is no longer the one from M0, and there are now two benchmark suites whose numbers anyone can reproduce.

The identity. assets/ holds the lockup, mark, avatar and favicons: ꦫꦸꦥ in Hanacaraka beside the Latin name, Latu's system in teal, every glyph outlined so no reader needs a Javanese font. dev/logo/build.py draws all of it from two fonts; assets/README.md has the rules and the palette. The README opens with the lockup and hexdocs gets the tile as logo and favicon.

A generated codec's diagnostics are said again in terms of the schema. Rupa.compile/2 wraps the codegen in Code.with_diagnostics/1, so warning: this clause of defp j2/2 is never used no longer arrives in someone's boot log as itself. What comes out instead names the codec, says which of the three walks wrote the code, points at Rupa.explain/1, and says what the usual cause is — all in one warning per compile rather than one per finding, because a schema that earns any of these usually earns four. Nothing is dropped: Rupa's own dead clauses have been real bugs three milestones running.

The index that makes that possible is per direction, not per node. Rupa.Codegen.module/3 now returns {ast, index} where the index names every function the module defines. A map from a function to a node would have meant threading a path through every clause of three generators, and it would have bought less than it sounds: a definition only survives staging when it is recursive, and the type checker does not report inside a recursive group at all.

The JSON encoder stays unconditional. It is about 30% of codegen on top of the other two trees, and bench/BUDGET.md has the number, but an option is a thing to remember and a boot bill of a second or two for fifty codecs belongs in the docs instead.

bench/compare.exs, and it runs in CI. Peri, Ecto's embedded cast, :json.decode/1 as the floor, both Rupa backends and hand-written, all on bench/decode.exs's fixture with the same checks in every row. On a two-core runner: 24 reductions per op against Peri's 1600 and Ecto's 1254, and 48 words against 1866 and 1515. It asserts rather than prints — the budget from bench/BUDGET.md and a deliberately loose margin against the other two — and exits non-zero when one stops holding, because a benchmark that only prints is one nobody reads until someone happens to look.

bench/xlang/ builds one Docker image with five runtimes and runs the same job in each: bytes in, validated typed value out. serde_json, pydantic-core, Zod, Malli and Rupa, every version pinned, every column documented as to what it is allowed to do differently — serde has no declarative min_length, so that column validates by hand rather than dropping the constraint. On the sandbox: serde_json 624 ns, Zod 1836, Rupa 2412, pydantic-core 2837. Zod being above Rupa is a real result for V8 on a hot loop and is printed rather than left out. Malli's column is written to the same protocol and has not been run, because Maven is not reachable from where the rest of this was built; a column that will not run is named in the output rather than quietly dropped.

The README is now about the library rather than about the repository. It had said "this repository is the skeleton ... there is no public API behind them until M1" since M0. It now opens with code that runs, says what the vocabulary deliberately refuses, and carries both tables with the machine and date beside them.

Docs pass. Every public module is documented and grouped — "The API", "Exceptions" and "Inside", so the staging pass stops sitting in the sidebar beside the constructors. Every public function has a doctest or an example, except Rupa.Closure.build_encoder/1 and build_json/1, which are one-line cross-references to build/1 on purpose. Doctests went from 65 to 76, mostly the ten format constructors, which are the most-used part of the API and had a one-line description each.

mix hex.build ships 24 files: lib/ including the Mix task, .formatter.exs, mix.exs, README, LICENSE and CHANGELOG, with stream_data as the one optional requirement. Peri and Ecto are only: :dev and appear nowhere in the package.

M9 — structs, both ways. Rupa.T.object(%{...}, into: MyApp.User) decodes that object into a struct, and mix rupa.gen.struct writes the modules it names.

into: is an option on the object, not on the compile, which is what makes it compose: an address three levels down becomes a MyApp.Address the same way the root becomes a MyApp.User. A module name is an atom, so the schema still prints, hashes with :erlang.phash2/1 and embeds in generated code as a literal — and as: idempotence keys on that hash, which a compile option would have quietly broken by letting two different codecs collide on one name.

The module has to be there, and has to fit. Staging requires it to be loaded with a defstruct, and to already have every key the object decodes to — the names after rename_all:, from: and keys: have been spent, which is why the check happens after staging rather than against what you wrote. So renaming a field and forgetting to re-run mix rupa.gen.struct is :struct_field_missing naming the key, rather than a struct that quietly comes back with a default in it. The new codes are :not_a_struct, :struct_field_missing, :struct_keys, :struct_keeps_unknown and :struct.

Three of the object's own options cannot hold beside it, because a struct has atom keys and every one of them always: keys: :string, unknown: :keep, and a string-named object without the keys: :atom that M8a already makes you ask for.

T.optional/2 survives and loses its edge. Inside a struct the key is always there, so what decoding leaves behind for an absent field is that field's defstruct default, and encoding writes that same value back as absent. That is what keeps decode(encode(decode(w))) == decode(w) closing, and it is the one thing into: costs against the three states the rest of the library keeps apart. For a struct mix rupa.gen.struct wrote the value is nil, so an absent key and an explicit null reach the same struct and both leave as absent; a struct you wrote yourself may default the field to something else, and then that is what stands for absent and nil goes out as a null like any other value. A field with a default: of its own is not in this set at all — decoding always put something there, so a nil is a value the schema cannot express, and it errors.

mix rupa.gen.struct MyApp.Schemas.user calls that zero-arity function, stages the schema and writes one file per into: module at the path its name conventionally has under lib/: a defstruct and a @type t, with a schema default: carried through as the defstruct default, and nothing that mentions Rupa. --force overwrites, --dry-run prints. It stages with Rupa.Stage.run(schema, structs: :skip), which is the new option and exists for this. Keys and defaults go through Elixir's own printers rather than through interpolation, so a property name a document chose — first-name, say — comes out quoted in both the defstruct and the typespec instead of as a syntax error.

Elixir's type checker found the one clause that fell out of the design. When the absent value is nil, an optional nullable field's nil branch is unreachable inside a struct — the field chain has already written that nil as absence — so both backends encode through the nullable's inner node instead. Decoding still goes through the wrapper, because a wire null has to be allowed in.

Decode's budget did not move: 119/190 and 24/48 words and reductions per op, the same figures as M3, M5, M6 and M7. The closure backend's struct path is a separate function from the ordinary one rather than a base that may be nil, so an object with no into: pays nothing for the feature.

M8b — JSON Schema, both directions. Rupa.JsonSchema.encode/1 writes a draft 2020-12 document and decode/1 reads one. The official JSON-Schema-Test-Suite is vendored under test/fixtures/json-schema-suite/, pinned to an upstream commit, and every case runs on every build.

encode/1 is total, and describes the wire rather than the schema. It stages first, so rename_all:, from: and keys: are already spent and the property names are the wire keys. A $ref off a cycle has been inlined by then; genuine recursion comes back out as $defs and $ref, with a ref to the root written #. A default: is written in its wire form, through the field's own encoder — which is the only thing that knows how, since the value is decoded and the document wants what the wire would carry.

decode/1 interns nothing, which is what M8a was for: the objects it produces are named with strings, so no property name in a document ever becomes an atom. Two of Rupa's own constructs therefore encode but do not decode, both for the same reason — a tagged union's tag is an atom, and a recursive $ref needs a $defs name. A $ref that is not on a cycle needs no name, so it is inlined and ordinary reuse through $defs works.

It refuses out loud. Every keyword Rupa has no answer for is a named error with the path to it: :unsupported_keyword, :untyped_schema, :unsupported_mixed_object, :unsupported_bare_required, :unsupported_open_tuple, :unsupported_ref, :unsupported_recursive_ref, :unsupported_type_union. Writing that list is what turned up two places where an earlier cut dropped a constraint on the floor — required naming a key properties did not describe, and prefixItems read as a fixed-length tuple when the document had pinned neither end.

Where Rupa and the spec disagree is now measured rather than asserted. Four places, all in Rupa.JsonSchema's moduledoc: format asserts where JSON Schema annotates, pattern is PCRE, lengths count graphemes, and — the only one where Rupa is the stricter — a number is compared by term rather than by mathematical value, so 1.0 is not an integer and {"const": 0} does not match 0.0. The suite runner prints the pass rate, the skip reasons and those deviations, and fails on anything not in one of the two lists. It also fails on a deviation the suite has stopped reporting, so the list cannot go stale.

A whole-string anchoring bug in Rupa.Format, found by the format corpus. ^...$ in PCRE also matches before a final newline, so T.uuid(), T.email(), T.hostname() and T.duration() all accepted a value with a trailing newline. They now anchor with \A and \z. M8c vendors the corpus that found it.

M8a — an object's field names can be strings. {:object, %{"a" => T.string()}, []} is a schema, and it decodes to %{"a" => ...}. Names are all atoms or all strings per object; mixing them is :mixed_field_names, because keys: would then have nothing coherent to default to.

This exists for Rupa.JsonSchema.decode/1 in M8b, and it is what makes that path total. A JSON Schema names its properties, and turning those names into atoms is the one thing in the library that could grow the atom table from a document. Now nothing has to: a decoded schema is string-named, and the design doc's claim that Rupa has no atom-exhaustion path stays true with no exception written under it.

keys: defaults to the type of the name you wrote. An atom-named object decodes to atom keys, a string-named one to string keys, so neither default interns anything. keys: :atom on a string-named object is the single explicit place a name becomes an atom — and that is a name in a schema, not a key off a document, which is the rule every other atom in a schema already follows. It is the second and last String.to_atom/1 in the repo.

unknown: :keep no longer lets an unknown key shadow a field. A field claims three names — the wire key it reads, the wire key it writes, and the key it takes in the decoded map — and once a decoded key can be a string, any of the three can collide with a key the schema does not know. It was reachable before M8a with keys: :string and a from:, where the kept key won and the field's value was silently lost; now all three names are off limits to the extras in both directions, from one definition in Rupa.IR that both backends read.

Migration: a non-atom name in defs: now reports :invalid_def_name rather than :invalid_field_name, since the two no longer mean the same thing.

M7 — JSON, both directions. Rupa.decode_json/3 takes JSON text and Rupa.encode_json/3 writes it, on both backends. The two halves are not the same problem, and only one of them fuses; the milestone was told to measure before believing either way, and mix run bench/json.exs is the measurement.

encode_json/3 emits iodata in one walk of the decoded value. The two-step it replaces — encode/3 builds a wire map, a JSON encoder then walks it — costs 349 reductions and 505 words per op on the nested fixture; fused costs 162 and 314. On the module backend, 326/459 becomes 129/235. Wire keys, enum values and a tagged branch's whole ,"kind":"click" are rendered to binaries while the schema is staged, so what is left at run time is escaping the strings the value actually carries. The result is iodata, which is what a socket wants; IO.iodata_to_binary/1 flattens it. Fields come out in the schema's order rather than a map's, which is the one visible difference from going the long way round.

decode_json/3 does not fuse, and the callback API is why. :json.decode/3 hands a value's key to object_push only after that value is fully built, so when a nested object starts, nothing in scope says which field it belongs to — and a field is exactly where a schema differs from a parser. The accumulator threads down through object_start and array_start, which is enough to direct the root and an array's elements and not enough for an object's fields. There is no object_keys callback. So decode_json/3 is the two-step composition under the name it promised, the bench shows it lands on the sum of its parts, and a Rupa-owned parser is the way past it rather than in.

A JSON null decodes to nil. :json calls it the atom null by default; Rupa parses with null: nil so that present, absent and null stay the three states the rest of the library already means by them. That costs 14 reductions and 18 words per parse — passing any decoders map at all makes :json.decode/3 build its callback record per call — and it buys the only reading of null that composes with T.nullable/1.

Going the long way round needs an encoder that knows about nil. encode/3 returns nil for a null, and :json.encode/1 writes a bare atom as a string, so encode/3 piped into it quietly emits "nil" where the document should say null. Elixir's own JSON module gets this right, and so does :json.encode/2 with an encoder you supply. encode_json/3 has no such edge, which is a second reason to prefer it.

Malformed text is an error, not a raise. %Rupa.Error{code: :json} with the reason in meta, so a request handler has one shape to match on. Trailing whitespace is fine; trailing anything else is not.

A tagged branch with no fields of its own no longer warns. Its decoder is {:ok, %{}} and cannot fail, so the clause that would have handled its failure was dead code — which Elixir's type checker reports by the generated module's internal name, into whatever console the compile happens in. Found by an M7 test, fixed in the M6 code it came from.

Codegen got a third tree, and the boot bill shows it. A named codec now generates decode, encode and encode-to-JSON. bench/BUDGET.md has the number. The decode budget itself did not move: 119/190 and 24/48, the same as M5 and M6.

M6 — unions. Rupa.T.tagged/3 and Rupa.T.union/2 compile, on both backends, which completes the vocabulary: every kind the design doc lists now has a codec behind it, and :not_yet_supported is gone along with the last thing that raised it.

A tagged union decodes to {tag, value} — {:circle, %{r: 1.0}} — with the tag interned from the branch name while the schema is staged, never from wire data. That is one shape for both tagging styles and one case clause per branch at the other end. Internally tagged (the default) leaves the branch's own fields where they are; content: puts them in an envelope beside the tag, serde style, and a branch is then free to be any schema rather than an object. Encoding puts the tag back where it found it, so the round trip holds either way.

Tagged dispatch is one key read and one call, at any depth. The module backend matches the tag in the function head, so a branch is a direct call. mix run bench/union.exs is that claim with numbers under it: at depths 1 to 7, tagged grows by a falling factor per level while untagged holds at ×2.

An untagged union tries its variants in the order you wrote them, and the first that takes the value wins — so the order is part of the schema. Attempts run in :halt whatever on_error: said, because a variant you did not choose is one whose complaints you will never read; when none of them fits, the error is a single :no_variant rather than every variant's.

Nesting one untagged union inside another warns, once per schema, with IO.warn/1 while staging. It is the only construct in the vocabulary whose cost doubles with depth and the only one you can reach without meaning to. Rupa still starts nothing and never logs: this is the compiler's own way of saying "this is valid, and you may not have meant it".

Rupa.Gen generates both, and the round-trip property covers a recursive tagged union. An untagged one generates from a random variant, which round-trips only if the variants are disjoint — that is the cost tag: :none makes you opt into, and the docs say so.

bench/measure.exs now holds how every benchmark in that directory counts, so bench/decode.exs and bench/union.exs share one definition of words and reductions per op rather than two copies of it.

M5 — wire mapping. An object's fields no longer have to be spelled the way the wire spells them. rename_all: :camelCase | :snake_case | :kebab renames every field of the object that declares it, from: and to: override that for one field, and keys: :atom | :string chooses what the decoded map is keyed by. All four are spent at staging, so both backends read three finished names off the staged field and neither one ever looks at a case convention.

rename_all: reads a field name as words, so it works on a name written in any of the three rather than only on snake_case, and a run of capitals is one word — user_id and userID both read as ["user", "id"]. It applies to the object that declares it and not to the objects inside it; a whole tree in one style is a Rupa.Schema.walk/2 away, which is the kind of thing schemas-as-data is for.

One of from: and to: renames both directions. Give both, naming different keys, and you have said this field reads an old name and writes a new one — the one way to make encode stop being decode's inverse, and it takes saying so. Like default:, they belong on the field's own term; anywhere else is :misplaced_rename. Two fields landing on one wire key is :duplicate_wire_key at compile time rather than one of them quietly winning.

keys: is the decoded side, not the wire. It changes the key's type and never its name, so %{first_name: ...} under rename_all: :camelCase, keys: :string reads "firstName" and decodes to %{"first_name" => ...} — and encode reads back whichever key it wrote. No atom is ever interned from wire data on any path, before or after renaming, and test/rupa/codegen_test.exs reads the generated AST to say so.

Rupa.T.partial/1 carries from: and to: out to the optional it adds, the same way it already leaves a defaulted field alone, so wrapping a field does not bury its wire key.

M4b — generators. Rupa.Gen.stream/1 turns a schema, a codec or a generated module into a StreamData generator of decoded values, and test/rupa/gen_test.exs runs the property it exists for — encode it, decode that, get the value back — a thousand times per type against both backends. stream_data is an optional dependency: Rupa.Gen compiles when it is there and does not exist when it is not, so nobody who only wants to decode pays for it.

It refuses rather than skips. A pattern:, a multiple_of: it cannot hit exactly, a bound nothing satisfies, or a recursion with no case that stops each raise with the path at the moment the generator is built. A property test that quietly ignores half your schema is worse than one that will not start.

M4a — encode. Rupa.encode/3 and Rupa.encode!/3, on both backends, from the same IR. Inverse means this precisely: encode a decoded value, decode it again, and you get the value back. It is deliberately not the identity on the wire — a default that was absent comes back materialised, which is the point of a default.

What encode checks is types and formats, because it has to look at those anyway to turn a DateTime back into a string and an atom back into its wire value. Constraints are not re-run; decoding already bought them. Failures are %Rupa.Error{} with a path, the same as decoding, and Rupa.EncodeError is its own exception — a decode error is the outside world being wrong, an encode error is your own code being wrong about a value it built.

Every format has an encode side, including a duration encoder written here rather than handed to Duration.to_iso8601/1: the stdlib will emit a negative duration, which RFC 3339 has no syntax for and Rupa's parser therefore rejects, so a round trip through the stdlib would not be one. Sub-second precision survives — PT1.500S comes back PT1.500S.

M3 — the module backend. Rupa.compile(schema, as: MyApp.Codecs.User) generates and loads a module from the same IR the closure tree is built from, and Rupa.decode/3 takes the name. Object fields are matched in a head, guard-safe checks in a guard, and the result built as a map literal, so a field that is present and valid allocates nothing: 48 words/op against hand-written's 42. A recursive ref is a direct call, so the one table lookup the closure backend does goes away, and a compiled pattern is embedded as a literal rather than kept in :persistent_term — the module is built at runtime by the OTP about to run it, so the version skew that would make that unsafe cannot happen.

Naming a codec twice is a lookup, on a hash of the schema the module carries. Naming it with a different schema is refused rather than swapping the codec under code already using it; force: true replaces it with :code.soft_purge/1, and a process still running the old codec refuses the replacement instead of being killed. Compiles are serialised per name with :global.trans/2, so Rupa still has nothing to start and nothing in your supervision tree.

Every decode test runs on both backends and asserts they agree, so a feature cannot land on one and not the other.

M2 — the staging pass, and the closure backend over it. Rupa.compile/1 validates a schema, stages it into Rupa.IR, and builds a decoder. Rupa.decode/3 runs it, Rupa.decode!/3 raises, Rupa.valid?/2 is the yes/no. Scalars with their constraints and all ten formats, objects with required, optional and default fields, lists, tuples, map_of, nullable, enum, literal, and the unknown-key policy. Unions are M6, wire renaming is M5, and both say so at compile time rather than being quietly ignored.

Refs are resolved at staging. A ref that is not on a cycle is replaced by the definition itself, so the decoder never looks anything up; only genuine recursion stays a node.

Errors are a list whatever happens. on_error: is :halt by default and stops at the first problem; :collect reports every field. Paths are built on the way back up, so a successful decode allocates nothing for them.

Rupa.explain/1 prints the staged program. It reads the IR, not a backend, so it will say the same thing when the module backend lands.

A decode budget, bench/BUDGET.md, and mix run bench/decode.exs to measure against it — no benchmarking dependency, because the numbers that matter are words and reductions per op.

M1 — the schema vocabulary. Rupa.T builds schema terms and nothing else: {kind, opts} for scalars, {kind, payload, opts} for everything that holds a schema. A bare map is an object, and options come back sorted, so two spellings of one schema are one term and hash the same. Rupa.Schema.validate/1 is the only judge — structure, options, refs, and no function anywhere in the tree — and reports every problem at once as %Rupa.Error{} with a path. Rupa.Schema.walk/2 rewrites a schema, children first. T.pick/2, T.omit/2, T.partial/1 and T.merge/2 are honest map work on the field map.

Present, absent and null are three states. A field is required unless it is wrapped in T.optional/2 or carries default:. optional is about the key and decodes to no key at all, never to nil; nullable is about the value and decodes to nil; default: fires on absent only, and never replaces an explicit null.

M0 — skeleton and gates. No library code. mix.exs on an Elixir 1.18 / OTP 27 floor, mix check.all, Credo strict, ExCoveralls at 100%, and a CI workflow that runs the gate on the pinned pair and compiles and tests the floor beside it.