Crate wellformed 

wellformed

A portable FormSpec IR with Zod-like authoring for defining form schemas, transforms, constraints, and error metadata.

Overview

wellformed provides a declarative, portable way to define form validation schemas that can be:

• Serialized to JSON for cross-language interop
• Executed in the Rust runtime
• Used to generate code for other languages (TypeScript, OpenAPI, etc.)

Key Features

• Type Layer: Define structure with primitives, objects, arrays, enums
• Transform Layer: Normalize data before validation (trim, digits_only, etc.)
• Constraint Layer: Portable predicate AST for validation rules
• Error Layer: Structured, stable error codes with help text

Optional Features

• address: Enables address parsing predicates through the postal crate. This feature requires the native libpostal C library, headers, and parser data to be installed on the target system.

Example

use wellformed::ir::*;
use wellformed::runtime::validate;
use serde_json::json;

// Define a schema
let schema = Schema::new(
    "1.0.0",
    TypeSchema::Object(
        ObjectSchema::new()
            .property(
                "tin",
                TypeSchema::String(
                    StringSchema::new()
                        .transform(Transform::digits_only())
                        .constraint(Constraint::new(
                            Predicate::regex(r"^\d{9}$"),
                            ErrorMeta::new("TIN_INVALID", "TIN must be 9 digits"),
                        )),
                ),
            )
            .property("name", TypeSchema::string()),
    ),
);

// Validate a value
let mut value = json!({
    "tin": "123-45-6789",
    "name": "Alice"
});

let result = validate(&schema, &mut value).unwrap();
assert!(result.is_valid());
assert_eq!(value["tin"], json!("123456789")); // Transformed

See https://wellformed.net/docs/rust-runtime for Rust runtime usage.

Re-exports

pub use error::Result;

pub use error::WelError;

pub use form::ClientFormSpec;

pub use form::EmbeddedSchema;

pub use form::FieldKind;

pub use form::FieldSpec;

pub use form::FieldState;

pub use form::FormErrors;

pub use form::FormState;

pub use ir::Constraint;

pub use ir::ErrorMeta;

pub use ir::ErrorSeverity;

pub use ir::FormError;

pub use ir::Predicate;

pub use ir::Schema;

pub use ir::Transform;

pub use ir::TypeSchema;

pub use path::JsonPointer;

pub use path::Segment;

pub use runtime::validate;

pub use runtime::validate;

pub use runtime::validate_with_registry;

pub use runtime::ValidationResult;

Modules

codegen

Code generation from wellformed schemas.

error

Internal error types for wellformed operations.

form

Form-oriented runtime helpers for generated wellformed schemas.

ir

IR (Intermediate Representation) types for form schemas.

path

JSON Pointer (RFC 6901) with wildcard extension.

runtime

Runtime for executing wellformed schemas.