chore: add schema for UC Metric Views on Analytics plugin

packages/shared/src/schemas/metric-source.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "vitest";
+import { metricSourceSchema } from "./metric-source";
+
+describe("metricSourceSchema", () => {
+  test("accepts a valid SP-only configuration", () => {
+    const config = {
+      $schema:
+        "https://databricks.github.io/appkit/schemas/metric-source.schema.json",
+      sp: {
+        revenue: { source: "appkit_demo.public.revenue_metrics" },
+      },
+      obo: {},
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(true);
+  });
+
+  test("accepts mixed sp + obo lanes", () => {
+    const config = {
+      sp: { revenue: { source: "demo.public.revenue" } },
+      obo: { customer: { source: "demo.public.customer_metrics" } },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(true);
+  });
+
+  test("accepts an empty configuration", () => {
+    expect(metricSourceSchema.safeParse({}).success).toBe(true);
+    expect(metricSourceSchema.safeParse({ sp: {}, obo: {} }).success).toBe(
+      true,
+    );
+  });
+
+  test("accepts metric keys with underscores", () => {
+    const config = {
+      sp: { customer_metrics: { source: "demo.public.customer_metrics" } },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(true);
+  });
+
+  test("rejects a bare-string entry (must be an object)", () => {
+    const config = {
+      sp: { revenue: "demo.public.revenue" },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(false);
+  });
+
+  test("rejects an entry without source", () => {
+    const config = {
+      sp: { revenue: {} },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(false);
+  });
+
+  test("rejects unknown fields on entries", () => {
+    const config = {
+      sp: {
+        revenue: {
+          source: "a.b.c",
+          ttl: 5, // future option, not in v1
+        },
+      },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(false);
+  });
+
+  test("rejects unknown top-level keys", () => {
+    expect(metricSourceSchema.safeParse({ foo: 1 }).success).toBe(false);
+    expect(
+      metricSourceSchema.safeParse({ sp: {}, obo: {}, unknown: {} }).success,
+    ).toBe(false);
+  });
+
+  test("rejects metric keys that start with a digit", () => {
+    const config = {
+      sp: { "1bad": { source: "a.b.c" } },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(false);
+  });
+
+  test("rejects metric keys containing a hyphen", () => {
+    const config = {
+      sp: { "bad-key": { source: "a.b.c" } },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(false);
+  });
+
+  test("rejects a non-three-part FQN", () => {
+    const cases = [
+      "revenue", // single token
+      "demo.revenue", // two parts
+      "four.parts.really.bad",
+      ".starts.with.dot",
+      "ends.with.dot.",
+    ];
+    for (const source of cases) {
+      const config = { sp: { revenue: { source } } };
+      expect(metricSourceSchema.safeParse(config).success).toBe(false);
+    }
+  });
+});

packages/shared/src/schemas/metric-source.ts

@@ -0,0 +1,77 @@
+/**
+ * AppKit metric-source schema.
+ *
+ * Single source of truth for `metric.json`
+ * the config that activates the Analytics' metric-view path.
+ *
+ * `metric.json` declares UC Metric Views.
+ * Each entry under `sp`/`obo` binds a metric key to a UC metric view FQN:
+ * - `sp` entries are queried as the service principal (cache scope shared
+ *   across all users).
+ * - `obo` entries are queried as the requesting user (on-behalf-of; cache
+ *   scope per-user).
+ */
+
+import { z } from "zod";
+
+export const metricKeySchema = z
+  .string()
+  .regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/)
+  .describe(
+    "Metric key. Must be a valid identifier (letters, digits, underscores; cannot start with a digit). Becomes the route key in POST /api/analytics/metric/:key, the hook argument in useMetricView('<key>', ...), and the MetricRegistry augmentation key.",
+  );
+
+/**
+ * @note Entries are objects (rather than bare strings) at v1 so future per-entry
+ * options (cacheTtl, defaultFilter, allowlists) can ship as additive
+ * properties without a breaking change.
+ */
+export const metricEntrySchema = z
+  .object({
+    source: z
+      .string()
+      .regex(
+        /^[a-zA-Z0-9_][a-zA-Z0-9_-]*\.[a-zA-Z0-9_][a-zA-Z0-9_-]*\.[a-zA-Z0-9_][a-zA-Z0-9_-]*$/,
+      )
+      .describe(
+        "Three-part Unity Catalog FQN of the metric view: <catalog>.<schema>.<metric_view>",
+      )
+      .meta({
+        examples: [
+          "appkit_demo.public.revenue_metrics",
+          "main.analytics.customer_metrics",
+        ],
+      }),
+  })
+  .strict()
+  .describe(
+    "A single metric view source declaration. v1 only accepts the 'source' field; future per-entry options (cacheTtl, defaultFilter, allowlists) ship as additive properties.",
+  );
+
+export const metricSourceSchema = z
+  .object({
+    $schema: z
+      .string()
+      .optional()
+      .describe("Reference to the JSON Schema for validation"),
+    sp: z
+      .record(metricKeySchema, metricEntrySchema)
+      .optional()
+      .describe(
+        "Metric views queried as the service principal. Cache scope is shared across all users.",
+      ),
+    obo: z
+      .record(metricKeySchema, metricEntrySchema)
+      .optional()
+      .describe(
+        "Metric views queried as the requesting user (on-behalf-of). Cache scope is per-user.",
+      ),
+  })
+  .strict()
+  .describe(
+    "Schema for AppKit metric.json — declares Unity Catalog Metric View sources for the analytics plugin's metric-view path. Each entry under sp/obo binds a metric key to a UC metric view FQN. Object form (rather than bare string) at v1 enables future per-entry option growth without breaking changes.",
+  );
+
+export type MetricKey = z.infer<typeof metricKeySchema>;
+export type MetricEntry = z.infer<typeof metricEntrySchema>;
+export type MetricSource = z.infer<typeof metricSourceSchema>;

tools/generate-json-schema.ts

@@ -14,6 +14,7 @@ import {
   pluginManifestSchema,
   templatePluginsManifestSchema,
 } from "../packages/shared/src/schemas/manifest";
+import { metricSourceSchema } from "../packages/shared/src/schemas/metric-source";
 import { formatWithBiome } from "./format-with-biome";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -28,11 +29,17 @@ const TEMPLATE_OUT_PATH = path.join(
   DOCS_SCHEMAS_DIR,
   "template-plugins.schema.json",
 );
+const METRIC_SOURCE_OUT_PATH = path.join(
+  DOCS_SCHEMAS_DIR,
+  "metric-source.schema.json",
+);
 
 const PLUGIN_SCHEMA_ID =
   "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json";
 const TEMPLATE_SCHEMA_ID =
   "https://databricks.github.io/appkit/schemas/template-plugins.schema.json";
+const METRIC_SOURCE_SCHEMA_ID =
+  "https://databricks.github.io/appkit/schemas/metric-source.schema.json";
 
 function emit(
   schema: z.ZodType,
@@ -91,9 +98,15 @@ async function main(): Promise<void> {
     TEMPLATE_SCHEMA_ID,
     "AppKit Template Plugins Manifest",
   );
+  const metricSourceJson = emit(
+    metricSourceSchema,
+    METRIC_SOURCE_SCHEMA_ID,
+    "AppKit Metric Source Configuration",
+  );
 
   writeJson(PLUGIN_OUT_PATH, pluginJson);
   writeJson(TEMPLATE_OUT_PATH, templateJson);
+  writeJson(METRIC_SOURCE_OUT_PATH, metricSourceJson);
 }
 
 main().catch((err) => {