@spec datamodel(t()) :: %{
  declared: MapSet.t(String.t()),
  sensitive: MapSet.t(String.t())
}

Both projections in one map, so a host that has a document supplies one input to a sensitive-path pass rather than two.

Nothing in this package calls it; it is the derivation the record promised, at the shape a pass that would consume it already takes.

@spec declared?(t(), term()) :: boolean()

Whether the document declares path.

A false here is this document does not declare it, which is the input to an advisory and to nothing that refuses anything.

@spec declared_paths(t()) :: MapSet.t(String.t())

ADR-0001 decision 7's projection: every entry's own path, at every nesting depth, and nothing else.

An object entry contributes its own path and, recursively, its fields'. A list entry contributes its own path alone - item_type names an element type and no record decides an index syntax, so there is no element path to contribute.

iex> alias StatifierDatamodel.Index
iex> %{"scopes" => [%{"scope" => "local", "entries" => [
...>   %{"path" => "risk_reasons", "type" => "list", "item_type" => "string"},
...>   %{"path" => "card", "type" => "object", "fields" => [%{"path" => "card.brand"}]}]}]}
...> |> Index.index()
...> |> Index.declared_paths()
MapSet.new(["card", "card.brand", "risk_reasons"])

@spec entries(t()) :: [entry()]

Every entry, in document order.

@spec fetch(t(), term()) :: {:ok, entry()} | :error

The entry declared at path.

iex> alias StatifierDatamodel.Index
iex> index = Index.index(%{"scopes" => [
...>   %{"scope" => "local", "entries" => [%{"path" => "amount_cents", "type" => "integer"}]}]})
iex> {:ok, entry} = Index.fetch(index, "amount_cents")
iex> entry.type
:integer
iex> Index.fetch(index, "amount_dollars")
:error

@spec index(term()) :: t() | nil

Admits a decoded datamodel document and indexes it, or returns nil.

Total: every input has an answer and none of them raise. A map carrying a list under "scopes" is a document; anything else - a set, a list of paths, a bare map, a number - is not one, and gets nil rather than an empty index, so not a document stays distinguishable from a document declaring nothing.

iex> alias StatifierDatamodel.Index
iex> index = Index.index(%{"version" => 1, "scopes" => [
...>   %{"scope" => "local", "entries" => [
...>     %{"name" => "card", "path" => "card", "type" => "object", "label" => "Card",
...>       "fields" => [
...>         %{"name" => "brand", "path" => "card.brand", "type" => "string",
...>           "label" => "Brand"}]}]}]})
iex> index.order
["card", "card.brand"]
iex> Index.type(index, "card.brand")
:string

iex> StatifierDatamodel.Index.index(["card.brand"])
nil

@spec path_types(t() | term()) :: %{optional(String.t()) => value_kind()}

ADR-0001 decision 11's projection: path -> value kind, in the expression language's own vocabulary.

Total, over anything: nil and a value that is not an index project to the empty map, on the same reasoning index/1 returns nil for an input it cannot admit.

Per entry, in the record's order:

• a drawable one_of wins over the kind and gives {:one_of, values}. Drawable means every value can be rendered as a choice - a string, a number or a boolean. A one_of that is empty, or that holds anything else, is not drawn and the entry falls back to its kind. The enumeration winning is decision 11's word and is not qualified by the entry's type, so an object carrying a drawable one_of is present with its values, where the same entry without one would be absent.

• string is :string; integer and decimal are both :number; boolean is :boolean; date, datetime and duration are themselves.

• a list whose item_type is one of those is {:list, kind}.

• object, a list with no usable item_type, and an entry whose type is outside the closed set are absent from the map. Absence means unknown, not wrong.

  iex> alias StatifierDatamodel.Index iex> %{"scopes" => [%{"scope" => "local", "entries" => [ ...> %{"path" => "amount_cents", "type" => "integer"}, ...> %{"path" => "risk_reasons", "type" => "list", "item_type" => "string"}, ...> %{"path" => "card", "type" => "object", "fields" => [ ...> %{"path" => "card.brand", "type" => "string", ...> "one_of" => ["visa", "mastercard", "amex"]}]}]}]} ...> |> Index.index() ...> |> Index.path_types() %{ "amount_cents" => :number, "risk_reasons" => {:list, :string}, "card.brand" => {:one_of, ["visa", "mastercard", "amex"]} }

  iex> StatifierDatamodel.Index.path_types(nil) %{}

@spec sensitive_paths(t()) :: MapSet.t(String.t())

The declared paths the document annotates sensitive?: true.

Read per entry and literally: an object marked sensitive does not stamp its fields. See the moduledoc for why that is a matcher's job rather than this one's.

iex> alias StatifierDatamodel.Index
iex> %{"scopes" => [%{"scope" => "local", "entries" => [
...>   %{"path" => "card.token_id", "type" => "string"},
...>   %{"path" => "card.number", "type" => "string", "sensitive?" => true}]}]}
...> |> Index.index()
...> |> Index.sensitive_paths()
MapSet.new(["card.number"])

@spec type(t(), term()) :: type() | nil

The declared type of path, or nil when the document does not declare it - unknown, never wrong (decision 12).

nil is also what a declared entry whose type is outside the closed set gets, for the same reason: this module reports what it can name and claims nothing about the rest.

@spec under(t(), term()) :: [entry()]

Every entry strictly under prefix, at any depth, in document order - the completion query.

The entry at prefix itself is not among them; fetch/2 is how a caller asks about the prefix. A caller wanting one level only filters the result on depth.

iex> alias StatifierDatamodel.Index
iex> index = Index.index(%{"scopes" => [%{"scope" => "local", "entries" => [
...>   %{"path" => "card", "type" => "object", "fields" => [
...>     %{"path" => "card.brand"}, %{"path" => "card.last4"}]},
...>   %{"path" => "cardholder"}]}]})
iex> index |> Index.under("card") |> Enum.map(& &1.path)
["card.brand", "card.last4"]