One reason something was refused.

A finding is the unit every refusal in this package reports: a template that names a construct outside the template subset, and later a document whose vocabulary is not admitted. Refusals return a list of findings rather than the first one, so that an author fixing what they wrote learns everything wrong with it in a single pass.

The fields stay few, and one is added only where a host would otherwise have to read the :message to get at something it needs:

• :code - a stable, machine-readable reason. Hosts switch on it; it does not change when the wording does.
• :message - the human sentence, naming what was refused and, where the refusal has a place in some source text, where it appeared.
• :field - what the finding is about: the name of the refused construct for a template, the offending field for a document. nil when the refusal is about the input as a whole.
• :node_key - the key of the document node the finding belongs to, and always a string or nil. It is nil wherever there is no key a host can look a node up by: a template finding, because a template is compiled on its own without the document that carries it; a finding about the envelope, which is the document's and not any one node's; and a node whose key is absent or is not a string. A key of the wrong form is named in the message rather than carried here, because a host reads this field to find the node the author has to fix and a key that is not a string is not a name it can find one by.
• :position - where in some source text the refusal is, as %{line: line, column: column}, both one-based and counting bytes as the parser's own locations do. Three places in this package set it: the two template refusal clauses in Riddler.Template, and the document.invalid_template finding that re-reports a template refusal against the template a document node writes, which carries the position of the refusal it wraps. Every other finding leaves it nil - the document checks, a field refused for not being template source at all (which carries that same code, so the code alone does not say whether a span is there), and the response.* findings. Three of those nils are defects rather than decisions and are filed as such rather than explained here: document.invalid_condition and document.invalid_pattern (rd-ai1) and response.undecidable (rd-d9n). Where there is a position the :message names it too and goes on naming it, so that a person reading a finding reads one sentence; this field is the same fact in the form an editor can act on without parsing that sentence.

Examples

iex> finding = %Riddler.Finding{
...>   code: "template.tag_not_allowed",
...>   message: ~s[the tag "include" is not in the template subset (line 1, column 3)],
...>   field: "include",
...>   position: %{line: 1, column: 3}
...> }
iex> {finding.node_key, finding.position}
{nil, %{line: 1, column: 3}}