ADR-0004 decision 7: whether a value conforms to a type expression.

conforms/3 is given the declarations, a type expression and a value - a payload a host decoded from JSON or built in Elixir - and answers :ok, or {:error, mismatches} naming every place the value does not conform. It checks against a declared record, a declared shape or an inline shape alike: a payload is checked against what its event declares it carries.

StatifierDatamodel.Types.satisfies/3 decides a type against a type, and StatifierDatamodel.Coverage.missing/3 decides which required fields of a shape a map leaves unfilled. This module is the third question beside them, a value against a type, and neither of the other two changes any answer it gives.

A mismatch: a path and a reason

Each mismatch is {path, reason}. path is a list of segments, a string for a field name and an integer for a list index; the value itself is at []. reason is one of two:

• :missing - a required field is absent or nil, which is StatifierDatamodel.Coverage.missing/3's fill rule;
• {:expected, type} - the value at path does not conform to type, the type expression it failed.

Mismatches come in the type's field order, depth first, and a list's items in index order.

What each type accepts

A Decimal struct is recognised by its module name; the package takes no dependency on it. The string spellings of :decimal and :duration are ADR-0001 decision 4's, accepted beside the ones a decoded JSON value spells. Decision 4 says a decimal "is a string" and states no grammar for it, so any string conforms. An expression-language duration string is one or more <digits>(.<digits>)?<unit> pairs, the unit one of y, mo, w, d, h, m, s and ms, with no whitespace and no sign, and a fraction that comes to a whole number of milliseconds (30s, 1h30m, 1.5s): the rule the expression language's own duration parse applies to a whole string, followed here without depending on it.

A NaiveDateTime carries no offset and does not conform to :datetime, and neither does a date-time string without one. A field whose type, or a list field whose item_type, named nothing the document declares is read as unknown, as an undeclared name is everywhere in this package.

A record, a shape or an inline shape

The value must be a map, read with the strings the declaration spells, as StatifierDatamodel.Coverage.missing/3 reads one: a key spelled as an atom is not the field's key. Then each field, in the type's order:

• absent or nil - a :missing mismatch when the field is required, and nothing when it is optional;
• present - checked against the field's type, and a list field's items against its item_type, with the field's name, and an item's index, added to the path.

A key the type does not name is ignored, because every object is open, and a field's one_of is a hint and is not checked. A record and a shape are checked the same way: the difference between them is what the read check decides, not what a value carries.

Every answer is a fact. Nothing raises, nothing is enforced at run time, and whether a mismatch stops a host's pipeline is the host's to decide (ADR-0001 decision 12).