OpenAPI and JSON Schema

vld-aide

Use vld types in aide OpenAPI routers - a thin alias of vld-schemars with no aide dependency of its own.

aide builds OpenAPI documents from schemars::JsonSchema. vld-aide re-exports impl_json_schema!, vld_to_schemars and schemars from vld-schemars, so a vld type can be used in aide::axum::Json<T> and friends. It does not depend on aide: add the aide version you use yourself.

Install

Cargo.toml

[dependencies]
vld = { version = "0.5", features = ["openapi"] }
vld-aide = "0.5"   # schemars 0.9-0.x (default)
aide = { version = "0.15", features = ["axum"] }

Features

Feature	Default	Description
`schemars-0`	yes	schemars `>=0.9, <1` (aide 0.15)
`schemars-1`	no	schemars `>=1, <2` (aide releases built on schemars 1)

Enable exactly one, matching the schemars major your aide version uses (cargo tree -i schemars).

MSRV: 1.85 (see MSRV).

Example

use vld_aide::prelude::*;
use vld_aide::schemars::JsonSchema;

vld::schema! {
    #[derive(Debug)]
    pub struct CreateUser {
        pub name: String => vld::string().min(2).max(100),
        pub email: String => vld::string().email(),
        pub age: i64 => vld::number().int().min(13).max(150),
    }
}
impl_json_schema!(CreateUser);

assert_eq!(CreateUser::schema_name(), "CreateUser");

With aide and axum, the body type must also implement serde::Deserialize, so use #[derive(Validate)] (feature derive on vld) instead of schema!:

use aide::axum::{routing::post_with, ApiRouter};
use aide::axum::Json;
use aide::transform::TransformOperation;

#[derive(Debug, serde::Serialize, serde::Deserialize, vld::Validate)]
struct NewUser {
    #[vld(vld::string().min(2).max(100))]
    name: String,
    #[vld(vld::string().email())]
    email: String,
}
vld_aide::impl_json_schema!(NewUser);

async fn create_user(Json(body): Json<NewUser>) -> Json<serde_json::Value> {
    Json(serde_json::json!({"id": 1, "name": body.name}))
}

fn create_user_docs(op: TransformOperation) -> TransformOperation {
    op.summary("Create a user")
}

let app: ApiRouter = ApiRouter::new().api_route("/users", post_with(create_user, create_user_docs));

aide::axum::Json<T> deserializes with serde and does not run vld rules. Validate in the handler (NewUser::validate(&body), see parse vs validate) or use vld-axum extractors for the request and keep aide for the documentation.

API

Item	Description
`impl_json_schema!(T)` / `impl_json_schema!(T, "Name")`	`schemars::JsonSchema` for a vld type
`vld_to_schemars(&Value)`	JSON Schema value → `schemars::Schema`
`schemars`	Re-export of the selected schemars major
`prelude`	The two items above plus `vld::prelude::*`

Everything else (validator, introspection, to_openapi3) lives in vld-schemars.

Gotchas

Nested vld::nested! types are added to the generator's definitions, and their $refs point at aide's #/components/schemas/.
Query and path structs get an object schema; there is no per-parameter IntoParams like in vld-utoipa.

Edit this page on GitHub

vld-schemars

Two-way bridge between vld and schemars - vld types as schemars::JsonSchema, and schemars types validated through vld.

vld-ts

Generate TypeScript Zod or Valibot schemas from vld schemas, so the frontend validates exactly what the server does.