Customize the model

Everything on this page is an option of defineApi (and of createOpenApi, buildApiModel and the CLI that call it). Each change goes into the version-neutral model, so every OpenAPI version gets it.

Document fieldsCopy Anchor Link

ResourcesCopy Anchor Link

resources maps a table's app key to true (every operation, list and get for views), to a description, or to a resource an adapter serves (anything with a plan, such as the handler defineResource returns). A key the schema doesn't have throws.

defineApi(betterSupabase, {
  info: { title: "CRM API", version: "1.0.0" },
  resources: {
    customers: {
      list: customerList,
      pagination: "cursor",
      operations: ["list", "get", "update"],
      tag: "CRM",
      input: { update: CustomerPatch },
      output: { get: CustomerView },
    },
  },
});

list is GET /<table>, create is POST /<table> (201), get, update (PATCH) and delete (204) are on /<table>/{key}. The components are <Table>Row, <Table>Insert, <Table>Update and <Table>Page.

Every resource operation carries x-better-supabase-table (the schema-qualified table) and x-better-supabase-operation. extensionPrefix replaces the x-better-supabase- prefix of every generated field.

Security presetsCopy Anchor Link

security takes a list of presets, and defaults to ["bearer"]:

The oauth2 preset's endpoints are <supabaseUrl>/auth/v1/oauth/authorize and <supabaseUrl>/auth/v1/oauth/token, and its metadata URL is <origin>/.well-known/oauth-authorization-server/auth/v1. A route or resource with security: [] is public.

Error presetsCopy Anchor Link

errors lists the shared error responses, each { name, status, description }. The default, DEFAULT_ERRORS, has BadRequest (400), Unauthorized (401), Forbidden (403), NotFound (404), Conflict (409) and Unprocessable (422), all with the Problem Details body (PROBLEM_SCHEMA, the Problem component).

Each operation lists only the statuses it can answer:

An operation with a permission answers its 403 with the shared PermissionDenied response, which has examples for PERMISSION_DENIED, INSUFFICIENT_SCOPE and APPROVAL_REQUIRED (see permissions).

NamesCopy Anchor Link

operationId({ source, method, path, defaultId }) names every operation. Resource operations default to <operation><Table> (listCustomers), actions to <action><Table>, and routes to their method and path segments (postReportsReportIdRun).

componentName(context) names the components. For tables context is { kind: "table", table, variant, defaultName }, with variant one of Row, Insert, Update and Page; returning undefined keeps defaultName. For a Standard Schema used as input or output it is { kind: "schema", id, schema, role, operationId }, where id is the name taken from the schema's $id (or id) and role is input, output or item; returning undefined inlines the schema. Without componentName, a schema with an $id becomes a component named after the last segment of the $id (https://schemas.example.com/NewCustomer.json becomes NewCustomer), and one without is inlined.

defineApi(betterSupabase, {
  info,
  resources: { notes: true },
  operationId: ({ defaultId, source }) =>
    source.kind === "resource" ? `crm_${defaultId}` : defaultId,
  componentName: (context) =>
    context.kind === "table" ? `Note${context.variant}` : undefined,
});

Two different schemas with one name are reported as component-conflict, and the first one is kept.

extendCopy Anchor Link

extend on a resource is keyed by operation or action name, and * applies to every operation of the resource. The fields are deep-merged into the rendered operation, after fragments, so they win. A key that names no operation is reported as extend-unknown.

resources: {
  customers: {
    extend: {
      "*": { "x-team": "crm" },
      delete: { "x-audit": "required" },
    },
  },
},

A route takes extend directly.

RoutesCopy Anchor Link

routes documents handlers that aren't resources, such as bs.routes or your own Hono routes:

defineApi(betterSupabase, {
  info,
  basePath: "/api",
  routes: [
    {
      method: "POST",
      path: "/reports/{reportId}/run",
      summary: "Run a report",
      params: ReportParams,
      query: RunQuery,
      input: RunInput,
      output: ReportRun,
      permission: "reports.run",
    },
    {
      method: "GET",
      path: "/events",
      operationId: "streamEvents",
      stream: { item: ReportEvent },
      security: [],
    },
  ],
});

path is relative to basePath and names parameters as {name}. params, query, input and output are Standard Schemas; a path parameter params doesn't describe is a string. stream describes a stream of item values (text/event-stream unless contentType says otherwise), rendered with itemSchema in 3.2 and later. status defaults to 200 with an output or a stream, and 204 without. The method can also be query, which only 3.2 and later render. A method outside the HTTP methods throws.

FragmentsCopy Anchor Link

fragments are parsed OpenAPI objects (from YAML or JSON) deep-merged over the rendered document, in order. Objects merge, arrays and other values replace. A field a fragment changes is reported as fragment-conflict with its JSON Pointer, so you see what it overrode. A fragment that removes a required field throws.

import { parse } from "yaml";
import { readFileSync } from "node:fs";

defineApi(betterSupabase, {
  info,
  resources: { customers: true },
  fragments: [parse(readFileSync("openapi.extra.yaml", "utf8"))],
});

mergeJson(base, patch, onConflict?) is the merge the fragments use, and pointerToken(key) escapes a key for a JSON Pointer.

Enrich hooksCopy Anchor Link

enrich changes the model itself, before any version renders it. Each hook gets one item and returns a replacement, or undefined to keep it:

defineApi(betterSupabase, {
  info,
  resources: { customers: true },
  enrich: {
    operation: (operation) =>
      operation.method === "delete"
        ? { ...operation, description: "Deletes need an admin." }
        : undefined,
  },
});

The hooks run last while the model is built, so they see the plugin descriptions and the resource defaults.

Plugin descriptionsCopy Anchor Link

A plugin with a describe hook adds what it does to the served tables: the first-party plugins mark the columns they set readOnly and drop them from the required fields of the request bodies.

A describe hook that throws is reported as plugin-describe-failed, and the rest of the model is built.

Comments become descriptionsCopy Anchor Link

comment on table and comment on column become the description of the table's schemas and fields, unless a schema already has one. A comment line that starts with @deprecated marks the table or column deprecated, and the operations of a deprecated table are deprecated too. @example lines are left out of the description (the validator generators read them).

comment on column public.customers.kvk is 'Chamber of Commerce number.
@deprecated Use registration_number.';

Permissions in the documentCopy Anchor Link

With an authorizer, each permission reference becomes its key(), written as x-better-supabase-permission on the operation. Without one, a permission must be a string, and anything else is reported as permission-unresolved. requirePermissions: true reports every write (any operation other than list and get, and routes and actions whose method isn't GET, HEAD, OPTIONS or QUERY) that declares no permission as permission-missing. permissionScopes: "keys" adds each permission key as a scope of the oauth2 preset and of the operation's requirement.