Schemaui

<div align="center"> <a href="https://signature4u.vercel.app/schemaui?font=satisfy&fontSize=153&speed=2.8&charSpacing=0&borderRadius=0&cardPadding=24&fill=multi&fill1=001bb7&fill2=ec4899&stroke=001bb7&stroke2=ec4899&strokeMode=multi&strokeEnabled=1&bg=transparent&bgMode=solid&bg2=1e3a8a&texture=cross&texColor=566486&texSize=30&texThickness=1&texOpacity=0.4&colors=001bb7-001bb7-001bb7-001bb7-001bb7-001bb7-ff8040-fcb53b&linkFillStroke=1" target="_blank"> <img src="https://signature4u.vercel.app/api/sign?text=schemaui&font=satisfy&fontSize=153&speed=2.8&charSpacing=0&borderRadius=0&cardPadding=24&fill=multi&fill1=001bb7&fill2=ec4899&stroke=001bb7&stroke2=ec4899&strokeMode=multi&strokeEnabled=1&bg=transparent&bgMode=solid&bg2=1e3a8a&texture=cross&texColor=566486&texSize=30&texThickness=1&texOpacity=0.4&colors=001bb7-001bb7-001bb7-001bb7-001bb7-001bb7-ff8040-fcb53b&linkFillStroke=1" align="center" alt="schemaui signature"/> </a> </div>

<!--  --> <div align="center"> <a href="https://asciinema.org/a/7IBbhRJAUBlIQaPWSrspEgZtE" target="_blank"> <img src="https://asciinema.org/a/7IBbhRJAUBlIQaPWSrspEgZtE.svg" width="500" /> </a>

English | 中文文档

</div>

schemaui turns JSON Schema documents into fully interactive terminal UIs powered by ratatui, crossterm, and jsonschema.

The library parses rich schemas (nested sections, $ref, arrays, key/value maps, pattern properties…) into a navigable form tree, renders it as a keyboard-first editor, and validates the result after every edit so users always see the full list of issues before saving.

<!-- AUTO-GENERATED:CLI-QUICKLINK:BEGIN -->

CLI available: schemaui-cli installs the schemaui binary. Prefer the CLI? Jump to CLI installation and usage.

<!-- AUTO-GENERATED:CLI-QUICKLINK:END -->

Feature Highlights

• Schema fidelity – draft-07 compatible, including $ref, definitions, patternProperties, enums, numeric ranges, and nested objects/arrays.
• Sections & overlays – top-level properties become root tabs, nested objects are flattened into sections, and complex nodes (composites, key/value collections, array entries) open dedicated overlays with their own validators.
• Immediate validation – every keystroke can trigger jsonschema::Validator, and all errors (field-scoped + global) are collected and displayed together.
• Pluggable I/O – io::input ingests JSON/YAML/TOML (feature-gated) while io::output can emit to stdout and/or multiple files in any enabled format.
• Batteries-included CLI – schemaui-cli offers the same pipeline as the library, including multi-destination output, stdin/inline specs, and aggregated diagnostics.
• Embedded Web UI – enabling the web feature bundles a browser UI and exposes helpers under schemaui::web::session so host applications can serve the experience without reimplementing the stack.

Quick Start

[dependencies]
schemaui = "0.7.1"
serde_json = "1"

use schemaui::prelude::*;
use serde_json::json;

fn main() -> color_eyre::Result<()> {
    color_eyre::install()?;
    let schema = json!({
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "Service Runtime",
        "type": "object",
        "properties": {
            "metadata": {
                "type": "object",
                "properties": {
                    "serviceName": {"type": "string"},
                    "environment": {
                        "type": "string",
                        "enum": ["dev", "staging", "prod"]
                    }
                },
                "required": ["serviceName"]
            },
            "runtime": {
                "type": "object",
                "properties": {
                    "http": {
                        "type": "object",
                        "properties": {
                            "host": {"type": "string", "default": "0.0.0.0"},
                            "port": {"type": "integer", "minimum": 1024, "maximum": 65535}
                        }
                    }
                }
            }
        },
        "required": ["metadata", "runtime"]
    });

    let options = UiOptions::default();
    let ui = SchemaUI::new(schema)
        .with_title("SchemaUI Demo")
        .with_options(options.clone());
    let frontend = TuiFrontend { options };
    let value = ui.run_with_frontend(frontend)?;
    println!("{}", serde_json::to_string_pretty(&value)?);
    Ok(())
}

Public API surface

For library integrations, the main entry points are:

• TUI runtime: crate::tui::app::{SchemaUI, UiOptions} and crate::tui::session::TuiFrontend
• TUI state: crate::tui::state::* (for example FormState, FormCommand, FormEngine, SectionState)
• Schema backend: crate::ui_ast::build_ui_ast together with crate::tui::model::form_schema_from_ui_ast (builds FormSchema from the canonical UI AST)

Architecture Snapshot

┌─────────────┐   parse/merge    ┌───────────────┐   layout + typing      ┌───────────────┐
│ io::input   ├─────────────────▶│ schema        ├───────────────────────▶│ tui::state    │
└─────────────┘                  │ (loader /     │                        │ (FormState,   │
                                 │ resolver /    │                        │ sections,     │
┌─────────────┐   emit Value     │ build_form_   │   FormSchema           │ reducers)     │
│ io::output  ◀──────────────────┴────pipeline───┘                        └────────┬──────┘
└─────────────┘                                                      focus/edits│
                                                                                │
                                                                     ┌──────────▼──────────┐
                                                                     │ tui::app::runtime   │
                                                                     │ (InputRouter,       │
                                                                     │ overlays, status)   │
                                                                     └──────────┬──────────┘
                                                                                │ draw
                                                                     ┌──────────▼──────────┐
                                                                     │ tui::view::*        │
                                                                     │ (ratatui view)      │
                                                                     └─────────────────────┘

This layout mirrors the actual modules under src/, making it easy to map any code change to its architectural responsibility.

Input & Output Design

• io::input::parse_document_str converts JSON/YAML/TOML (via serde_json, serde_yaml, toml) into serde_json::Value. Feature flags (json, yaml, toml, all_formats) keep dependencies lean.
• schema_from_data_value/str infers schemas from live configs, injecting draft-07 metadata and defaults so UIs load pre-existing values.
• schema_with_defaults merges canonical schemas with user data, propagating defaults through properties, patternProperties, additionalProperties, dependencies, dependentSchemas, arrays, and $ref targets without mutating the original tree.
• io::output::OutputOptions encapsulates serialization format, pretty/compact toggle, and a vector of OutputDestination::{Stdout, File}. Multiple destinations are supported; conflicts are caught before emission.
• SchemaUI::with_output wires these options into the runtime so the final serde_json::Value can be written automatically after the session ends.

Web UI Mode

The optional web feature bundles the files under web/dist/ directly into the crate and exposes high-level helpers for hosting the browser UI. Basic usage:

use schemaui::web::session::{
    ServeOptions,
    WebSessionBuilder,
    bind_session,
};

# async fn run() -> anyhow::Result<()> {
let schema = serde_json::json!({
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "host": {"type": "string", "default": "127.0.0.1"},
        "port": {"type": "integer", "default": 8080}
    },
    "required": ["host", "port"]
});

let config = WebSessionBuilder::new(schema)
    .with_title("Service Config")
    .build()?;
let session = bind_session(config, ServeOptions::default()).await?;
println!("visit http://{}/", session.local_addr());
let value = session.run().await?;
println!("final JSON: {}", serde_json::to_string_pretty(&value)?);
# Ok(())
# }

The helper spawns an Axum router that exposes /api/session, /api/save, and /api/exit alongside the embedded static assets. Library users can either call bind_session/serve_session for a turnkey flow or reuse session_router/WebSessionBuilder to integrate the UI into an existing HTTP stack. The official CLI (schemaui-cli web …) is merely a thin wrapper around these APIs.

JSON Schema → TUI Mapping

build_ui_ast resolves the schema into the canonical UI AST, and form_schema_from_ui_ast maps that tree into FormSection/FieldSchema for the TUI runtime:

| Schema feature | Resulting control | | -----------------------------------------------------