ArctonArcton
Validation

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.

On this page