Crate paramdef 

Type-safe parameter definition system.

paramdef provides a comprehensive system for defining, validating, and managing parameters in applications. Inspired by Blender RNA, Unreal Engine UPROPERTY, and Qt Property System.

Quick Start

The easiest way to get started is using the prelude:

use paramdef::prelude::*;
use std::sync::Arc;

// Create a schema with parameters
let schema = Schema::builder()
    .parameter(Text::builder("username")
        .label("Username")
        .required()
        .build())
    .parameter(Number::builder("age")
        .label("Age")
        .build())
    .parameter(Boolean::builder("active")
        .label("Active")
        .default(true)
        .build())
    .build();

// Create a runtime context
let mut ctx = Context::new(Arc::new(schema));

// Set values
ctx.set("username", Value::text("alice"));
ctx.set("age", Value::Int(30));
ctx.set("active", Value::Bool(true));

// Get values
assert_eq!(ctx.get("username").and_then(|v| v.as_text()), Some("alice"));

Architecture

paramdef uses a three-layer architecture:

1. Schema Layer (Immutable)

Parameter definitions shared via Arc. Contains metadata, flags, validators, and transformers. Multiple contexts can share the same schema.

Schema (Arc-shared, immutable)
  ├── Parameter definitions
  ├── Metadata (labels, descriptions)
  ├── Flags (REQUIRED, READONLY, etc.)
  └── Validation rules

2. Runtime Layer (Mutable)

Per-instance state management. Each Context has its own runtime state for parameter values, dirty flags, and validation errors.

Context (mutable, per-instance)
  ├── Current values
  ├── State flags (dirty, touched, valid)
  └── Validation errors

3. Value Layer

Runtime data representation. The Value enum is the serialization target and runtime storage format for all parameter types.

Value (runtime representation)
  ├── Primitives: Null, Bool, Int, Float, Text
  └── Collections: Array, Object, Binary

Type System

paramdef defines 23 node types across 4 categories:

Category	Own Value	Children	Types	Module
Group	❌	✅	2	types::group
Decoration	❌	❌	8	types::decoration
Container	✅	✅	7	types::container
Leaf	✅	❌	6	types::leaf

Group Types (Root Aggregators)

• types::group::Group - Root parameter group
• types::group::Panel - UI organization panel

Leaf Types (Terminal Values)

• types::leaf::Text - String values with validation
• types::leaf::Number - Numeric values (int/float) with units
• types::leaf::Boolean - True/false toggles
• types::leaf::Vector - Fixed-size numeric arrays
• types::leaf::Select - Single or multiple selection
• types::leaf::File - File uploads and references

Container Types (Structured Data)

• types::container::Object - Named field collection
• types::container::List - Dynamic array with item template
• types::container::Mode - Discriminated union (sum type)
• types::container::Matrix - Table-based data entry
• types::container::Routing - Connection/reference wrapper
• types::container::Expirable - TTL-based wrapper
• types::container::Reference - Template reference

Decoration Types (Display-Only)

• types::decoration::Notice - Info/warning/error messages
• types::decoration::Separator - Visual dividers
• types::decoration::Link - Clickable references
• types::decoration::Code - Syntax-highlighted code
• types::decoration::Image - Static images
• types::decoration::Html - Rich HTML content
• types::decoration::Video - Embedded video
• types::decoration::Progress - Progress indicators

Module Organization

• core - Foundation types (Key, Value, Metadata, Flags, Error)
• types - All 23 node types organized by category
• subtype - Type-safe subtypes and units
• schema - Schema and Context for managing parameters
• runtime - Runtime state management
• prelude - Common imports for convenience

Feature Flags

Feature	Description
serde	Serialization/deserialization support
validation	Validation system with custom validators
visibility	Visibility conditions and expressions
events	Event system with tokio channels
i18n	Internationalization with Fluent
chrono	Chrono type conversions
full	Enable all features

Examples

Building Complex Schemas

use paramdef::prelude::*;

let address = Object::builder("address")
    .field("street", Text::builder("street").required().build())
    .field("city", Text::builder("city").required().build())
    .field("zip", Text::builder("zip").build())
    .build();

let user = Object::builder("user")
    .field("name", Text::builder("name").required().build())
    .field("email", Text::builder("email").build())
    .field("address", address)
    .build();

Using Subtypes

use paramdef::prelude::*;
use paramdef::subtype::{Email, Port};

let email = Text::email("contact");
let port = Number::port("http_port").default(8080.0).build();

Re-exports

pub use context::Context;

pub use core::Error;

pub use core::Flags;

pub use core::Key;

pub use core::Metadata;

pub use core::Result;

pub use core::StateFlags;

pub use core::Value;

pub use runtime::ErasedRuntimeNode;

pub use runtime::RuntimeNode;

pub use runtime::State;

pub use schema::Schema;

pub use subtype::IntoBuilder;

pub use subtype::NumberSubtype;

pub use subtype::NumberUnit;

pub use subtype::TextSubtype;

pub use subtype::VectorSubtype;

Modules

context

Context for managing runtime parameter trees.

core

Core types for the paramdef library.

event

Event system for reactive parameter updates.

prelude

Convenience re-exports for common usage patterns.

runtime

Runtime layer for mutable parameter state.

schema

Schema module for immutable parameter definitions.

subtype

Type-safe subtypes for parameter definitions.

types

All 23 node types organized by category.

validation

Validation system for parameter values.

Macros

define_file_subtype

Defines a file subtype with MIME type constraints.

define_number_subtype

Defines a number subtype with automatic type constraint detection.

define_text_subtype

Defines a text subtype with semantic meaning.

define_vector_subtype

Defines a vector subtype with size constraint.