Macaw.Data.Schema (macaw_data v0.5.3)

A source's schema: what each of its fields means (spec/01 §1.2).

A schema maps a field, named as the source's rows name it (an atom or a string), to a description: its type (:time, :number, :category, :text, :color or :point, a geographic position), and as much of unit, quantity, label, order, status, polarity, target, continuity, window, metric_kind, bounds and identity as the source knows, and for a :category field the values it takes, every one. It says what the numbers are, whoever draws them, and never how they are drawn: a description has no color key, since color is the theme's to choose from the meaning. A declared value may be an entry, %{value: v, name: "Display", color: c}, whose color is a data color, a literal (spec/01 §1.7).

A unit is a UCUM code Macaw.Data.Unit reads and a quantity one of Macaw.Data.Quantity.all/0, and when both are given the unit measures the quantity (spec/01 §1.6). A field whose value names the thing a row is about says identity: true, several such fields together naming it (spec/01 §1.4). The window field is window_field/1's (spec/01 §1.5).

A schema is identified by its version: the kernel's digest of its map form (Macaw.Layers.Document.digest/1, spec/01 §1.10), the same on every node and under every release, and new with any change of content. Names, states and roles count by their spelling, so :latency and "latency" are one field of one version, as they are after a trip through JSON. A Macaw.Data.Delivery names the version its rows were produced under; Macaw.Data.Schema.Cache holds schemas by {source, version}. compatibility/2 says when one schema's rows read as another's (spec/01 §1.9). to_json/1 and from_json/2 are its public JSON form (spec/01 §1.11).

Ported from visualize's Visualize.Data.Schema, with the :point type, literal data colors, the window field, the kernel's digest and a public JSON form.

Examples

iex> {:ok, schema} =
...>   Macaw.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> Macaw.Data.Schema.fetch(schema, "latency", :unit)
{:ok, "s"}
iex> String.length(Macaw.Data.Schema.version(schema))
64
iex> Macaw.Data.Schema.new(%{state: %{type: :category, colors: %{"ok" => "#0a0"}}})
{:error, [{[:state, :colors], {:color_key, :colors}}]}

Summary

Types

description()

What one field means (spec/01 §1.2).

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/01 §1.2, visualize D-159).

name()

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

t()

value()

A category field's value: a string, an atom or a number.

value_entry()

A declared value with what a person reads of it (spec/01 §1.2, visualize D-224): its display name, and a color hint, a data color: a literal (spec/01 §1.7).

Functions

attributes()

The fourteen description keys, :type first (spec/01 §1.2).

color?(name)

Whether a value is a data color as a schema holds one (spec/01 §1.7): a literal, #rgb, #rgba, #rrggbb or #rrggbbaa in hexadecimal, or a CSS named color. A theme role or a typed color is a drawing color, which a schema never names.

compatibility(schema, other)

Whether other's rows read as schema's (spec/01 §1.2, visualize 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 spelled 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 — except identity (visualize D-167): a field one schema declares identity: true and the other does not is {:identity, a, b}, a and b whether each declares it, even a field only other has, since other's rows read as schema's would merge the things other tells apart.

entry_keys()

A value entry's three keys, :value first (spec/01 §1.3): what a codec reads an entry's keys as, never making an atom of another. Public, so a host that encodes schemas itself (metresis) reads it rather than a hidden function.

fetch(schema, name)

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

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.

from_json(json, opts \\ [])

The schema a JSON document holds: read through the kernel's limits and scan first (Macaw.Layers.Limits, Macaw.Layers.Scan), so a document over a limit is refused before it is decoded, then decoded and read by from_map/1. limits: tightens them.

from_map(pairs)

The schema a map form holds (spec/01 §1.11): new/1 of what it reads. Each word is read through its own closed vocabulary and every name, state and role is a string, so no atom is made. A key no description or value entry has stays its string, for new/1 to refuse by name.

identity(schema)

The fields the schema declares identity: true, as it spells them, ordered by name as a string; [] when it declares none (spec/01 §1.2, visualize D-167).

identity(schema, row)

A row's identity under the schema (spec/01 §1.2, visualize D-167): the bare value of the one identity field, a map from field to value, keyed as the schema spells them, for several, and nil when the schema declares none or the row has no value for one of them. Each field is read by either spelling of its name.

new(fields)

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

new!(fields)

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

to_json(schema)

The schema's JSON form: to_map/1, encoded.

to_map(schema)

The schema's map form (spec/01 §1.11): the JSON-ready list of [name, description] pairs, sorted by name, every name, state and role written by its spelling, every word of the vocabulary (type, quantity, polarity, metric_kind) as its string.

value_colors(schema, field)

A map from each declared value with a color to its color, as written, a literal (spec/01 §1.3); %{} when none has one, or the field declares no values. A drawing library may use it as a color map; a design's own colors outrank it.

value_names(schema, field)

A map from each declared value with a name to its name (spec/01 §1.2, visualize D-224); %{} when none has one, or the field declares no values.

values(schema, field)

A field's declared values, bare, in their declared order (spec/01 §1.2, visualize D-224): each value entry's value, and each bare value as it is. nil when the schema has no such field or the field declares no values — an open set, where [] would say a closed one holding nothing. Read by either spelling of the field's name.

version(schema)

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

window_field(schema)

The schema's window field (spec/01 §1.5): the field a request's window applies to, by which rows are ordered, trimmed and routed. It is the field described window: true, else the schema's one :time field when it does not say window: false; nil when there is neither, and a schema with several :time fields and none marked has none.

window_kind(schema)

The window that applies to the schema's window field (spec/01 §1.5): :range over a :time or a :number field, from one instant or value to another; :box over a :point field, a region of positions; nil when the schema has no window field.