Setting examples for requests (inputs) to APIs

[chibx]

Hey, this is my first time in a discussion here 👋🏼

I am building a server with Elysia.js and I am using its OpenAPI adapter with Valibot's JSON Schema mapper
The issue I am facing stems from my attempt to add examples using input types. For example

// A simple schema
export const CreateSubscriptionSchema = v.pipe(
    v.object({
        planId: v.pipe(v.string(), v.toBigint("Invalid plan id")),
        cardId: v.optional(v.string()),
        callbackUrl: v.pipe(v.string(), v.regex(httpRegex, "Invalid callback url")),
    }), v.examples([{
        planId: "12345",
        callbackUrl: "",
        cardId: ""
    }])
);

I got to learn that v.examples() takes in values similar to the result of v.InferOutput which is logically speaking for validation result (and response typing in Elysia), but I want to build my OpenAPI docs using the request body (Input) types

If I pass in a string to my planId field instead of a bigint, v.examples() will yell at me, so is there a way to configure v.examples to store inputs for a particular schema, or should I have done the below instead:

export const CreateSubscriptionSchema = v.object({
    planId: v.pipe(v.string(), v.examples(["12345"]), v.toBigint("Invalid plan id")), // Emphasis on the position
    cardId: v.pipe(v.optional(v.string()), v.examples(["54321"])),
    callbackUrl: v.pipe(v.string(), v.regex(httpRegex, "Invalid callback url"), v.examples([""])),
});

Please I would love to know if there's anything I am doing wrong

[dosubot[bot]]

Hi @chibx! I'm Dosu and I'm helping the Open Circle team.

You're on the right track with your second approach! The key insight is that v.examples() uses the type at its position in the pipe — so placement matters [1]. When you put v.examples() at the end of the outer pipe (after v.toBigint()), it expects the output type (bigint), which is why it complains when you pass a string.

To provide input-type examples, place v.examples() before the transformation:

export const CreateSubscriptionSchema = v.object({
    planId: v.pipe(
        v.string(),
        v.examples(["12345"]),              // before toBigint → expects string ✅
        v.toBigint("Invalid plan id")
    ),
    cardId: v.optional(v.pipe(v.string(), v.examples(["54321"]))),
    callbackUrl: v.pipe(
        v.string(),
        v.regex(httpRegex, "Invalid callback url"),
        v.examples(["https://example.com/callback"])
    ),
});

Since examples() is purely a metadata action — it doesn't affect validation or transformation — its position only determines which type it expects at compile time [2]. For your OpenAPI use case with the JSON Schema mapper, placing examples on individual fields before any transformations should give you the correct input-type examples in your generated docs.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.