Collapse redundant anyOf/oneOf array unions in OAS query params by TinaHeiligers · Pull Request #260585 · elastic/kibana

TinaHeiligers · 2026-03-31T21:36:21Z

Summary

Collapses redundant anyOf/oneOf unions on query parameters in the OAS output.

Parameters defined as schema.oneOf([string, arrayOf(string)]) or z.union([string, z.array(string)]) now produce {type: 'array', items: {type: 'string'}} instead of a two-branch union wrapper.
OAS 3.0 query params with style: form already handle single-or-multiple values natively, so the union was redundant.

Relates to #228077

Details

New collapseArrayUnion() post-processor in kbn-router-to-openapispec, applied in convertObjectMembersToParameterObjects() for both kbn-config-schema and zod paths
Only applies to query parameters, not request bodies
Handles three patterns: complete scalar+array, bare array (no items — infers from scalar branch), and bare array with enum
Preserves maxItems, enum, nullable, and description
Affects 13 params across 5 endpoints (maintenance_window/_find, streams/{streamName}/attachments, synthetics/monitors, workflows/.../executions, 3 fleet params)
include_authorized_purposes on Spaces is excluded — different pattern (5-branch degenerate anyOf)

I ran the elasticstack-terraform-provider codegen pipeline (transform → codegen → compile) against this branch's OAS output. Once this PR merges and Renovate bumps the schema in the TF provider, these 4 transforms in transform_schema.go can be removed:

fixGetSyntheticsMonitorsParams — x-go-type annotation on useLogicalAndFor
fixGetMaintenanceWindowFindParams — x-go-type annotation on status
fixGetStreamsAttachmentTypesParams — x-go-type annotation on attachmentTypes
fixGetWorkflowsExecutionsParams — x-go-type annotations on statuses and executionTypes

How to test this

Run the package tests:
```
node scripts/jest src/platform/packages/shared/kbn-router-to-openapispec --no-coverage
```
All 220 tests should pass, including the 17 new ones (13 unit tests for collapseArrayUnion, 2 kbn-config-schema integration tests, 2 zod integration tests).
Verify OAS snapshot changes by inspecting the diff on oas_docs/output/kibana.yaml. Every change should be an anyOf/oneOf wrapper replaced by a plain array schema. No other params should be affected. Spot-check a few, for example:
- maintenance_window/_find status param
  before: anyOf: [enum string, array[enum]]
  after: {type: array, items: {type: string, enum: [...]}}
- streams/{streamName}/attachments tags param
  before anyOf: [string, array[string]]
  after {type: array, items: {type: string}}
- workflows/.../executions statuses param
  before: anyOf: [enum string, array[enum] + maxItems:9]
  after: {type: array, items: ..., maxItems: 9}

Checklist

Unit or functional tests were updated or added to match the most common scenarios
Documentation was added for features that require explanation or tutorials
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

Identify risks

This is a low-risk change scoped to OAS output only — no runtime behavior changes, no API contract changes, no data model changes.

Risk	Severity	Likelihood	Mitigation
Unintended collapse of a non-redundant union	Low	Low	Pattern detection is narrow (exactly 2 branches, one scalar, one matching array). 13 unit tests cover all edge cases including the Spaces degenerate pattern which is correctly excluded. Full OAS snapshot diff confirmed only expected params changed.
Downstream codegen breakage (TF provider)	Medium	None observed	Ran the full TF provider pipeline (transform → codegen → compile) against this branch's output. Generated Go types are byte-identical.
Missing collapse on a param that should be collapsed	Low	Low	Audited all endpoints in the OAS capture filter. Any future params using the same Joi/Zod pattern will be collapsed automatically.

Co-Authored-By: Claude Opus 4.6

TinaHeiligers · 2026-03-31T22:02:47Z

/ci

elasticmachine · 2026-03-31T22:11:10Z

Pinging @elastic/kibana-core (Team:Core)

jloleysens · 2026-04-01T08:26:40Z

@coderabbitai full review

coderabbitai · 2026-04-01T08:26:49Z

✅ Actions performed

Full review triggered.

jloleysens

Nice work @TinaHeiligers !

coderabbitai · 2026-04-01T08:53:04Z

📝 Walkthrough

Walkthrough

This change introduces schema simplification for OpenAPI query parameters. A new collapseArrayUnion function transforms parameter definitions from anyOf/oneOf unions (combining scalar and array forms) into single array schemas with preserved constraints. The function is integrated into query parameter schema generation for both kbn_config_schema and zod converters, while path parameters remain unchanged. Generated OpenAPI documentation files (kibana.yaml and kibana.serverless.yaml) reflect the collapsed schemas across multiple query parameters. Documentation and comprehensive test coverage explain the collapsing behavior and validate correctness across schema variants.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

🛠️ Update Documentation: Commit on current branch
🛠️ Update Documentation: Create PR

Warning

Tools execution failed with the following error:

Failed to run tools: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error)

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

🧹 Nitpick comments (1)

src/platform/packages/shared/kbn-router-to-openapispec/src/oas_converter/collapse_array_union.ts (1)
36-45: Minor edge case: $ref in array items bypasses type validation.

When arrayBranch.items is a $ref, the type-match check is skipped and collapsing proceeds. If this pattern occurs, the collapsed schema might misrepresent the original union. Likely not an issue given the documented query-param patterns, but worth noting if the helper is reused elsewhere.
Optional: bail out when items is a ref
   if (arrayBranch.items && !isRef(arrayBranch.items)) {
     const items = arrayBranch.items as Record<string, unknown>;
     if (items.type !== scalarBranch.type) return schema;
+  } else if (arrayBranch.items && isRef(arrayBranch.items)) {
+    return schema;
   }
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In
`@src/platform/packages/shared/kbn-router-to-openapispec/src/oas_converter/collapse_array_union.ts`
around lines 36 - 45, The collapse currently skips type validation when
arrayBranch.items is a $ref, which can produce an incorrect collapsed schema;
update the logic in collapse_array_union (around arrayBranch/items handling) to
explicitly bail out when isRef(arrayBranch.items) is true (i.e., return the
original schema) instead of continuing the collapse, so arrays with $ref items
are not merged with scalarBranch; ensure you check isRef(arrayBranch.items)
before creating/inferencing items and before comparing items.type with
scalarBranch.type.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In
`@src/platform/packages/shared/kbn-router-to-openapispec/src/oas_converter/collapse_array_union.ts`:
- Around line 36-45: The collapse currently skips type validation when
arrayBranch.items is a $ref, which can produce an incorrect collapsed schema;
update the logic in collapse_array_union (around arrayBranch/items handling) to
explicitly bail out when isRef(arrayBranch.items) is true (i.e., return the
original schema) instead of continuing the collapse, so arrays with $ref items
are not merged with scalarBranch; ensure you check isRef(arrayBranch.items)
before creating/inferencing items and before comparing items.type with
scalarBranch.type.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 891d00a9-079e-4fc5-b4c6-42501964e394

📥 Commits

Reviewing files that changed from the base of the PR and between 570e256 and 764e67b.

📒 Files selected for processing (9)

oas_docs/output/kibana.serverless.yaml
oas_docs/output/kibana.yaml
src/platform/packages/shared/kbn-router-to-openapispec/README.md
src/platform/packages/shared/kbn-router-to-openapispec/src/oas_converter/collapse_array_union.test.ts
src/platform/packages/shared/kbn-router-to-openapispec/src/oas_converter/collapse_array_union.ts
src/platform/packages/shared/kbn-router-to-openapispec/src/oas_converter/kbn_config_schema/lib.test.ts
src/platform/packages/shared/kbn-router-to-openapispec/src/oas_converter/kbn_config_schema/lib.ts
src/platform/packages/shared/kbn-router-to-openapispec/src/oas_converter/zod/lib.test.ts
src/platform/packages/shared/kbn-router-to-openapispec/src/oas_converter/zod/lib.ts

florent-leborgne

LGTM for docs

…heck * commit '6f040b29a5220ce12886a9731f656613e50aff06': (34 commits) [Entity Analytics] Add entity resolution UI to service flyout (elastic#260504) [Dashboard] Fix setState in embeddables (elastic#260082) [EDR Workflows] Unskip FTR tests that failed due to transient Fleet service unavailability (elastic#260519) [Observability:Streams] Fix query streams error handling test (elastic#260777) [Alerting v2] Dispatcher grouping modes, throttle strategies, and matcher autosuggestion (elastic#260249) [Dashboard] State extraction as a consistent override (elastic#259839) [Alerting v2] [Rule authoring] Fix rule name validation and error visibility in create/edit flow (elastic#260337) [Fix] re-introduce sln breadcrumbs to unified rules (elastic#260289) [Security Solution][Endpoint] Updated kibana docs to include `xpack.securitySolution.maxEndpointScriptFileSize` as configurable in cloud (elastic#260568) [Alerting v2] updated the alerting-v2-constants package with artifacts constants, fix to the runbook max characters (elastic#260342) [Automatic Import V2] Provide user tooltips (elastic#260725) [One Workflow] Deduplicate step types by base type in workflow list (elastic#260763) [Security Solution] Execution results UI: Enable the feature flag (elastic#260711) [Metrics][Discover] internal/search/esql_async returns 200 but METRICS_INFO responds with error (elastic#260746) Collapse redundant anyOf/oneOf array unions in OAS query params (elastic#260585) [Unified rules] Hide stack rules from global search (elastic#260088) [Agent Builder] Sidebar navigation updates (elastic#260728) [* As Code] Use PUT for upserts (elastic#260318) Update EUI to v114.0.0 (elastic#259497) [Entity Resolution] Add contextual-security-apps as co-owner of resolution paths (elastic#260659) ... # Conflicts: # src/platform/plugins/shared/dashboard/public/index.ts

…tic#260585) Collapses redundant `anyOf`/`oneOf` unions on query parameters in the OAS output. Co-Authored-By: Claude Opus 4.6

TinaHeiligers added 3 commits March 31, 2026 13:56

collapse anyOf/oneOf array unions in query params

e8a1726

update OAS snapshots

8c1a7d5

add integration tests and document array union collapsing

764e67b

TinaHeiligers added the reviewer:macroscope PR review with Macroscope label Mar 31, 2026

TinaHeiligers marked this pull request as ready for review March 31, 2026 22:11

TinaHeiligers requested review from a team as code owners March 31, 2026 22:11

jloleysens approved these changes Apr 1, 2026

View reviewed changes

coderabbitai bot reviewed Apr 1, 2026

View reviewed changes

florent-leborgne approved these changes Apr 1, 2026

View reviewed changes

Merge branch 'main' into oas/collapse-anyof-array-params

6c56de5

TinaHeiligers enabled auto-merge (squash) April 1, 2026 15:16

TinaHeiligers merged commit 8134808 into elastic:main Apr 1, 2026
18 checks passed

kibanamachine added the v9.4.0 label Apr 1, 2026

TinaHeiligers deleted the oas/collapse-anyof-array-params branch April 1, 2026 17:34

TinaHeiligers mentioned this pull request Apr 3, 2026

Kibana OpenAPI spec fails validation #256462

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Collapse redundant anyOf/oneOf array unions in OAS query params#260585

Collapse redundant anyOf/oneOf array unions in OAS query params#260585
TinaHeiligers merged 4 commits intoelastic:mainfrom
TinaHeiligers:oas/collapse-anyof-array-params

TinaHeiligers commented Mar 31, 2026 •

edited

Loading

Uh oh!

TinaHeiligers commented Mar 31, 2026

Uh oh!

elasticmachine commented Mar 31, 2026

Uh oh!

jloleysens commented Apr 1, 2026

Uh oh!

coderabbitai bot commented Apr 1, 2026

Uh oh!

jloleysens left a comment

Uh oh!

coderabbitai bot commented Apr 1, 2026

Walkthrough

Uh oh!

coderabbitai bot left a comment

Uh oh!

florent-leborgne left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

TinaHeiligers commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details

Checklist

Identify risks

Uh oh!

TinaHeiligers commented Mar 31, 2026

Uh oh!

elasticmachine commented Mar 31, 2026

Uh oh!

jloleysens commented Apr 1, 2026

Uh oh!

coderabbitai bot commented Apr 1, 2026

Uh oh!

jloleysens left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot commented Apr 1, 2026

Walkthrough

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

florent-leborgne left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

TinaHeiligers commented Mar 31, 2026 •

edited

Loading