fig-schema 0.5.0

A generic, prov-agnostic schema layer over fig's value tree: field types, controlled vocabularies, and a reusable rule-matching engine.
Documentation

fig-schema

The schema layer over fig's value tree: what a field expects — its type, its allowed values, and how to present it.

fig parses bytes into a fig::Value and edits losslessly; it has no notion of "what is valid here". This crate adds that knowledge as a generic, embedder-agnostic engine. It never learns the word "prov" or "flower": a consumer defines its own constraint type and implements Validate on it, and FieldRule/Schema are generic over that type — so the path-matching and commit-time validation plumbing is written once, here, and reused everywhere.

A schema is also a document. Written to the schema document format — a fig document in any of fig's languages, composed from others by include and from shared vocabulary documents by constraint.from — it is loaded by load_schema, checked against by the fig-schema binary, and mapped by an embedder into its own constraint type.

What lives here

Type Role
PathPat / SegPat Match a fig path, including every item of a list (EachItem) and whole subtrees (AnyDepth); PathPat::parse reads the format's grammar (audience[], meta.**)
FieldType The expected type: coercion of an edit buffer into it (FieldType::coerce), whether a parsed value already has it (FieldType::admits), and its name in the format (FieldType::from_name)
Term / Cardinality / validate_enum A controlled vocabulary and the logic to check a value against one
Validation / Issue / IssueKind Why a value failed, as data rather than prose — or that it was not checked at all (IssueKind::Unchecked)
Schema::check / Verdict A whole document against the schema: every node's shape against its rule's type, and its value against the rule's constraint
Presentation / Icon / Tint Renderer-neutral display hints, carried but never interpreted
Consequence / Severity What changing a field costs, so a host can warn before an expensive or irreversible edit
lint_vocabulary / Finding Judge a vocabulary document rather than read it — what it declares that nothing acts on
load_schema / Constraint / Origin A Schema read from a schema document, every rule saying which document and entry it came from; Constraint is the crate's own — a vocabulary, or an Other kind it cannot check

The constraint seam is still the embedder's. Constraint exists so that a document can be loaded with no embedder behind it; an embedder maps a loaded Schema<Constraint> into a schema over its own type with Schema::map_constraints, reading the Other kinds it knows — a reference into a workspace, a range, a pattern — and keeping the rest as its own unchecked variant.

Example

use fig::Value;
use fig_schema::{
    Consequence, FieldRule, FieldType, PathPat, Presentation, Schema, Seg, Severity,
    Term, Validate, Validation, validate_enum,
};

// The embedder's own constraint type — the seam this crate is built around.
struct Vocabulary { values: Vec<Term>, closed: bool }

impl Validate for Vocabulary {
    fn validate(&self, value: &Value) -> Validation {
        validate_enum(&self.values, self.closed, value)
    }
}

let schema = Schema::new(vec![
    FieldRule::new(PathPat::each_item_of("audience"))
        .ty(FieldType::Str)
        .constraint(Vocabulary {
            values: vec![Term::value("public"), Term::value("family")],
            closed: true,
        })
        .present(Presentation::default().title("Audience"))
        .on_change(
            Consequence::when("public", "Anyone with the link will be able to read this.")
                .severity(Severity::Confirm),
        ),
]);

let path = [Seg::Key("audience".into()), Seg::Index(0)];
let rule = schema.rule_for(&path).expect("a rule governs this path");

assert!(rule.validate(&Value::Str("public".into())).is_ok());

let rejected = rule.validate(&Value::Str("familly".into()));
assert!(rejected.is_reject());
assert_eq!(rejected.issue().unwrap().suggestion.as_deref(), Some("family"));

// Valid, but not free — ask before committing it.
assert_eq!(rule.severity_of(&Value::Str("public".into())), Some(Severity::Confirm));
assert_eq!(rule.severity_of(&Value::Str("family".into())), None);

The command line

cargo install fig-schema
fig-schema check notes/*.md
fig-schema explain note.md audience[1]
fig-schema complete --bare note.md audience[0]
fig-schema lint .fig-schema.figl

Installed on PATH it is also fig schema <command>: fig hands an action it has no verb for to a fig-<action> program, passing every argument through untouched, so the two compose with no registration step anywhere.

check answers whether a document is valid, which fig check does not — that answers whether it parses. Every governed node is checked twice, its shape against its rule's type and its value against the rule's constraint, and the report has three headings: errors (a rejection, a type mismatch), notes (a warning — a retired term, an open vocabulary's near miss), and unchecked (a rule of a constraint kind this binary does not know). It exits 0 when every file is valid, 1 when a file has an error, 2 when the command line is wrong, and 3 when nothing is invalid and not everything was checked — non-zero so a CI gate fails closed, distinct so a script can accept it deliberately. There is no --allow-unchecked; against a schema carrying reference constraints, prov's check is the tool that knows them, and exit 3 is how this one says so.

The schema is found in exactly two ways. --schema <file>, repeatable in precedence order, is the whole schema when given. Otherwise the nearest .fig-schema.<ext> or .config/fig-schema.<ext>, walking up from the document's directory — one file, never a merge of every file on the way up, so a person reading it sees the whole precedence. Discovery order is rule precedence: Schema::rule_for returns the first match.

explain answers "what governs this path": the value there and what its rule makes of it, the rule in full with the document and entry it was read from, and every later rule it shadows — the precedence include order decided, made visible. complete answers "what may I put here": a vocabulary's terms with labels, descriptions and the consequence choosing one would carry, live first and retired last; --bare is the shape a shell completer consumes, and never offers a retired term. Both exit 0 whenever the question was answered, "nothing governs this" included.

lint reads a schema or vocabulary document, follows its includes, and reports what it declares that nothing acts on. The finding it exists for is values: cloesd, which loads as an open vocabulary that forbids nothing. Errors change what validation does; notes change only what a reader sees, and --strict fails on those too.

Two limits worth knowing, both inherited rather than chosen:

  • Findings carry a path, not a line and column. fig hands back a value tree with no per-node spans, so nothing downstream of a parse knows which line a key came from. audience[1] is the most any consumer of the parse can say.
  • It reads fewer formats than fig check does. json, jsonc, json5, yaml, toml, zon and figl, plus a markdown file's frontmatter or endmatter block. fig's own check also takes ini, dotenv, properties, plist and nestedtext: fig's core carries no language until a program registers one, and this binary registers the ones it names. fig convert moves a document into one of them.

Design notes

Rule precedence is declaration order. Schema::rule_for returns the first matching rule, so list a specific rule before a broader one that would also match. Schema::rules_for returns every match in that order — the winner first, then what it shadows — so a tool can show the precedence rather than leave it inferred.

A check never reports a missing field. A FieldRule says what a value must be if there is one, and nothing says there must be one, so an empty document is valid. Nor does it report a node no rule governs: a schema governs what it names, and a check that fires on correct documents is one people stop running.

A type names the item, and a list of items has the type too. str admits public and [public, family] alike, one level deep, because a field is declared once and written as a scalar or a list as the document pleases. A date also admits a string shaped like one, since YAML, JSON and markdown frontmatter have no date literal and every document in them would otherwise fail its own schema.

A validator fails closed; a presenter fails open. The one rule that keeps the constraint seam intact across the document boundary. Anything the loader cannot read as a rule at all — an unknown type, an unknown spec, a missing at — is a LoadError, never a rule quietly weaker than the one written. Anything that changes only what a reader sees — a key nothing reads, a tint nothing maps — loads without it and is a Finding.

Unchecked is not wrong. A constraint of a kind a validator does not know fails closed — Validation::Reject carrying IssueKind::Unchecked(kind) — so an editor that does not look further will not commit the value. A reader that does look can tell unchecked from invalid, and Verdict::is_unchecked is that look.

Retired terms warn, they don't reject. A Term marked retired is still a known value — it is merely no longer offered in a picker. A document that already holds one stays committable, even under a closed vocabulary.

Validation failures are structured. Issue carries the offending value, the kind of failure, and a near-miss suggestion when one exists. Display renders a reasonable English default; a frontend that wants to localize the text, or offer the suggestion as a one-tap correction, has the parts it needs.

A consequence names a destination, not a transition. Consequence::when matches the value being landed. This crate holds no current value, so it cannot see a change from anything — which also means asking about a value the field already holds answers the same as asking about a fresh one. Suppressing that no-op, and deciding what a deleted field resolves to, are the host's, and the host is the side that knows.

Costs and tints are different facts. A Tint says how loudly to draw a field; a Consequence says what happens if the user goes through with the change. A field can be drawn calmly and still be expensive, or drawn in red and cost nothing.

Coercion falls back to text. FieldType::coerce never destroys an edit: a value that doesn't fit the declared type becomes a Value::Str, leaving the caller's own reparse as the final backstop.

Licence

Licensed under either of Apache License, Version 2.0 or MIT license at your option.