Visualize.Data.Schema (Visualize v0.5.1)

A feed's schema: what each of its fields means (spec/08 §10.1, D-136).

A schema maps a field — named as the feed's rows name it, an atom or a string — to a description: its type, and as much of unit, quantity, label, order, status, polarity, target, continuity, window, metric_kind and bounds as the feed knows. It says what the numbers are, whoever draws them, and never how they are drawn: a description has no colour key, since colour is the theme's to choose from the meaning (#533). A :time field holds instants; a feed whose clock is a number describes it :number and window: true, the field its windows are over (D-154). A numeric field may say how it was measured, metric_kind: :gauge | :counter | :rate, which refines what its quantity's additivity allows, and where its values lie, bounds: [min, max], a display hint over its quantity's (D-155). A unit is a UCUM code Visualize.Unit reads and a quantity one of Visualize.Quantity.all/0, and when both are given the unit measures the quantity (D-157).

A schema is identified by its version, a content hash (spec/08 §10.2): the same schema has the same version on every node and under every release, and any change of content is a new version. A Visualize.Data.Delivery names the version its rows were produced under; Visualize.Data.Schema.Cache holds schemas by {feed, version}. Schemas of different versions may still describe the same data in different words, and compatibility/2 says when one's rows read as the other's (D-159).

Examples

iex> {:ok, schema} =
...>   Visualize.Data.Schema.new(%{
...>     t: %{type: :time},
...>     latency: %{type: :number, unit: "s", quantity: :duration, label: "Request time"},
...>     state: %{type: :category, order: ["ok", "warn", "fail"],
...>              status: %{"ok" => :good, "warn" => :warning, "fail" => :bad}}
...>   })
iex> Visualize.Data.Schema.fetch(schema, "latency", :unit)
{:ok, "s"}
iex> String.length(Visualize.Data.Schema.version(schema))
64
iex> Visualize.Data.Schema.new(%{state: %{type: :category, colors: %{"ok" => "#0a0"}}})
{:error, [{[:state, :colors], {:colour_key, :colors}}]}

Summary

Types

description()

What one field means (spec/08 §10.1).

error()

A fault of new/1: the path from the schema to the value, and why.

incompatibility()

Why a field of one schema cannot read another's rows (spec/08 §10.1, D-159).

name()

A field name, as the feed's rows spell it.

t()

Functions

attributes()

The twelve description keys, :type first (spec/08 §10.1).

compatibility(schema, other)

Whether other's rows read as schema's (spec/08 §10.1, D-159): for each field of schema, other has a field of the same name compared as strings, of the same type, and for a :number field a unit that converts into schema's — two absent units agree, one absent facing a present one does not. {:error, faults} lists every fault, field spelt as schema spells it, ordered by its name as a string. Labels and facts are not compared, and other's extra fields are not faults.

fetch(schema, name)

A field's description, by either spelling of its name (spec/08 §6.2).

fetch(schema, name, key)

One attribute of a field's description; :error when the field or the attribute is absent.

format_error(arg)

One fault of new/1 as a line a person reads.

new(fields)

The schema of a map of field descriptions, or every fault of it by path (spec/08 §10.1).

new!(fields)

The schema of a map of field descriptions, or ArgumentError naming every fault.

version(schema)

The schema's version: the SHA-256 of its canonical encoding as 64 lowercase hex digits (spec/08 §10.2), computed once by new/1.