Body
Validate a request body with a schema and access the parsed, validated result as `ctx.body`.
Declaring a body schema on a route's options gives you ctx.body — the
request body, parsed according to its Content-Type and validated against
your schema:
import { Arcton } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.post('/users', {
body: v.object({
name: v.pipe(v.string(), v.minLength(1)),
email: v.pipe(v.string(), v.email())
}),
handler: ctx => ({ created: ctx.body })
})
app.listen()ctx.body only appears — and only type-checks — on a route that declared a
body schema this way. A route without one doesn't have ctx.body at all.
Body isn't only JSON
A route accepts application/json and nothing else by default. Any other media
type — text/plain, a form body, even a +json subtype like
application/vnd.api+json — answers 415 before anything is parsed, unless the
route declares it explicitly with
content. Whatever value that media type
parses to is what your schema validates against, so a route can take plain text:
import { Arcton } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.post('/notes', {
body: { content: { 'text/plain': v.pipe(v.string(), v.minLength(1)) } },
handler: ctx => ({ length: ctx.body.length })
})
app.listen()or describe a FormData body:
import { Arcton } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.post('/upload', {
body: { content: { 'multipart/form-data': v.instance(FormData) } },
handler: ctx => ({ received: ctx.body.get('name') })
})
app.listen()Which Content-Type values parse to which JavaScript value — and what happens
when the request's Content-Type isn't one Arcton knows how to parse — is
covered in Body Parsers.
Optional bodies
A body is required by default: a request with no body at all is rejected
before your schema runs. To also accept one, pass { schema, optional: true }
instead of a bare schema:
import { Arcton } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.post('/reviews/:id/dismiss', {
body: {
schema: v.object({ reason: v.optional(v.string()) }),
optional: true
},
handler: ctx => ({ dismissedWith: ctx.body?.reason ?? null })
})
app.listen()A request that carries no body skips parsing and validation, and ctx.body is
undefined — it is not turned into {}, and the schema never sees it. The
type follows: ctx.body is the schema's output or undefined. A request that
does carry a body is handled exactly as before: {} goes through the schema,
malformed JSON is still a 400, an unsupported Content-Type still a 415.
"No body" means the request carries none — a Content-Type header on its own
doesn't make one.
Accepting specific media types
A bare schema accepts only application/json. To accept other media types, or
several, each with its own schema, use content instead of schema. content
replaces that default, so list application/json too if the route should keep
taking it:
import { Arcton } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.post('/webhook', {
body: {
content: {
'application/json': v.object({ event: v.string() }),
'text/plain': v.pipe(v.string(), v.minLength(1))
}
},
handler: ctx => ({ via: ctx.contentType, received: ctx.body })
})
app.listen()A request whose Content-Type isn't listed responds 415 before anything is
parsed. Matching ignores case and parameters like ; charset=, and is exact
otherwise: application/vnd.api+json doesn't match application/json. The
matched media type is ctx.contentType, and ctx.body is the output of that
media type's schema — so its type is the union of the outputs. Narrowing
ctx.body from ctx.contentType isn't type-checked yet.
content only decides which media types the route accepts; it doesn't teach
Arcton to read new ones. A media type with no built-in parser, like
text/csv, still needs an
app.parser() — without one
it answers 415; registering one never changes what a bare schema accepts.
optional: true works the same way as with schema: a
request with no body leaves both ctx.body and ctx.contentType undefined.
Use either schema or content, never both. OpenAPI
documents each listed media type with its schema.
Order
body validates last, after params and query — see
Validation Overview. A failing body schema responds with
400 the same way params or query failures do — see
Validation Errors.