chore: add schema for UC Metric Views on Analytics plugin

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

@@ -0,0 +1,128 @@
+import { describe, expect, test } from "vitest";
+import { metricSourceSchema } from "./metric-source";
+
+describe("metricSourceSchema", () => {
+  test("accepts a minimal configuration and defaults executor to app_service_principal", () => {
+    const config = {
+      $schema:
+        "https://databricks.github.io/appkit/schemas/metric-source.schema.json",
+      metricViews: {
+        revenue: { source: "appkit_demo.public.revenue_metrics" },
+      },
+    };
+    const result = metricSourceSchema.safeParse(config);
+    expect(result.success).toBe(true);
+    expect(result.data?.metricViews?.revenue.executor).toBe(
+      "app_service_principal",
+    );
+  });
+
+  test("accepts explicit executor values", () => {
+    const config = {
+      metricViews: {
+        revenue: {
+          source: "demo.public.revenue",
+          executor: "app_service_principal",
+        },
+        my_orders: { source: "main.sales.orders_by_user", executor: "user" },
+      },
+    };
+    const result = metricSourceSchema.safeParse(config);
+    expect(result.success).toBe(true);
+    expect(result.data?.metricViews?.my_orders.executor).toBe("user");
+  });
+
+  test("accepts an empty configuration", () => {
+    expect(metricSourceSchema.safeParse({}).success).toBe(true);
+    expect(metricSourceSchema.safeParse({ metricViews: {} }).success).toBe(
+      true,
+    );
+  });
+
+  test("accepts metric keys with underscores", () => {
+    const config = {
+      metricViews: {
+        customer_metrics: { source: "demo.public.customer_metrics" },
+      },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(true);
+  });
+
+  test("rejects the legacy sp/obo lane shape", () => {
+    const config = {
+      sp: { revenue: { source: "demo.public.revenue" } },
+      obo: { my_orders: { source: "main.sales.orders_by_user" } },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(false);
+  });
+
+  test("rejects invalid executor values", () => {
+    for (const executor of ["sp", "obo", "service_principal", "USER"]) {
+      const config = {
+        metricViews: { revenue: { source: "a.b.c", executor } },
+      };
+      expect(metricSourceSchema.safeParse(config).success).toBe(false);
+    }
+  });
+
+  test("rejects a bare-string entry (must be an object)", () => {
+    const config = {
+      metricViews: { revenue: "demo.public.revenue" },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(false);
+  });
+
+  test("rejects an entry without source", () => {
+    const config = {
+      metricViews: { revenue: {} },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(false);
+  });
+
+  test("rejects unknown fields on entries", () => {
+    const config = {
+      metricViews: {
+        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({ metricViews: {}, unknown: {} }).success,
+    ).toBe(false);
+  });
+
+  test("rejects metric keys that start with a digit", () => {
+    const config = {
+      metricViews: { "1bad": { source: "a.b.c" } },
+    };
+    expect(metricSourceSchema.safeParse(config).success).toBe(false);
+  });
+
+  test("rejects metric keys containing a hyphen", () => {
+    const config = {
+      metricViews: { "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 = { metricViews: { revenue: { source } } };
+      expect(metricSourceSchema.safeParse(config).success).toBe(false);
+    }
+  });
+});

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

@@ -0,0 +1,84 @@
+/**
+ * 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 under a single `metricViews` map.
+ * Each entry binds a metric key to a UC metric view FQN plus the executor
+ * the query runs as:
+ * - `executor: "app_service_principal"` (default) — queried as the app service
+ *   principal (cache scope shared across all users).
+ * - `executor: "user"` — queried as the requesting user (on-behalf-of;
+ *   cache scope per-user).
+ *
+ * A single map (rather than per-executor sections) makes metric keys unique
+ * by construction — the same key cannot be declared twice with different
+ * executors.
+ */
+
+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.",
+  );
+
+export const metricExecutorSchema = z
+  .enum(["app_service_principal", "user"])
+  .describe(
+    "Who the metric view is queried as. 'app_service_principal' (default) runs as the app service principal with a cache shared across all users; 'user' runs on-behalf-of the requesting user with a per-user cache.",
+  );
+
+/**
+ * @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. `executor` is the first such option.
+ */
+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",
+        ],
+      }),
+    executor: metricExecutorSchema.default("app_service_principal"),
+  })
+  .strict()
+  .describe(
+    "A single metric view source declaration: the UC FQN to query and the executor to query it as. 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"),
+    metricViews: z
+      .record(metricKeySchema, metricEntrySchema)
+      .optional()
+      .describe(
+        "Metric view declarations, keyed by metric key. Each entry names the UC metric view to query and the executor it runs as.",
+      ),
+  })
+  .strict()
+  .describe(
+    "Schema for AppKit metric.json — declares Unity Catalog Metric View sources for the analytics plugin's metric-view path. Each entry under 'metricViews' binds a metric key to a UC metric view FQN and an executor ('app_service_principal' shared cache, or 'user' per-user cache). 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 MetricExecutor = z.infer<typeof metricExecutorSchema>;
+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) => {