feat(config): publish the config schemas as draft-07 under supabase.com/schemas

.gitattributes

@@ -28,9 +28,7 @@ packages/api/src/generated/* linguist-generated=true
 packages/api/scripts/openapi-source.json linguist-generated=true
 packages/stack/src/functions/generated/* text eol=lf linguist-generated=true
 apps/cli/src/shared/feedback/database.types.ts linguist-generated=true
-apps/docs/public/cli/config.schema.json linguist-generated=true
-apps/docs/public/cli/project-config.schema.json linguist-generated=true
-apps/docs/public/cli/supabase-lock/v1.schema.json linguist-generated=true
+apps/docs/public/schemas/** linguist-generated=true
 
 # Lockfiles. Collapsed rather than hidden -- a dependency change is still one
 # click away in review, which is the same treatment GitHub gives package-lock.json.

apps/cli/docs/stack-commands.md

@@ -351,7 +351,7 @@ start --frozen` fails instead of resolving when the lock is missing or stale; it
 targets another project or branch than the lock observed (run `supabase stack update`), and when
 this CLI bundles a newer revision of a locked version. A lock that is malformed, does not match the
 format, or comes from a newer CLI always fails the start. The lock's JSON Schema is published at
-`https://supabase.com/docs/cli/supabase-lock/v1.schema.json`. A database with initialized data keeps
+`https://supabase.com/schemas/supabase-lock/v1.json`. A database with initialized data keeps
 its build: any change other than a new `-rN` revision of the same build (a different upstream build,
 release line or major) is refused. The refusal offers to keep the data by pinning the recorded build with
 `[local.services.database] version`, setting `[db] major_version` back when the major differs and removing any

apps/cli/scripts/generate-docs.ts

@@ -1,11 +1,12 @@
 import { BunFileSystem, BunPath } from "@effect/platform-bun";
 import process from "node:process";
 import { CLI_CONFIG_SCHEMA_URL, PROJECT_CONFIG_SCHEMA_URL } from "@supabase/config";
-import { Lock, LOCK_SCHEMA_URL } from "@supabase/stack/effect";
+import { HOSTED_LOCK_SCHEMA_URL } from "@supabase/stack/effect";
 import { Console, Effect, FileSystem, Layer, Path, Schema } from "effect";
 import { rootCommand } from "../src/cli/root.ts";
 import { collectCommands, getHelpDoc } from "../src/shared/cli/command-docs.ts";
 import { formatHelpDocAsMarkdown } from "../src/shared/cli/markdown-formatter.ts";
+import { lockSchemaDocument, publishedSchemaPath } from "./published-schemas.ts";
 
 const BINARY_NAME = "supabase";
 const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown, { space: 2 }));
@@ -92,8 +93,7 @@ const main = Effect.gen(function* () {
     schemaUrl: string,
     distFileName: string,
   ) {
-    const schemaPathname = new URL(schemaUrl).pathname.replace(/^\/docs/, "");
-    const destPath = path.join(defaultDocsPublicDir, schemaPathname);
+    const destPath = path.join(defaultDocsPublicDir, publishedSchemaPath(schemaUrl));
     const sourcePath = path.join(configPackageDistDir, distFileName);
 
     yield* fs.makeDirectory(path.dirname(destPath), { recursive: true });
@@ -106,20 +106,10 @@ const main = Effect.gen(function* () {
 
   /** Writes the `supabase.lock` v1 JSON Schema, generated from the stack's lock schema, to its docs-site public path. */
   const writeLockSchemaAsset = Effect.fnUntraced(function* () {
-    const { schema, definitions } = Schema.toJsonSchemaDocument(Lock);
-    const document = {
-      $schema: "https://json-schema.org/draft/2020-12/schema",
-      $id: LOCK_SCHEMA_URL,
-      title: "supabase.lock",
-      description: "The service versions that supabase start pins in supabase/supabase.lock.",
-      ...schema,
-      $defs: definitions,
-    };
-    const schemaPathname = new URL(LOCK_SCHEMA_URL).pathname.replace(/^\/docs/, "");
-    const destPath = path.join(defaultDocsPublicDir, schemaPathname);
+    const destPath = path.join(defaultDocsPublicDir, publishedSchemaPath(HOSTED_LOCK_SCHEMA_URL));
 
     yield* fs.makeDirectory(path.dirname(destPath), { recursive: true });
-    yield* fs.writeFileString(destPath, `${yield* encodeJson(document)}\n`);
+    yield* fs.writeFileString(destPath, `${yield* encodeJson(lockSchemaDocument())}\n`);
 
     yield* Console.log(
       `Generated: ${path.relative(path.resolve(import.meta.dir, "../../.."), destPath)}`,

apps/cli/scripts/published-schemas.ts

@@ -0,0 +1,77 @@
+import { HOSTED_LOCK_SCHEMA_URL, Lock, LOCK_SCHEMA_URL } from "@supabase/stack/effect";
+import { JsonSchema, Predicate, Schema } from "effect";
+
+const DEFINITION_REF_PREFIX = "#/definitions/";
+
+const renameRefs = (node: unknown, renames: ReadonlyMap<string, string>): unknown =>
+  Array.isArray(node)
+    ? node.map((child) => renameRefs(child, renames))
+    : Predicate.isObject(node)
+      ? renameRefsIn(node, renames)
+      : node;
+
+const renameRefsIn = (
+  node: JsonSchema.JsonSchema,
+  renames: ReadonlyMap<string, string>,
+): JsonSchema.JsonSchema =>
+  Object.fromEntries(
+    Object.entries(node).map(([key, value]) => [
+      key,
+      key === "$ref" && typeof value === "string"
+        ? (renames.get(value) ?? value)
+        : renameRefs(value, renames),
+    ]),
+  );
+
+/** Collapses identical definitions onto the first name, since `Lock` renders one per service. */
+const dedupeDefinitions = ({ schema, definitions }: JsonSchema.Document<"draft-07">) => {
+  const firstByBody = new Map<string, string>();
+  const renames = new Map<string, string>();
+  const kept: Array<[string, JsonSchema.JsonSchema]> = [];
+  for (const [name, definition] of Object.entries(definitions)) {
+    const body = JSON.stringify(definition);
+    const first = firstByBody.get(body);
+    if (first === undefined) {
+      firstByBody.set(body, name);
+      kept.push([name, definition]);
+    } else {
+      renames.set(`${DEFINITION_REF_PREFIX}${name}`, `${DEFINITION_REF_PREFIX}${first}`);
+    }
+  }
+  return {
+    schema: renameRefsIn(schema, renames),
+    definitions: renameRefsIn(Object.fromEntries(kept), renames),
+  };
+};
+
+/** `readLock` accepts the hosted `$schema` URL alongside the legacy one that writes still use. */
+const acceptHostedSchemaUrl = (schema: JsonSchema.JsonSchema): JsonSchema.JsonSchema => {
+  const properties = schema["properties"];
+  return Predicate.isObject(properties)
+    ? {
+        ...schema,
+        properties: {
+          ...properties,
+          $schema: { type: "string", enum: [LOCK_SCHEMA_URL, HOSTED_LOCK_SCHEMA_URL] },
+        },
+      }
+    : schema;
+};
+
+/** The draft-07 JSON Schema of `supabase/supabase.lock`, rendered from the stack's `Lock` schema. */
+export const lockSchemaDocument = () => {
+  const { schema, definitions } = dedupeDefinitions(
+    JsonSchema.toDocumentDraft07(Schema.toJsonSchemaDocument(Lock)),
+  );
+  return {
+    $schema: JsonSchema.META_SCHEMA_URI_DRAFT_07,
+    $id: HOSTED_LOCK_SCHEMA_URL,
+    title: "supabase.lock",
+    description: "The service versions that supabase start pins in supabase/supabase.lock.",
+    ...acceptHostedSchemaUrl(schema),
+    definitions,
+  };
+};
+
+/** The path under `apps/docs/public` that serves the schema published at `url`. */
+export const publishedSchemaPath = (url: string): string => new URL(url).pathname;

apps/cli/scripts/published-schemas.unit.test.ts

@@ -0,0 +1,214 @@
+import { BunServices } from "@effect/platform-bun";
+import { describe, expect, it } from "@effect/vitest";
+import {
+  CLI_CONFIG_SCHEMA_URL,
+  PROJECT_CONFIG_SCHEMA_URL,
+  toCliConfigJsonSchema,
+  toProjectConfigJsonSchema,
+} from "@supabase/config";
+import { HOSTED_LOCK_SCHEMA_URL, LOCK_SCHEMA_URL } from "@supabase/stack/effect";
+import { Effect, FileSystem, JsonSchema, Path, Schema } from "effect";
+import { lockSchemaDocument, publishedSchemaPath } from "./published-schemas.ts";
+
+type Document = Readonly<Record<string, unknown>>;
+
+const REGENERATE =
+  "run `pnpm --filter @supabase/config build && bun apps/cli/scripts/generate-docs.ts`";
+
+const POST_DRAFT_07_KEYWORDS = new Set([
+  "$defs",
+  "prefixItems",
+  "unevaluatedProperties",
+  "unevaluatedItems",
+  "dependentRequired",
+  "dependentSchemas",
+  "$dynamicRef",
+  "$dynamicAnchor",
+  "$recursiveRef",
+  "$recursiveAnchor",
+  "$anchor",
+  "$vocabulary",
+  "minContains",
+  "maxContains",
+]);
+const DATA_KEYWORDS = new Set(["default", "examples", "enum", "const"]);
+const SCHEMA_MAP_KEYWORDS = new Set(["properties", "patternProperties", "definitions"]);
+
+const isNode = (value: unknown): value is Document =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const findPostDraft07Usage = (node: unknown, path: ReadonlyArray<string> = []): Array<string> => {
+  if (Array.isArray(node)) {
+    return node.flatMap((child, index) => findPostDraft07Usage(child, [...path, String(index)]));
+  }
+  if (!isNode(node)) return [];
+  return Object.entries(node).flatMap(([keyword, value]) => {
+    const here = [...path, keyword];
+    if (POST_DRAFT_07_KEYWORDS.has(keyword)) return [here.join("/")];
+    if (keyword === "$ref" && typeof value === "string" && value.startsWith("#/$defs/")) {
+      return [here.join("/")];
+    }
+    if (DATA_KEYWORDS.has(keyword)) return [];
+    if (SCHEMA_MAP_KEYWORDS.has(keyword) && isNode(value)) {
+      return Object.entries(value).flatMap(([name, child]) =>
+        findPostDraft07Usage(child, [...here, name]),
+      );
+    }
+    return findPostDraft07Usage(value, here);
+  });
+};
+
+const collectRefs = (node: unknown): Array<string> => {
+  if (Array.isArray(node)) return node.flatMap(collectRefs);
+  if (!isNode(node)) return [];
+  return Object.entries(node).flatMap(([keyword, value]) =>
+    keyword === "$ref" && typeof value === "string" ? [value] : collectRefs(value),
+  );
+};
+
+const withoutMetadata = ({
+  $id: _id,
+  title: _title,
+  description: _description,
+  ...rest
+}: Document): Document => rest;
+
+const published = [
+  {
+    name: "config",
+    file: "schemas/config/v1.json",
+    url: CLI_CONFIG_SCHEMA_URL,
+    build: (): Document => toCliConfigJsonSchema(),
+    comparable: withoutMetadata,
+  },
+  {
+    name: "project-config",
+    file: "schemas/project-config/v1.json",
+    url: PROJECT_CONFIG_SCHEMA_URL,
+    build: (): Document => toProjectConfigJsonSchema(),
+    comparable: withoutMetadata,
+  },
+  {
+    name: "supabase-lock",
+    file: "schemas/supabase-lock/v1.json",
+    url: HOSTED_LOCK_SCHEMA_URL,
+    build: (): Document => lockSchemaDocument(),
+    comparable: (document: Document): Document => document,
+  },
+] as const;
+
+const decodeDocument = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown)),
+);
+
+const readCommitted = (file: string) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const publicDir = path.resolve(import.meta.dirname, "../../docs/public");
+    return yield* decodeDocument(yield* fs.readFileString(path.join(publicDir, file)));
+  }).pipe(Effect.provide(BunServices.layer));
+
+describe("findPostDraft07Usage", () => {
+  it("flags post-draft-07 keywords and $defs refs in schema positions", () => {
+    const document = {
+      type: "object",
+      $defs: { Name: { type: "string" } },
+      properties: {
+        tuple: { type: "array", prefixItems: [{ type: "string" }] },
+        name: { $ref: "#/$defs/Name" },
+      },
+    };
+
+    expect(findPostDraft07Usage(document)).toEqual([
+      "$defs",
+      "properties/tuple/prefixItems",
+      "properties/name/$ref",
+    ]);
+  });
+
+  it("treats property names and data keywords as data", () => {
+    const document = {
+      type: "object",
+      properties: {
+        prefixItems: { type: "string", default: "x" },
+        $defs: { type: "object", default: { $defs: {} }, examples: [{ prefixItems: [] }] },
+        mode: { enum: ["$defs", "prefixItems"], const: "$defs" },
+      },
+      definitions: { unevaluatedProperties: { type: "string" } },
+    };
+
+    expect(findPostDraft07Usage(document)).toEqual([]);
+  });
+});
+
+describe.each(published)("published $name schema", (entry) => {
+  it.effect("declares draft-07 and an $id that serves from its own path", () =>
+    Effect.gen(function* () {
+      const document = yield* readCommitted(entry.file);
+
+      expect(document["$schema"]).toBe(JsonSchema.META_SCHEMA_URI_DRAFT_07);
+      expect(document["$id"]).toBe(entry.url);
+      expect(publishedSchemaPath(entry.url)).toBe(`/${entry.file}`);
+    }),
+  );
+
+  it.effect("uses no keyword newer than draft-07", () =>
+    Effect.gen(function* () {
+      expect(findPostDraft07Usage(yield* readCommitted(entry.file))).toEqual([]);
+    }),
+  );
+
+  it.effect("matches what the build renders", () =>
+    Effect.gen(function* () {
+      const document = yield* readCommitted(entry.file);
+
+      expect(
+        entry.comparable(document),
+        `apps/docs/public/${entry.file} is stale: ${REGENERATE}`,
+      ).toEqual(entry.comparable(entry.build()));
+    }),
+  );
+});
+
+describe("published supabase-lock schema definitions", () => {
+  const readLockDefinitions = Effect.gen(function* () {
+    const document = yield* readCommitted("schemas/supabase-lock/v1.json");
+    const definitions = document["definitions"];
+    return { document, definitions: isNode(definitions) ? definitions : {} };
+  });
+
+  it.effect("are pairwise distinct", () =>
+    Effect.gen(function* () {
+      const { definitions } = yield* readLockDefinitions;
+      const bodies = Object.values(definitions).map((definition) => JSON.stringify(definition));
+
+      expect(bodies.length).toBeGreaterThan(1);
+      expect(new Set(bodies).size).toBe(bodies.length);
+    }),
+  );
+
+  it.effect("cover every $ref in the document", () =>
+    Effect.gen(function* () {
+      const { document, definitions } = yield* readLockDefinitions;
+      const refs = collectRefs(document);
+
+      expect(refs).not.toEqual([]);
+      expect(
+        refs.filter((ref) => !Object.keys(definitions).includes(ref.replace("#/definitions/", ""))),
+      ).toEqual([]);
+    }),
+  );
+
+  it.effect("accept every $schema value readLock accepts", () =>
+    Effect.gen(function* () {
+      const document = yield* readCommitted("schemas/supabase-lock/v1.json");
+      const properties = document["properties"];
+      const schemaProperty = isNode(properties) ? properties["$schema"] : undefined;
+
+      expect(isNode(schemaProperty) ? schemaProperty["enum"] : undefined).toEqual(
+        expect.arrayContaining([LOCK_SCHEMA_URL, HOSTED_LOCK_SCHEMA_URL]),
+      );
+    }),
+  );
+});

apps/cli/src/commands/experimental/stack/start/SIDE_EFFECTS.md

@@ -133,7 +133,7 @@ When the project has a `supabase/config.toml`, the versions a new or stopped sta
 twelve services it records the specifier requested under `[local.services]` (`<service>.version`,
 else `default.version`, else `linked`), how it resolved, and the exact pin: the release revision,
 each target's archive and manifest digests, and the image digest. Its
-[JSON Schema](https://supabase.com/docs/cli/supabase-lock/v1.schema.json) is published with the
+[JSON Schema](https://supabase.com/schemas/supabase-lock/v1.json) is published with the
 docs. A project without `supabase/config.toml` runs the versions bundled with the CLI and has no
 lock, unless `--frozen` is set, which fails the start.