chore: add schema for UC Metric Views on Analytics plugin

[atilafassina]

What

PR1 of the metric-views delivery stack: the schema contract for metric.json — the opt-in config that activates the analytics metric-view path. Ships in the shared package.

This is the typed contract only — no runtime, CLI, hook, UI, or demo. It lands inert: nothing executes until an app actually ships a config/queries/metric.json.

Why now / why it's safe

This re-ships part of #341 (a ~15k-line mega-PR) as a small, reviewable increment. The feature is opt-in and dormant (every metric-view code path gates on metric.json existing), and these are all new files — so it lands on main without touching any existing behavior.

What's in it — 4 files, +267

File	Purpose
packages/shared/src/schemas/metric-source.ts	Zod source of truth — metricSourceSchema + inferred MetricSource/MetricExecutor types
tools/generate-json-schema.ts	extended (+13) to emit the JSON Schema artifact
docs/static/schemas/metric-source.schema.json	generated, published JSON Schema (powers editor $schema autocomplete + validation)
packages/shared/src/schemas/metric-source.test.ts	13 safeParse validation cases

The metric.json contract

{
  "$schema": "https://databricks.github.io/appkit/schemas/metric-source.schema.json",
  "metricViews": {
    "revenue":   { "source": "main.analytics.revenue" },
    "my_orders": { "source": "main.sales.orders_by_user", "executor": "user" }
  }
}

• Top-level { $schema?, metricViews? }, closed (rejects unknown keys).
• metricViews is a single map of metric key → entry. One map (rather than per-executor sections) makes metric keys unique by construction — the route key space can't collide.
• metric key: identifier pattern ^[a-zA-Z_][a-zA-Z0-9_]*$ — becomes the route key (POST /api/analytics/metric/:key), the useMetricView('<key>', …) argument, and the MetricRegistry augmentation key.
• source: three-part Unity Catalog FQN <catalog>.<schema>.<metric_view>.
• executor: "app_service_principal" (default) runs as the app service principal with a shared cache; "user" runs on-behalf-of the requesting user with a per-user cache. Defaulting to app_service_principal matches plain <key>.sql queries executing as SP.
• Entries are objects (not bare strings) so future per-entry options (cacheTtl, defaultFilter, allowlists) are additive — executor is the first such option.

Shape revision (review feedback): the original proposal used top-level sp/obo lane sections, mirroring the <key>.sql / <key>.obo.sql query-file convention. Per review discussion this was reshaped to the entity-first metricViews map with a per-entry executor — clearer naming, execution mode as an attribute rather than a taxonomy, and the cross-lane duplicate-key rule (previously unexpressible in the schema, enforced post-parse) becomes unrepresentable.

Reconciliation note (for reviewers comparing against #341)

#341 authored this JSON-Schema-first (hand-written .schema.json → generated .ts via a generate-schema-types.ts tool). Since #341's base, main adopted a Zod-first convention in the manifest refactor (#261): Zod is the single source of truth and the JSON Schema is generated from it via tools/generate-json-schema.ts. This PR re-expresses the contract in main's current idiom. Consequences vs. the #341 reference:

• No *.generated.ts — the inferred MetricSource type replaces it.
• No ajv / ajv-formats — validation rides the Zod schema directly via safeParse, matching validate-manifest.ts.
• No package-internal .schema.json — the generated JSON lives only in docs/static/schemas/, exactly like the manifest schemas.

Note the shape also differs from #341 (see revision note above): downstream slices (runtime, typegen, CLI) port their config-reading layer against this revised contract.

Testing

• pnpm build && pnpm docs:build ✅
• pnpm check:fix && pnpm -r typecheck ✅
• pnpm test ✅ — metric-source.ts at 100% coverage. The generator is deterministic (re-running produces no diff) and does not drift the existing manifest/template schemas. Tests include rejection of the legacy sp/obo shape and verification that the executor default materializes on parse.

Stack context

Part of re-shipping #341 as a stacked chain (merge order PR0 → PR1 → PR3 → PR4 → PR2 → PR5 → PR6):

• PR0 ✅ landed as fix(appkit): trim x-forwarded-user in core OBO path #427 — trim x-forwarded-user in core OBO path
• PR1 ← this PR — metric.json schema
• PR3 typegen · PR4 CLI · PR2 runtime · PR5 UI · PR6 demo + docs

Only hard dependency on this PR: PR4 (appkit metric sync CLI) imports this schema and will validate via the Standard Schema interface (no Ajv).

---

This pull request and its description were written by Isaac.

[Copilot]

Pull request overview

Adds the initial schema contract for config/queries/metric.json (authored in Zod and emitted as JSON Schema) to support the upcoming analytics metric-view stack.

Changes:

• Introduces a new Zod schema (metricSourceSchema) that defines the allowed shape for metric.json (closed top-level object with optional $schema, sp, obo).
• Adds Vitest coverage for accepted/rejected configurations (metric key pattern, strict objects, 3-part UC FQN).
• Extends the JSON Schema generation script to emit and publish metric-source.schema.json under docs/static/schemas.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
tools/generate-json-schema.ts	Emits and writes the generated JSON Schema for the new metric-source Zod schema.
packages/shared/src/schemas/metric-source.ts	Defines the Zod source-of-truth schema and inferred TS types for metric.json.
packages/shared/src/schemas/metric-source.test.ts	Adds schema validation tests (valid/invalid configs).
docs/static/schemas/metric-source.schema.json	Generated draft-07 JSON Schema artifact served by docs for editor $schema validation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[calvarjorge]

Maybe this was already discussed and I missed it, but I don't fully agree with having the sp/obo as the top key. Basically, currently, it would be:

{
    "sp":  { "revenue":   { "source": "main.analytics.revenue" } },
    "obo": { "my_orders": { "source": "main.sales.orders_by_user" } }
 }

I'd prefer:

{
    "metrics": {
      "revenue":   { "source": "main.analytics.revenue",        "execute_as": "app_service_principal" },
      "my_orders": { "source": "main.sales.orders_by_user",     "execute_as": "user" }
    }
 }

The reasons why I believe this would be more intuitive are:

• The query execution principal is not that important of a concept to have it as the first-level key. In fact, maybe many users don't even care (and we can just use a default for them?).
• Having it as a key means that it's hard to even know what it is. IMO keys in an object should represent entities of the parent object.
• Naming of sp / obo is quite hard to understand. I'd prefer full text (at least accept it), ie, service_principal and on_behalf_of, or ideally app_service_principal and user to be more specific.

[atilafassina]

@calvarjorge agreed and adopted in 917242a (value renamed to app_service_principal in 5fc4a00) — the schema is now an entity-first metrics map with the execution principal as a per-entry attribute. Two naming tweaks from your sketch: the field is executor and the values are "app_service_principal" | "user", defaulting to app_service_principal (consistent with plain <key>.sql queries executing as SP, for the users who don't care).

{
  "metrics": {
    "revenue":   { "source": "main.analytics.revenue" },
    "my_orders": { "source": "main.sales.orders_by_user", "executor": "user" }
  }
}

Bonus your shape bought us: with a single map, metric keys are unique by construction — the old two-lane shape could express the same key in both sp and obo, which the schema couldn't forbid (cross-record key disjointness isn't expressible in JSON Schema), so the reference implementation enforced it post-parse in two separate places. That rule is now unrepresentable and both checks disappear from the downstream slices.

[calvarjorge]

Overall looks good - only one last thing: the concept of metric is quite broad. Maybe we want to be more specific and refer to this as metric_view? Specially if we might have other concepts similar to metrics in the future (telemetry metrics, etc.)

[atilafassina]

Follow-up on the shape discussion: renamed the root key metrics → metricViews in aa5d7fb — these entries are specifically UC metric views, and the bare metrics name collided with the observability sense of the word. camelCase per the repo's authored-config-key convention (appkit.plugins.json's displayName/dependsOn/…); snake_case stays reserved for values mirroring Databricks APIs (app_service_principal, sql_warehouse).

{
  "metricViews": {
    "revenue":   { "source": "main.analytics.revenue" },
    "my_orders": { "source": "main.sales.orders_by_user", "executor": "user" }
  }
}