Skip to Content
onedef

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 })
operationsRESTMCP tools
collection()list, get; create and delete if declared; your actionsGET /songs, GET /songs/{slug}, POST /songs, DELETE /songs/{slug}, POST /songs/{slug}/renamesongs_list, songs_get, songs_create, …
singleton()get; your actionsGET /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 through get on the server before your handler runs, and passes it as object. One round trip, on every surface.
  • Return the updated object (output: Song, the same schema as fields), and caches that hold it update by themselves.
  • process: true makes 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

opMCP toolCLIREST
songs.setOffsetsongs_set_offsetmisrava 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.

On this page