[* as Code] Migrate to `@kbn/zod` by nickofthyme · Pull Request #268329 · elastic/kibana

nickofthyme · 2026-05-08T03:26:39Z

Summary

Migrate as-code schemas to @kbn/zod

Notes

Leaves SavedObject schemas alone, duplicates when needed.
Converts as much as possible in-place to minimize code diffs

Why change all schemas?

With dashboard schemas being the primary consumer of these as-Code schemas, we cannot change parts of the schema without changing all at once or creating a custom schema-config/zod conversion layer. Doing it altogether is tough but necessary for future-proofing as-code.

Reviewing

Guide to reviewing this PR.

There should be minimal changes to the actual schemas as this is meant to be as close to a 1:1 replacement as possible. That said there are a few functional differences namely:

Route params and query schemas
- schema.number() -> z.coerce.number(), see [* as Code] Migrate to @kbn/zod #268329 (comment)
- schema.boolean() -> z.stringbool(), see [* as Code] Migrate to @kbn/zod #268329 (comment)
schema.object({ a: schema.any() }) to z.object({ a: z.any() }), see [* as Code] Migrate to @kbn/zod #268329 (comment)
.default().optional() vs .optional().default(), see [* as Code] Migrate to @kbn/zod #268329 (comment)
Using schema.nullable() coerces missing or undefined to null. But zod's bare .nullable() only allows X | null and requires the field to be present. Thus schema.nullable() -> z.nullable().default(null).
schema.object() is strict by default where it will reject unknowns unless explicitly relaxed. But z.object() defaults to ignore, so a 1:1 replacement would be schema.object() -> z.object().strict().
Types related to z.object({}).loose(), see [* as Code] Migrate to @kbn/zod #268329 (comment)
Defaults for schema.object(...) with only optional properties, see [* as Code] Migrate to @kbn/zod #268329 (comment)

I tried my best to leave everything in order as to limit the diff, but zod syntax is much more concise so git/github has some trouble nicely aligning the diffs.

If there is a mistake in the syntax, it would be a huge help if you comment with the suggested code fix so it can be easily applied.

Checklist

Documentation was added for features that require explanation or tutorials
Unit or functional tests were updated or added to match the most common scenarios
This was checked for breaking HTTP API changes, and any breaking changes have been approved by the breaking-change committee. The release_note:breaking label should be applied in these situations.
The PR description includes the appropriate Release Notes section, and the correct release_note:* label is applied per the guidelines
Review the backport guidelines and apply applicable backport:* labels.

Identify risks

Describe the risk, its severity, and mitigation for each identified risk. Invite stakeholders and evaluate how to proceed before merging.

Schemas could act slightly different than @kbn/config-schema

nickofthyme

Comments for reviewers

nickofthyme · 2026-05-14T23:12:39Z

+            params: zod.object({
+              x: zod.coerce.number(),
+              y: zod.coerce.number(),
+              z: zod.coerce.number(),
            }),


The behavior of schema.number is more aligned with z.coerce.number but in many use cases this does not actually matter. This is only necessary for params and query schemas as these are passed as strings.

Value z.number() z.coerce.number() schema.number()

0 0 0 0

'0' Error 0 0

1 1 1 1

'1' Error 1 1

'1.23' Error 1.23 1.23

1.23 1.23 1.23 1.23

'two' Error Error Error

false Error 0 Error

true Error 1 Error

nickofthyme · 2026-05-14T23:21:42Z

+    // For now, we use `z.any()` to allow flexibility in the params field.
+    params: z.any().optional(),


Using schema.any() inside a schema.object() actually optionalizes that property where it is not required. But doing so with zod requires you explicitly pass undefined as a value.

// @kbn/config-schema const testType1 = schema.object({ a: schema.any() }); type TestType1 = TypeOf<typeof testType1>; // { a?: any; } // @kbn/zod const testType2 = z.object({ a: z.any() }); type TestType2 = z.output<typeof testType2>; // { a: any; }

So schema.any() used as a prop is replaced with z.any().optional().

nickofthyme · 2026-05-14T23:26:33Z

+  color: z
+    .union([colorByValueSchema, noColorSchema, autoColorSchema])
+
+    .default(AUTO_COLOR)
+    .optional()


The .optional() modifier always comes after .default() otherwise the type is not inferred as undefined/optional.

const testType1 = z.number().default(0).optional(); // number | undefined const testType2 = z.number().optional().default(0); // number

Really these should not be mixed at all because .optional() wipes away the applied .default() but for now this is to best match the current schemas.

nickofthyme · 2026-05-14T23:32:43Z

+  })
+  .meta({
+    id: 'gaugeNoESQL',
+    title: 'Gauge Chart (DSL)',
+    description: 'Gauge configuration using a data view.',
+  });


The options from schema.object are inherited when using .extends such that...

const mySchema = schema.object({}, { unknowns: 'forbid' }); const mySchemaCopy = mySchema.extends({}); // still forbids unknowns

This is not true with zod, the strictness is not passed on using .extend.

const mySchema = z.object({}).strict(); const mySchemaCopy = mySchema.extend({}); // no longer strict

Because of this we need to explicitly carry forward the strictness/looseness of any extended object schema.

const mySchema = z.object({}).strict(); const mySchemaCopy = mySchema.extend({}).strict(); // also strict

nickofthyme · 2026-05-14T23:41:57Z

+    // TODO: enforce Serializable type, see https://github.com/elastic/kibana/pull/269196
+    config: z.object({}).loose() as z.ZodType<{}>,


The loose equivalent in zod actually has more correct typings than config-schema as shown here...

// @kbn/config-schema const testType1 = schema.object({}, { unknowns: 'allow' }); // {} // @kbn/zod const testType2 = z.object({}).loose(); // { [x: string]: unknown; }

The issue is that these type feed into Serializable and get passed around as generic object type.

I'll address this in a follow up PR. See #269196 for more details.

nickofthyme · 2026-05-14T23:47:53Z

-export type VisualizationConfig = ReturnType<
-  ChartTypeRegistry[SupportedChartType]['schema']['validate']
->;
+export type VisualizationConfig = z.output<ChartTypeRegistry[SupportedChartType]['schema']>;


This type was previously any as typeof chartTypeRegistry was explicitly defined as Record<SupportedChartType, ChartTypeRegistryEntry> so none of the schemas were inferred.

We could use satisfies on chartTypeRegistry but that overly narrows the type for each supported chart type where it would be missing undefined values from ChartTypeRegistryEntry. Defining the explicit type is the best alternative.

nickofthyme · 2026-05-14T23:56:29Z

-export function mergeAllMetricsWithChartDimensionSchema<T extends Props>(
-  baseSchema: T,
-  context: string
-) {
-  return schema.oneOf([
-    mergeWithSimpleMetrics(baseSchema, context),
-    formulaOperationDefinitionSchema.extends(
-      baseSchema,
-      ctxMeta(context, 'Formula', METRIC_OP_TITLES.formula)
-    ),
+export function getMetricsWithChartDimensionSchema(context: string) {
+  return z.union([
+    getSimpleMetricsSchema(context),
+    formulaOperationDefinitionSchema.meta(ctxMeta(context, 'Formula', METRIC_OP_TITLES.formula)),


These metric schemas were a large strain on the TS inferred type depth limit with the nested extending of a generic baseSchema. This simplifies it and relies on the .and method of zod to intersect each of these.

I think this will also help to optimize the OAS output such that this...

const testSchema = z.object({ a: z.string() }).meta({ id: 'test-schema' }); const extendedSchema = testSchema.and(z.object({ n: z.number() }))

...outputs extendedSchema as this...

{ "allOf": [ { "$ref": "#/components/schemas/test-schema" }, { "type": "object", "properties": { "n": { "type": "number" } }, "required": ["n"] } ] }

Co-authored-by: Nick Partridge <nick.ryan.partridge@gmail.com>

nreese

kibana-presentation changes LGTM - Thanks for taking on such a large project. Great to see no changes in public code for generated types.
Code review only
Did not review filters schemas - @nickpeihl can you review those?

github-actions

Reviewed the @kbn/config-schema → @kbn/zod migration. Most systemic concerns (.strict() parity, z.coerce/stringbool for query params, z.any() optionality, strict-intersection issues in chart schemas) are already well-covered by prior review threads. One additional concrete finding on the drilldown registry, inline.

Generated by Claude Reviewer for #268329 · 511.2 AIC · ⌖ 11.7 AIC · ⊞ 4.6K

github-actions · 2026-07-23T03:58:44Z

+                ),
+                type: z.literal(type),
+              })
+            )


Strict .and() intersection rejects valid drilldown configs at runtime — same failure mode already flagged for the chart schemas (getMetrics...().and(...)), but here it hits registered drilldowns.

Zod validates both sides of an intersection against the full input. drilldownSetup.schema can be a .strict() object — urlDrilldownSchema in x-pack/platform/plugins/private/drilldowns/url_drilldown/server/schemas.ts is defined with .strict(). So when this combined schema validates a real drilldown value { url, encode_url, open_in_new_tab, label, trigger, type }, the strict left-hand side rejects label, trigger, and type as unrecognized keys before the right-hand object can accept them, so parsing throws even for valid input.

The previous drilldownSetup.schema.extends({ label, trigger, type }) merged the keys into a single object, so no key was ever "unrecognized". To preserve that behavior, merge the extra keys into the drilldown object's shape (as was done for the chart schemas) rather than intersecting with a strict object — e.g. build the combined schema from drilldownSetup.schema extended with the { label, trigger, type } shape, or ensure the intersected object is non-strict so keys owned by the other side aren't rejected.

AlexGPlay

LGTM, code review only. Thank you for the change 😄!

github-actions · 2026-07-23T14:27:13Z

- [request body.layout.0]: expected value to equal [horizontal]\n\
- [request body.layout.1]: expected value to equal [vertical]'
+    expect(response.body.message).toMatch(
+      /layout.*horizontal|layout.*vertical|horizontal|vertical/i


The trailing |horizontal|vertical disjuncts drop the coupling to the layout field, so this assertion passes on any error message containing just the word "horizontal" or "vertical" — including one from an unrelated field or endpoint. Recommend tightening so the message must also mention the layout field.

See details

The first two disjuncts (layout.*horizontal|layout.*vertical) already cover the intended zod message. The fallback tail is over-permissive: if the route regressed so a different validation fired (e.g. a chart-type or orientation field elsewhere in the request/response pipeline that happens to mention horizontal), this test would still pass without ever exercising the layout enum error path.

Suggested tightening:

expect(response.body.message).toMatch(/layout.*(horizontal|vertical)/i);

The same pattern appears at src/platform/plugins/private/links/test/scout/api/tests/update_links.spec.ts:144 — recommend updating both spots.

^{Share feedback in the #appex-qa Slack channel.}

smith

Service map embeddable changes look good

Converts allowHiddenIndicesSchema from @kbn/config-schema (unimported) to z.boolean().optional().meta(), fixing a ReferenceError on startup that caused all discover/as-code jobs to fail. Claude-Session: https://claude.ai/code/session_0132ugcMCNCJZSqUGDsh8pPM

github-actions

One additional occurrence of the strict-.and() intersection issue already discussed elsewhere in this PR — this one is on the Lens embeddable's by-value panel schema, which is the schema actually returned to the dashboard panel transform path. Left inline. The rest of the migration matches the documented conversion rules.

Generated by Claude Reviewer for #268329 · 506.9 AIC · ⌖ 11.7 AIC · ⊞ 464

github-actions · 2026-07-24T02:04:09Z

-  });
+export const getLensByValuePanelSchema = (getDrilldownsSchema: GetDrilldownsSchemaFnType) => {
+  return lensApiConfigSchema
+    .and(getSharedPanelSchema(getDrilldownsSchema))


🟠 Strict .and() intersection rejects every by-value Lens panel at runtime — same failure mode already flagged on gauge.ts, registry.ts, and shared.ts, but it also lands here and this is the schema returned by getSchema for the Lens embeddable (getLensPanelSchema → used in the dashboard panel transform .parse() path).

getSharedPanelSchema(...) is defined with a trailing .strict() (line 85). Zod validates both sides of an intersection against the entire input, so the strict right-hand object rejects any key it doesn't declare. The chart-config keys on the left side (type, metrics, styling, dataSource.*, breakdown_by, ...) are not part of getSharedPanelSchema's shape, so a real by-value Lens config fails validation with Unrecognized key before the union branch can match.

The old extendLensApiConfigSchema(getSharedPanelSchema(...)) merged the shared props into each union branch, so the branch objects (which are non-strict and strip) accepted the combined shape. To preserve that, either drop .strict() from getSharedPanelSchema for the by-value case, or build the union of per-branch extensions rather than intersecting with a strict object. Note getLensByRefPanelSchema (line 93) is unaffected because it uses .extend(...).strict() on a single object.

Fixed in bcc3374 and ea7e974

…idation option

…bility

markov00

This is a pure mechanical port to zod, I don't see discrepancies between the schemas on visualization owned files

nickpeihl · 2026-07-24T12:47:07Z

-        stripUnknownKeys: true,
-      }
-    );
+    transformedPanelConfig = transforms.schema.parse(transformedPanelConfig);


As discussed offline with @nickofthyme, Zod does not support any type of stripUnknownKeys option. On a quick check of all our integration dashboards, I'm seeing a slight increase in cases where transformed panels are leaking invalid or unknown properties from saved object state to the transformedPanelConfig. This causes the .parse method to throw an error.

Fortunately, #270300 (🙏 @Heenawter ) captures these transform errors and drops invalid panels from dashboard rather than throwing a 500 error. In the UI the dashboard loads and shows a warning toast about dropped panels.

So with this change, users may see a slight increase in panel warnings with hand-modified or otherwise munged saved objects. But I think we can look at fixing leaky transforms in subsequent PRs.

cc @nreese

nickpeihl

This is huge and amazing work @nickofthyme! LGTM! Code review and I tested 1371 integration dashboards seeing only a slight increase in panel transform warnings. Usually these saved objects are hand-munged so we can discuss fixing those with the integrations team. None of the integration dashboards returned a 500 error, all return HTTP 200.

dej611 · 2026-07-24T13:57:12Z

@@ -79,6 +79,14 @@ export const APPROVED_TRIGGER_DEFINITIONS: Array<{ id: string; schemaHash: strin
    id: 'alerting.ruleEnabled',
    schemaHash: '95d5d9bc425bbc2ef5391ee67d280aa42c1acfab230920a482e91d01a02c4a13',
  },
+  {


Apparently this PR triggered a missed task from CI. So good for us 🎉

Is this a good thing? 🤔 😅

kibanamachine · 2026-07-25T05:15:40Z

💛 Build succeeded, but was flaky

Buildkite Build
Commit: ac80916
Build duration: 69 mins

Failed CI Steps

Test Failures

[job] [logs] Scout Lane #1 - stateful-classic / default / local-stateful-classic - Discover filter editor - should support app filters in histogram/total hits and data grid
[job] [logs] Scout Lane #8 - stateful-classic / default / local-stateful-classic - Lens with multiple data views - should allow building a multi-data-view chart and applying global filters

Metrics [docs]

Module Count

Fewer modules leads to a faster build time

id	before	after	diff
`agentBuilder`	1996	1952	-44
`agentBuilderDashboards`	631	568	-63
`agentBuilderVisualizations`	562	503	-59
`apm`	2978	2915	-63
`apmShared`	549	550	+1
`automaticImport`	281	282	+1
`cases`	2459	2397	-62
`dashboard`	1204	1145	-59
`datasetQuality`	1145	1146	+1
`discover`	2225	2162	-63
`elasticAssistant`	567	568	+1
`entityStore`	579	580	+1
`inbox`	47	48	+1
`indexManagement`	1113	1114	+1
`infra`	1965	1902	-63
`lens`	1861	1798	-63
`links`	248	190	-58
`observabilityAIAssistantApp`	890	827	-63
`securitySolution`	11345	11346	+1
`streamsApp`	2718	2719	+1
`triggersActionsUi`	2005	2006	+1
`unifiedDocViewer`	1155	1092	-63
total			-713

Async chunks

Total size of all lazy-loaded chunks that will be downloaded as the user navigates the app

id	before	after	diff
`agentBuilder`	2.2MB	2.0MB	-199.7KB
`agentBuilderDashboards`	408.3KB	163.4KB	-245.0KB
`agentBuilderVisualizations`	398.8KB	153.8KB	-245.0KB
`apm`	3.4MB	3.2MB	-245.2KB
`cases`	2.6MB	2.4MB	-245.3KB
`dashboard`	1.2MB	952.7KB	-244.9KB
`discover`	2.0MB	1.8MB	-247.5KB
`infra`	1.5MB	1.3MB	-245.3KB
`lens`	2.1MB	1.9MB	-247.3KB
`maps`	3.2MB	3.2MB	+81.0B
`observability`	2.4MB	2.4MB	-301.0B
`observabilityAIAssistantApp`	680.6KB	436.1KB	-244.5KB
`profiling`	368.1KB	368.1KB	-6.0B
`unifiedDocViewer`	866.7KB	621.8KB	-244.9KB
total			-2.6MB

Page load bundle

Size of the bundles that are downloaded on every page load. Target size is below 100kb

id	before	after	diff
`agentBuilder`	45.5KB	45.5KB	-1.0B
`agentBuilderDashboards`	7.1KB	7.0KB	-113.0B
`agentBuilderVisualizations`	6.6KB	6.6KB	-51.0B
`apm`	48.5KB	48.4KB	-17.0B
`dashboard`	19.0KB	19.0KB	+55.0B
`discover`	30.4KB	30.2KB	-147.0B
`infra`	54.0KB	54.0KB	-15.0B
`lens`	92.2KB	92.3KB	+55.0B
`observability`	104.2KB	104.1KB	-60.0B
`observabilityAIAssistantApp`	16.3KB	16.3KB	-15.0B
`unifiedDocViewer`	14.8KB	14.7KB	-15.0B
total			-324.0B

Unknown metric groups

async chunk count

id	before	after	diff
`observability`	36	34	-2

History

cc @nickofthyme

nickofthyme added release_note:skip Skip the PR/issue when compiling release notes backport:version Backport to applied version labels v9.5.0 v9.4.1 labels May 8, 2026

move ZodObjectType to kbn-zod package

30b51c7

nickofthyme force-pushed the zod-ftw branch 2 times, most recently from 8e810b9 to ade88c6 Compare May 13, 2026 21:50

migrate all as-code dependent schemas to zod

e746cd3

nickofthyme force-pushed the zod-ftw branch from ade88c6 to e746cd3 Compare May 13, 2026 21:53

kibanamachine and others added 3 commits May 13, 2026 22:01

Changes from node scripts/lint_ts_projects --fix

fed6210

Changes from node scripts/regenerate_moon_projects.js --update

e1d5f8f

Merge branch 'main' into zod-ftw

5e2af4c

nickofthyme added v9.4.2 and removed v9.4.1 labels May 13, 2026

markov00 added reviewer:claude PR review and comments with Claude reviewer:macroscope PR review with Macroscope reviewer:codex PR review and comments with Codex labels May 14, 2026

This comment was marked as resolved.

Sign in to view

fix schema issue

167ce48

This comment was marked as resolved.

Sign in to view

Merge branch 'main' into zod-ftw

90f3886

This comment was marked as resolved.

Sign in to view

nickofthyme added 2 commits May 14, 2026 15:39

update .meta modifiers to be last per best practice

4eaed40

add missed strict modifiers

c47caf7

nickofthyme commented May 14, 2026

View reviewed changes

use stringbool instead of coerce.boolean

1c4e81e

Co-authored-by: Nick Partridge <nick.ryan.partridge@gmail.com>

This comment was marked as resolved.

Sign in to view

nickofthyme added 2 commits July 22, 2026 11:01

fix availability usage in zod

98cdc04

Merge branch 'main' into zod-ftw

a9ca3a9

nreese approved these changes Jul 22, 2026

View reviewed changes

fix merge errors

8c2fee6

github-actions Bot mentioned this pull request Jul 22, 2026

[aw] Scout Test Reviewer produced no safe outputs #280272

Open

nickofthyme mentioned this pull request Jul 23, 2026

[*as-Code] Reduce Zod schema startup memory pressure #280296

Open

nickofthyme added 2 commits July 22, 2026 20:29

fix discover session status code change

0299799

Merge branch 'main' into zod-ftw

e4bbc53

github-actions Bot reviewed Jul 23, 2026

View reviewed changes

AlexGPlay approved these changes Jul 23, 2026

View reviewed changes

[ML] Fix criteria field typing (#11)

dd45acf

github-actions Bot reviewed Jul 23, 2026

View reviewed changes

smith approved these changes Jul 23, 2026

View reviewed changes

nickofthyme added 2 commits July 23, 2026 17:09

Merge branch 'main' into zod-ftw

85ce586

github-actions Bot reviewed Jul 24, 2026

View reviewed changes

nickofthyme and others added 4 commits July 23, 2026 20:08

align original unknowns behavior

ea7e974

Use root-level .strip() in place of previous stripUnknownKeys val…

bcc3374

…idation option

replace .strict() calls with .strip() to satisfy .and() compati…

c8d3f1d

…bility

Changes from make api-docs

516b718

markov00 approved these changes Jul 24, 2026

View reviewed changes

rbrtj approved these changes Jul 24, 2026

View reviewed changes

nickpeihl reviewed Jul 24, 2026

View reviewed changes

nickpeihl approved these changes Jul 24, 2026

View reviewed changes

nickpeihl mentioned this pull request Jul 24, 2026

[As Code] Stringify zod panel warnings on dropped panels from dashboards #280806

Draft

dej611 approved these changes Jul 24, 2026

View reviewed changes

nickofthyme added 3 commits July 24, 2026 15:44

fix type errors

617153a

Merge branch 'main' into zod-ftw

6dcf0d4

update test assertions

ac80916

Value	`z.number()`	`z.coerce.number()`	`schema.number()`
`0`	`0`	`0`	`0`
`'0'`	Error	`0`	`0`
`1`	`1`	`1`	`1`
`'1'`	Error	`1`	`1`
`'1.23'`	Error	`1.23`	`1.23`
`1.23`	`1.23`	`1.23`	`1.23`
`'two'`	Error	Error	Error
`false`	Error	`0`	Error
`true`	Error	`1`	Error

		// For now, we use `z.any()` to allow flexibility in the params field.
		params: z.any().optional(),

		// TODO: enforce Serializable type, see https://github.com/elastic/kibana/pull/269196
		config: z.object({}).loose() as z.ZodType<{}>,

Uh oh!

Conversation

nickofthyme commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why change all schemas?

Reviewing

Checklist

Identify risks

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

nickofthyme left a comment

Choose a reason for hiding this comment

Uh oh!

nickofthyme May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

nreese left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

AlexGPlay left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

smith left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markov00 left a comment

Choose a reason for hiding this comment

Uh oh!

nickpeihl Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nickpeihl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

nickofthyme commented May 8, 2026 •

edited

Loading

nickofthyme May 14, 2026 •

edited

Loading

nickpeihl Jul 24, 2026 •

edited

Loading

nickofthyme Jul 24, 2026 •

edited

Loading