Standards
Standards registry
Every standard better-supabase follows, where it is used and how mature it is.
Every standard is opt-in: it lives in its own subpath or behind an option,
and nothing in the core requires it. Specs that are still drafts or versioned
conventions are pinned in code in SPEC_PINS
(import { SPEC_PINS } from 'better-supabase'), so an upgrade is always an
explicit change.
Posture
- Adopted: implemented, tested and covered by semver.
- Adopted (pinned): implemented against a pinned version of a draft or evolving convention. Moving the pin is a minor release with a changeset.
- Adopted (draft): implemented against a draft that has no release yet. It is opt-in, never a default, warns when it is used, and its fields may change with the draft.
- Tracked: not implemented yet; recorded so the design leaves room for it.
Registry
Each adopted standard has a conformance test in
packages/better-supabase/tests/standards. Where an official JSON Schema
exists (OpenAPI, Overlay, Arazzo, AsyncAPI, SARIF, CloudEvents, MCP, the MCP
Registry), the test
validates the output against a vendored copy of it.
| Standard | Posture | Where | Tests |
|---|---|---|---|
| Standard Schema v1 | Adopted | validation plugin, route()/action() inputs, /list, /env, typed jsonb, defineRpc | standard-schema.test.ts |
| Standard JSON Schema | Adopted | converting user schemas for OpenAPI and MCP tools | standard-schema.test.ts |
| JSON Schema 2020-12 | Adopted | generated table schemas, config, doctor report and metadata $schema URLs | json-schema-2020-12.test.ts |
| OpenAPI 3.0, 3.1 and 3.2 | Adopted (pinned) | /openapi: createOpenApi, openapiFormat and better-supabase openapi emit; 3.1 is the default | openapi.test.ts, openapi-versions.test.ts |
OpenAPI 3.3 draft (v3.3-dev) and Security Profiles | Adopted (draft) | version: "3.3-preview" on /openapi, never a default | openapi-versions.test.ts |
| Overlay 1.0, 1.1 and 1.2 | Adopted (pinned) | /overlay: defineOverlay, applyOverlay and overlayFromDiff, with RFC 9535 JSONPath | overlay.test.ts |
| Arazzo 1.0 and 1.1 | Adopted (pinned) | /arazzo: workflows over the emitted OpenAPI document | arazzo.test.ts |
| AuthZEN Authorization API 1.0 | Adopted (pinned) | the Authorizer interface: subject, action, resource and context, batch order, fail-closed | authzen.test.ts |
| RFC 9457 Problem Details | Adopted | toProblem(), every server adapter | rfc9457-problem-details.test.ts |
| RFC 6750 Bearer tokens | Adopted | WWW-Authenticate on 401, insufficient_scope on 403 from /mcp, resolveAuth | rfc6750-bearer.test.ts |
| RFC 9728 Protected Resource Metadata | Adopted | /mcp: the metadata document, scopes_supported and resource_metadata in every challenge | rfc9728-protected-resource.test.ts |
| RFC 7518 ES256 JSON Web Keys | Adopted | better-supabase keys, the local stack and asUser sign with ES256; HS256 is explicit and local-only | rfc7518-es256.test.ts |
| MCP 2026-07-28 (Streamable HTTP, authorization) | Adopted (pinned) | /mcp serves stateless 2026-07-28 requests and the 2025-11-25, 2025-06-18 and 2025-03-26 handshake | mcp.test.ts |
| OpenTelemetry DB semantic conventions | Adopted (pinned) | /otel | otel-semconv.test.ts |
| W3C Server Timing (Working Draft) | Adopted (pinned) | bs.proxy({ serverTiming: true }) emits bs-proxy and bs-verify (middleware) | w3c-server-timing.test.ts |
| W3C Trace Context | Adopted | /otel propagates traceparent through the supabase-js fetch | w3c-trace-context.test.ts |
| CloudEvents 1.0 | Adopted | /events | cloudevents.test.ts |
| Standard Webhooks | Adopted | /webhooks (Supabase Auth hooks, database webhooks), the webhook inbox | standard-webhooks.test.ts |
| Idempotency-Key header (IETF draft) | Adopted (draft) | /jobs | idempotency-key.test.ts |
| pgTAP | Adopted | sql add pgtap | sql-modules-standards.test.ts |
| WinterTC minimum common API | Adopted | runtime entries import no Node built-ins (checked in CI) | wintertc.test.ts |
| AbortSignal | Adopted | every repository, storage and RPC call takes signal | abort-signal.test.ts |
| Explicit Resource Management | Adopted | await using tx, using sub | explicit-resource-management.test.ts |
| PostgREST aggregate functions (12+) | Adopted (pinned) | aggregate() and _sum/_avg/_min/_max includes | postgrest-aggregates.test.ts |
| Stripe Sync Engine schema | Adopted (pinned) | the entitlements SQL module reads stripe.active_entitlements | sql-modules-standards.test.ts |
| pgvector iterative index scans (0.8+) | Adopted (pinned) | the vector-search SQL module sets hnsw.iterative_scan | sql-modules-standards.test.ts |
| SARIF 2.1.0 | Adopted | doctor --format sarif | sarif.test.ts |
| Agent Skills | Adopted | skills/ in the package, npx skills add ScaleDockHQ/better-supabase, better-supabase skills install (for AI agents) | agent-standards.test.ts |
| AGENTS.md and llms.txt | Adopted | repo root and these docs (/llms.txt, /llms-full.txt, /docs/<page>.md) | agent-standards.test.ts |
MCP Registry server.json | Adopted | the read-only docs MCP server at /mcp (for AI agents) | mcp-registry-server-json.test.ts |
| npm provenance | Adopted | release workflow | npm-provenance.test.ts |
| OCSF 1.9.0 | Adopted (pinned) | exportAuditLog({ format: "ocsf" }) in the audit block | ocsf.test.ts |
| OpenFeature 0.9.0 | Adopted (pinned) | createFlagsProvider() and createFlagClient() in the flags block | openfeature.test.ts |
| SCIM 2.0 (RFC 7643, RFC 7644) | Adopted (pinned) | scimHandler() in the SSO block serves /Users, /Groups and discovery | scim.test.ts |
| Supabase SDK diagnostic logging (capability matrix 1.14.0) | Adopted (pinned) | defineSupabase(schema, { diagnostics: true }) writes redacted debug records to logger (events) | supabase-sdk-diagnostic-logging.test.ts |
| better-supabase AI message v1 | Adopted (pinned) | ai_messages.parts in the AI chat block, schemas/ai-message-v1.json | ai-message.test.ts |
| AI SDK UI message stream protocol v1 | Adopted (pinned) | createAssistant() in better-supabase/ai-sdk/chat, resumed from the stream store | ai-sdk-ui-message-stream.test.ts |
Anthropic memory tool memory_20250818 | Adopted (pinned) | memoryTool() and anthropicMemory() in better-supabase/ai-sdk/memory, on the memory block | anthropic-memory-tool.test.ts |
| AsyncAPI 3.0 and 3.1 | Adopted (pinned) | /asyncapi: Realtime topics, table broadcasts and events | asyncapi.test.ts |
Pins
import { SPEC_PINS } from "better-supabase";
SPEC_PINS.otelSemconv; // OpenTelemetry semantic conventions version
SPEC_PINS.mcp; // MCP protocol revision (2026-07-28)
SPEC_PINS.openapi; // default OpenAPI version emitted (the same as openapi31)
SPEC_PINS.openapi30; // OpenAPI 3.0 patch release `version: "3.0"` emits
SPEC_PINS.openapi31; // OpenAPI 3.1 patch release `version: "3.1"` emits
SPEC_PINS.openapi32; // OpenAPI 3.2 patch release `version: "3.2"` emits
SPEC_PINS.openapi33Preview; // commit of the v3.3-dev branch `3.3-preview` follows
SPEC_PINS.securityProfiles; // state of the Security Profiles proposal `3.3-preview` follows
SPEC_PINS.overlay10; // Overlay 1.0 release `applyOverlay` reads
SPEC_PINS.overlay11; // Overlay 1.1 release, the default of `defineOverlay`
SPEC_PINS.overlay12; // Overlay 1.2 release (reusable actions, `$self`)
SPEC_PINS.arazzo10; // Arazzo 1.0 patch release
SPEC_PINS.arazzo11; // Arazzo 1.1 release (AsyncAPI steps)
SPEC_PINS.asyncapi30; // AsyncAPI 3.0 release
SPEC_PINS.asyncapi31; // AsyncAPI 3.1 release
SPEC_PINS.authzen; // AuthZEN Authorization API version the `Authorizer` vocabulary follows
SPEC_PINS.postgrestAggregates; // PostgREST version whose aggregate syntax is used
SPEC_PINS.serverTiming; // W3C Server Timing draft the proxy header follows
SPEC_PINS.stripeSyncEngine; // Stripe Sync Engine release whose tables the entitlements module reads
SPEC_PINS.pgvector; // minimum pgvector version for the vector-search module's iterative scans
SPEC_PINS.ocsf; // OCSF schema version of audit exports
SPEC_PINS.openfeature; // OpenFeature specification the flags provider follows
SPEC_PINS.scim; // SCIM version the SSO block's handler serves
SPEC_PINS.cloudevents; // CloudEvents version of `/events` envelopes
SPEC_PINS.standardWebhooks; // Standard Webhooks version `/webhooks` verifies
SPEC_PINS.sarif; // SARIF version of `doctor --format sarif`
SPEC_PINS.jsonSchema; // JSON Schema dialect of generated schemas
SPEC_PINS.supabaseSdkCapabilities; // Supabase SDK capability matrix the `diagnostics` option follows
SPEC_PINS.aiMessage; // version of the canonical AI message (`schemas/ai-message-v1.json`)
SPEC_PINS.aiSdkUiMessageStream; // AI SDK UI message stream protocol that `createAssistant` writes
SPEC_PINS.anthropicMemoryTool; // version of Anthropic's memory tool whose commands the memory block runsLast updated on