The schema term: what it is, how to check one, and how to rewrite one.

A schema is a tuple, {kind, opts} or {kind, payload, opts}, built by Rupa.T. Nothing in it is a function, so a schema prints, compares, hashes with :erlang.phash2/1, and embeds in generated code as a literal. validate/1 is the only thing that judges a schema; the constructors themselves hand back whatever you gave them.

Present, absent, null

Three states, kept apart on purpose.

• A field is required unless its term is wrapped in Rupa.T.optional/2 or carries default:. A required key must be present and must not be null.
• Rupa.T.optional/2 says the key may be absent. Absent decodes to the key simply not being in the map — not to nil.
• Rupa.T.nullable/2 says the value may be JSON null, which decodes to nil. It says nothing about the key being absent.
• default: fires on absent only. An explicit null is never replaced by a default; it is either allowed, by nullable, or an error.

So T.optional(T.nullable(T.string())) is the field that may be missing, may be null, and is otherwise a string — and decoding tells you which of the three you got.

Field names

A field's name is an atom or a string, and an object's names are all of one or all of the other — mixing them is :mixed_field_names, because it would make the decoded map's shape depend on which field you were looking at.

Write atoms when you know the fields as you write the code, which is most of the time. Strings are for an object whose field names you did not choose — one that came out of Rupa.JsonSchema.decode/1, say — and they are what makes that path total: nothing is interned from a document that arrived over the wire.

Names on the wire

A field's wire key is a string, and by default it is the name spelled out. Four options move that apart, all of them settled at compile time.

• rename_all: is an object option — :camelCase, :snake_case or :kebab. It reads each field name as words and writes them back in that style, both directions, so %{first_name: ...} with rename_all: :camelCase reads and writes "firstName". It applies to that object and not to the objects inside it; walk/2 is how you apply one to a whole tree.
• from: and to: override it for one field: from: is the key the value arrives under, to: the key it leaves under. Give one and the other follows it, so a field renamed by hand still round-trips; give both, naming different keys, and you have said that this field reads an old name and writes a new one — the one way to make Rupa.encode/3 stop being Rupa.decode/3's inverse, which is exactly what a migration wants. Like default:, they belong on the field's own term — the node in the object's field map, Rupa.T.optional/2 included — and anywhere else is :misplaced_rename.
• keys: is the object option for the other side: :atom or :string, deciding the type of the key the decoded map holds. It changes the key's type, never its name, so it stays out of the wire's way — and encoding reads back whichever it wrote. It defaults to the type of the name you wrote, so an atom-named object decodes to atom keys and a string-named one to string keys, and neither default interns anything.

Renaming never interns an atom from wire data: the atoms are the field names, and they exist before any data does. keys: :atom on a string-named object is the one place a name becomes an atom, and it is a name in a schema rather than a key off a document — the same rule every other atom in a schema already follows. Two fields that land on one wire key are refused at compile time rather than one of them quietly winning.

Structs

into: on an object names a struct module to decode into. It is an option on the object, not on the compile, so nesting works: 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 and embeds as a literal; what it adds is a soft dependency on that module, which Rupa.compile/2 checks — the module must be loaded and must already have every key the object decodes to, or you get a schema error rather than a surprise at decode time. mix rupa.gen.struct writes those modules from the schema.

A struct has atom keys and every one of them always, which rules three things out. keys: must resolve to :atom, so keys: :string is refused and a string-named object needs the explicit keys: :atom that interning already makes you ask for. unknown: :keep is refused, because a struct has nowhere to put the keys it would carry. And Rupa.T.optional/2 keeps working but stops meaning three things: 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 — which is what keeps the round trip closing. For a struct mix rupa.gen.struct wrote, that 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 something else is what stands for absent, and nil is a value like any other.

Paths

Errors from validate/1 carry a path through the schema:

• an atom is an object field, or a defs: entry after the :defs segment
• :of is a list's element type or a map_of's value type
• an integer is a position in a tuple or a variant of a union
• a string is a branch of a tagged union, or a field of a string-named object