chore: add schema for UC Metric Views on Analytics plugin#429
Open
atilafassina wants to merge 3 commits into
Open
chore: add schema for UC Metric Views on Analytics plugin#429atilafassina wants to merge 3 commits into
atilafassina wants to merge 3 commits into
Conversation
atilafassina
changed the title
…hema) Author the metric.json config contract as Zod in packages/shared/src/schemas/metric-source.ts (single source of truth) and generate the published JSON Schema via tools/generate-json-schema.ts into docs/static/schemas/metric-source.schema.json. metric.json declares the Unity Catalog Metric View sources (sp/obo lanes) that opt an app into the analytics metric-view path. Reconciles PR1 of the metric-views stack onto main's Zod-first schema convention; #341 authored this JSON-first with a separate generated type. Co-authored-by: Isaac Signed-off-by: Atila Fassina <atila@fassina.eu>
Validate metricSourceSchema directly via safeParse (no Ajv): accepts sp-only / mixed sp+obo / empty configs; rejects bare-string entries, missing source, unknown entry and top-level fields, invalid metric keys (leading digit, hyphen), and malformed source FQNs. Ports the #341 case set to main's Zod-first validation idiom. Co-authored-by: Isaac Signed-off-by: Atila Fassina <atila@fassina.eu>
Trim the module header, move the object-entry rationale to a @note on metricEntrySchema, and drop the section banners. Comment-only — the Zod schema, describe() strings, and generated JSON are unchanged. Co-authored-by: Isaac Signed-off-by: Atila Fassina <atila@fassina.eu>
atilafassina
changed the title
atilafassina
changed the title
Contributor
There was a problem hiding this comment.
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 formetric.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.jsonunderdocs/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.
Comment on lines
+51
to
+77
| 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>; |
Comment on lines
+5
to
+13
| 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: {}, | ||
| }; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 thesharedpackage.Note
This is the typed contract only — no runtime, CLI, hook, UI, or demo.
nothing executes until an app actually ships a
config/queries/metric.json.The
metric.jsoncontract{ $schema?, sp?, obo? }, closed (rejects unknown keys).sp/oboare maps of metric key →{ source }:sp— queried as the service principal (shared cache).obo— queried on-behalf-of the requesting user (per-user cache).^[a-zA-Z_][a-zA-Z0-9_]*$— becomes the route key (POST /api/analytics/metric/:key), theuseMetricView('<key>', …)argument, and theMetricRegistryaugmentation key.<catalog>.<schema>.<metric_view>. Object form (not a bare string) so future per-entry options are additive.Stack context
The current PR adds the schema without any user-facing surface.
This schema will be used by the typegen PR to generate the runtime queries in a follow up PR