tmux_schema (libtmux for Erlang v0.0.1)

View Source

Validate schema-defined observations and normalize scalar values.

Field names come from the generated registry, never record reflection or payload-created atoms. Text is validated UTF-8; byte fields preserve arbitrary binaries. Integer normalization uses the shared exact JSON integer range. tmux_model validates rows and tmux_filter validates criteria through this schema. The field reference lists fields and relationships.

Summary

Types

The built-in tmux graph entities; window_link represents a session membership.

Structured boundary validation errors with a code and input path.

Generated field contract. stable is a versioned portable identity; wire is the JSON key. required controls construction and nullable permits known absence. format is present only for directly observed tmux fields; derived fields omit it. capture_codec identifies an admitted batched source encoding; its absence selects isolated reads for that entity. minimum tightens an integer field's lower bound. Field names themselves are the keys returned by fields/1, not this map's wire or stable values.

Validated scalar operators. The field's type and nullability restrict this set.

Generated relationship contract: kind is one or many; target names the related entity. wire and stable have the same roles as in field_metadata/0. Completeness belongs to snapshot coverage, not this static schema.

Scalar categories used by normalization and operator validation; IDs remain binaries.

Functions

Look up one permitted field by its Erlang atom name. Unknown names return a tagged error; this does not turn input strings into atoms.

Return generated field metadata for a known entity, or a tagged unknown_entity error. Field names, wire names and stable IDs are allowlisted; this is not reflection over arbitrary record fields.

Validate a domain-field map and normalize its scalar observations, retaining not_loaded/unavailable distinctly and deriving schema-defined values. Performs no I/O; constructors and action boundaries still validate records.

Return the permitted scalar operators for this field type and nullability. The generated field reference uses this same validator. Performs no I/O.

Return generated relationship metadata, including target entities and one/many cardinality. Performs no I/O.

Validate and normalize one value against generated field metadata. Integral JSON numbers obey the exact shared integer range and field bounds; text is validated UTF-8, while bytes remain arbitrary binaries. Performs no I/O.

Types

entity()

-type entity() :: session | window | window_link | pane.

The built-in tmux graph entities; window_link represents a session membership.

error_detail()

-type error_detail() :: #{code := atom(), path := [term()], atom() => term()}.

Structured boundary validation errors with a code and input path.

field_metadata()

-type field_metadata() ::
          #{type := value_type(),
            wire := binary(),
            stable := binary(),
            required := boolean(),
            nullable := boolean(),
            format => binary(),
            capture_codec => escaped_columns_v1,
            minimum => integer()}.

Generated field contract. stable is a versioned portable identity; wire is the JSON key. required controls construction and nullable permits known absence. format is present only for directly observed tmux fields; derived fields omit it. capture_codec identifies an admitted batched source encoding; its absence selects isolated reads for that entity. minimum tightens an integer field's lower bound. Field names themselves are the keys returned by fields/1, not this map's wire or stable values.

operator()

-type operator() ::
          equals | 'not' | in | not_in | lt | lte | gt | gte | contains | starts_with | ends_with |
          regex | present.

Validated scalar operators. The field's type and nullability restrict this set.

relation_metadata()

-type relation_metadata() ::
          #{kind := one | many, target := entity(), wire := binary(), stable := binary()}.

Generated relationship contract: kind is one or many; target names the related entity. wire and stable have the same roles as in field_metadata/0. Completeness belongs to snapshot coverage, not this static schema.

value_type()

-type value_type() :: session_id | window_id | pane_id | boolean | uint | integer | text | bytes.

Scalar categories used by normalization and operator validation; IDs remain binaries.

Functions

field(Entity, Field)

-spec field(entity(), atom()) -> {ok, field_metadata()} | {error, error_detail()}.

Look up one permitted field by its Erlang atom name. Unknown names return a tagged error; this does not turn input strings into atoms.

fields(Entity)

-spec fields(entity()) -> {ok, #{atom() => field_metadata()}} | {error, error_detail()}.

Return generated field metadata for a known entity, or a tagged unknown_entity error. Field names, wire names and stable IDs are allowlisted; this is not reflection over arbitrary record fields.

normalize/2

-spec normalize(entity(), map()) -> {ok, map()} | {error, error_detail()}.

Validate a domain-field map and normalize its scalar observations, retaining not_loaded/unavailable distinctly and deriving schema-defined values. Performs no I/O; constructors and action boundaries still validate records.

operators/1

-spec operators(#{type := value_type(), nullable := boolean(), atom() => term()}) -> [operator()].

Return the permitted scalar operators for this field type and nullability. The generated field reference uses this same validator. Performs no I/O.

relations(Entity)

-spec relations(entity()) -> {ok, #{atom() => relation_metadata()}} | {error, error_detail()}.

Return generated relationship metadata, including target entities and one/many cardinality. Performs no I/O.

value/2

-spec value(map(), term()) -> {ok, term()} | {error, error_detail()}.

Validate and normalize one value against generated field metadata. Integral JSON numbers obey the exact shared integer range and field bounds; text is validated UTF-8, while bytes remain arbitrary binaries. Performs no I/O.