Struct ZObject 

pub struct ZObject { /* private fields */ }

Dynamic object schema with runtime-defined fields.

For compile-time type-safe objects, use the schema! macro instead.

Unknown field handling

• strip() (default) — unknown fields are silently removed from the output.
• strict() — unknown fields cause a validation error.
• passthrough() — unknown fields are kept as-is in the output.

Example

use vld::prelude::*;

let schema = vld::object()
    .field("name", vld::string().min(1))
    .field("age", vld::number().int().min(0));

Implementations

impl ZObject

pub fn new() -> ZObject

pub fn field<S>(self, name: impl Into<String>, schema: S) -> ZObject

where S: DynSchema + Send + Sync + 'static,

Add a field with its validation schema. A field with the same name is replaced.

With the openapi feature the field keeps its JSON Schema, its required status (.optional() / .nullish() / .with_default(...) / .nullable() are not required) and its named nested schemas.

pub fn field_optional<S>(self, name: impl Into<String>, schema: S) -> ZObject

where S: DynSchema + Send + Sync + 'static,

Add a field that is automatically optional (null/missing → null).

The field won’t cause a validation error if it is missing or null. When the value is missing/null the inner schema still runs first, so .with_default(...) and .catch(...) produce their value; otherwise the output is null.

Example

use vld::prelude::*;

let schema = vld::object()
    .field("name", vld::string().min(1))
    .field_optional("nickname", vld::string().min(1));

let result = schema.parse(r#"{"name": "Alice"}"#).unwrap();
assert_eq!(result.get("nickname").unwrap(), &serde_json::Value::Null);

pub fn strict(self) -> ZObject

Reject unknown fields not defined in the schema.

pub fn strip(self) -> ZObject

Silently remove unknown fields from the output (default behavior).

pub fn passthrough(self) -> ZObject

Keep unknown fields as-is in the output without validation.

pub fn omit(self, name: &str) -> ZObject

Remove a field definition by name. Returns self for chaining.

Useful with extend() to override fields.

pub fn pick(self, names: &[&str]) -> ZObject

Keep only the listed fields, removing all others.

pub fn extend(self, other: ZObject) -> ZObject

Merge another object schema into this one.

If both schemas define the same field, the one from other wins (and takes its place at the end). other’s settings are merged too: its unknown-field mode (when not the default strip()), catchall, min_keys / max_keys win when set, and its when rules are added.

pub fn merge(self, other: ZObject) -> ZObject

Alias for extend.

pub fn partial(self) -> ZObject

Make all fields optional: null/missing values return null in the output instead of failing validation.

Equivalent to Zod’s .partial().

pub fn required(self) -> ZObject

Make all fields required: null values will fail validation. This is the opposite of partial().

pub fn catchall<S>(self, schema: S) -> ZObject

where S: DynSchema + Send + Sync + 'static,

Validate unknown fields using the given schema instead of stripping/rejecting them.

When set, unknown fields are parsed through the catchall schema regardless of the unknown field mode.

pub fn when<S>( self, condition_field: impl Into<String>, condition_value: impl Into<Value>, target_field: impl Into<String>, schema: S, ) -> ZObject

where S: DynSchema + Send + Sync + 'static,

Add a conditional validation rule.

When condition_field has the given value, target_field is validated with the provided schema in addition to any existing field schemas. Under strict() an undeclared target_field is not reported as unrecognized.

Example

use vld::prelude::*;

let schema = vld::object()
    .field("role", vld::string())
    .field_optional("admin_key", vld::string())
    .when("role", "admin", "admin_key", vld::string().min(10));

// When role != "admin", admin_key is optional and any value is fine
let ok = schema.parse(r#"{"role": "user"}"#);
assert!(ok.is_ok());

// When role == "admin", admin_key must pass the extra schema
let err = schema.parse(r#"{"role": "admin", "admin_key": "short"}"#);
assert!(err.is_err());

pub fn min_keys(self, n: usize) -> ZObject

Require at least this many keys in the input object.

pub fn max_keys(self, n: usize) -> ZObject

Require at most this many keys in the input object.

pub fn deep_partial(self) -> ZObject

👎Deprecated since 0.5.0:

not recursive; identical to partial(). Call partial() on nested objects explicitly.

Same as partial(): not recursive.

Fields are type-erased, so nested objects cannot be reached; call partial() on nested ZObjects yourself before adding them.

pub fn keyof(&self) -> Vec<String>

Get the list of field names defined in this schema.

Trait Implementations

impl Default for ZObject

fn default() -> ZObject

Returns the “default value” for a type.

impl VldSchema for ZObject

type Output = Map<String, Value>

The Rust type produced by this schema after successful parsing.

fn parse_value(&self, value: &Value) -> Result<Map<String, Value>, VldError>

Parse and validate a serde_json::Value.

fn parse<I>(&self, input: &I) -> Result<Self::Output, VldError>

where I: VldInput + ?Sized,

Parse from any supported input (JSON string, file path, serde_json::Value, etc.)

fn validate<T>(&self, value: &T) -> Result<Self::Output, VldError>

where T: Serialize,

Validate an existing Rust value against this schema.

fn is_valid<T>(&self, value: &T) -> bool

where T: Serialize,

Check if an existing Rust value passes this schema’s validation.

fn optional(self) -> ZOptional<Self>

Make this field optional. Missing or null values become None.

fn nullable(self) -> ZNullable<Self>

Allow null values. Null becomes None.

fn with_default(self, value: Self::Output) -> ZDefault<Self>

where Self::Output: Clone,

Provide a default value when the field is missing or null.

fn refine<F>(self, check: F, message: &str) -> ZRefine<Self, F>

where F: Fn(&Self::Output) -> bool,

Add a custom refinement check without changing the output type.

fn transform<F, U>(self, f: F) -> ZTransform<Self, F, U>

where F: Fn(Self::Output) -> U,

Transform the output value after successful parsing.

fn nullish(self) -> ZNullish<Self>

Make this field nullish (both optional and nullable).

fn catch(self, fallback: Self::Output) -> ZCatch<Self>

where Self::Output: Clone,

Return a fallback value on ANY validation error.

fn pipe<S>(self, next: S) -> ZPipe<Self, S>

where S: VldSchema, Self::Output: Serialize,

Chain this schema’s output into another schema.

fn describe(self, description: &str) -> ZDescribe<Self>

Attach a human-readable description/label to this schema.

fn super_refine<F>(self, check: F) -> ZSuperRefine<Self, F>

where F: Fn(&Self::Output, &mut VldError),

Add a custom refinement that can produce multiple errors.

fn or<B>(self, other: B) -> ZUnion2<Self, B>

where B: VldSchema,

Create a union: this schema or another. Returns Either<Self::Output, B::Output>.

fn and<B>(self, other: B) -> ZIntersection<Self, B>

where B: VldSchema,

Create an intersection: input must satisfy both schemas.

fn message(self, msg: impl Into<String>) -> ZMessage<Self>

Override the error message for this schema.