The contract
What your API is, as one value. Every surface is derived from it.
The contract describes your API: its objects, its operations, their input and output schemas, and a one-line summary for each. It holds no server code, so a browser, a CLI or a published SDK can import it without pulling in your backend.
import { defineApi, defineConfig } from 'onedef'
export const config = defineConfig({
name: 'misrava', // MCP server name, CLI binary, tool prefix
description: 'French songs taught line by line.', // MCP server instructions, docs intro
})
export const contract = defineApi(config, { songs, concepts })Schemas are any Standard Schema validator with JSON Schema support: zod 4.2 or later, valibot or arktype. Nothing to register.
Objects: collection() and singleton()
Most APIs are objects, so that's the main way to declare them.
export const songs = collection(config, {
name: 'songs',
description: 'French song lessons.',
id: 'slug', // the field that addresses one song
fields: Song, // the object: what `get` returns
summary: SongSummary, // the list item, when it should be lighter than `fields`
create: { input: NewSong },
delete: true,
actions: {
rename: action({
summary: 'Rename a lesson',
input: z.object({ title: z.string() }),
output: Song,
needs: 'object',
}),
},
})
export const account = singleton(config, { name: 'account', description: 'You.', fields: Account })| operations | REST | MCP tools | |
|---|---|---|---|
collection() | list, get; create and delete if declared; your actions | GET /songs, GET /songs/{slug}, POST /songs, DELETE /songs/{slug}, POST /songs/{slug}/rename | songs_list, songs_get, songs_create, … |
singleton() | get; your actions | GET /account, POST /account/<action> | account_get, … |
Actions
An action is a verb of your own. By default it acts on one object (POST /songs/{slug}/rename).
Pass on: 'collection' for one that acts on the whole collection.
needs: 'object'loads the object throughgeton the server before your handler runs, and passes it asobject. One round trip, on every surface.- Return the updated object (
output: Song, the same schema asfields), and caches that hold it update by themselves. process: truemakes it a long-running process an agent can drive. See Processes.
Lists: filters and pages
list takes input like any operation, so filters and search are input fields.
paginate: 'cursor' adds cursor and limit, and returns { items, nextCursor }:
collection(config, {
// …
list: { input: z.object({ q: z.string().optional() }), paginate: 'cursor' },
})Plain operations: defineService()
For things that aren't objects (search, health checks, batch jobs), declare operations
directly. query() is read-only (GET, MCP readOnlyHint). mutation() changes something
(POST).
export const sources = defineService(config, {
name: 'sources',
description: 'Where lyrics can come from.',
ops: {
list: query({ summary: 'List the lyrics sources', output: z.array(Source) }),
},
})Collections and singletons compile down to these same operations, so everything that works for one works for the other.
Names, derived once
| op | MCP tool | CLI | REST |
|---|---|---|---|
songs.setOffset | songs_set_offset | misrava songs set-offset <slug> | POST /songs/{slug}/set-offset |
Summaries become MCP tool titles, CLI help and OpenAPI summaries. description becomes the
longer explanation an agent reads before calling a tool, so it is worth writing well.