[OAS Validation] Fix structural schema issues in Fleet APIs

[TinaHeiligers]

The Fleet API schemas have two structural issues tracked under #256462.

One DELETE operation defines a requestBody, and around 7 schemas use inline oneOf/anyOf/allOf instead of referencing named components. (Counts approximate as of April 2026; run verification steps below for current numbers.)

DELETE operation with requestBody:

Method	Path
DELETE	/api/apm/settings/agent-configuration

Inline polymorphic schemas (7 instances):

Method	Path	Location
POST	/api/fleet/agents/{agentId}/rollback	response 200
POST	/api/fleet/agents/{agentId}/privilege_level_change	response 200
GET	/api/fleet/epm/templates/{pkgName}/{pkgVersion}/inputs	response 200
POST	/api/fleet/outputs	requestBody
PUT	/api/fleet/outputs/{outputId}	requestBody
POST	/api/fleet/package_policies	requestBody
PUT	/api/fleet/package_policies/{packagePolicyId}	requestBody

Verification:

node scripts/capture_oas_snapshot --no-serverless --include-path /api/fleet --include-path /api/apm
node scripts/validate_oas_snapshot

After the OAS snapshot validates, coordinate with @elastic/kibana-core to verify downstream client generation isn't affected. The tooling for scriptable codegen verification is tracked in #262361.

Part of #256462

[elasticmachine]

Pinging @elastic/fleet (Team:Fleet)

[TinaHeiligers]

Discriminator coverage gap (audit 2026-04-27)

34 polymorphic-object unions across /api/fleet/* are emitted without discriminator in both kibana.yaml and kibana.serverless.yaml, spread across 20 paths. Largest contributors:

Unions	Path
3	/api/fleet/package_policies/{packagePolicyId} (GET / PUT x2)
3	/api/fleet/package_policies (GET / POST x2)
3	/api/fleet/outputs/{outputId} (GET / PUT x2)
3	/api/fleet/outputs (GET / POST x2)
2	/api/fleet/package_policies/upgrade/dryrun
2	/api/fleet/epm/packages/{pkgName}/{pkgVersion}
2	/api/fleet/epm/packages/{pkgName}
2	/api/fleet/epm/packages/_bulk
2	/api/fleet/agent_policies/{agentPolicyId}
2	/api/fleet/agent_policies

Long tail of single-union routes across agents, epm, and package_policies.

Fix: migrate the polymorphic shapes from plain schema.oneOf() to schema.discriminatedUnion('propertyName', [..., { meta: { id } }]). The meta:{id} work tracked in #261258 is the prerequisite. See cross-cutting root-cause comment on #256462.

[criamico]

@kpollich reading this comment it says:

The meta:{id} work tracked in #261258 is the prerequisite

should we tackle #261258 before this one? I don't see it in the sprint

[kpollich]

Ah good call @criamico - I switched the two issues when I scheduled this one. I've pulled #261258 into the sprint and marked it as blocking this one.

[criamico]

Discriminator gap — resolution status (2026-05-27)

After two PRs (#270560 — meta:{id} rollout, #271407 — discriminatedUnion migration):

Unions	Path	Before	After
3	/api/fleet/outputs	3	✅ 0 (3 discriminated)
3	/api/fleet/outputs/{outputId}	3	✅ 2 discriminated + 1 remaining (PUT — type optional in update, breaking to require)
3	/api/fleet/package_policies/{packagePolicyId}	3	1 remaining (full vs simplified format, no shared literal discriminator)
3	/api/fleet/package_policies	3	1 remaining (same)
2	/api/fleet/package_policies/upgrade/dryrun	2	1 remaining (same)
2	/api/fleet/epm/packages/{pkgName}/{pkgVersion}	2	✅ 0
2	/api/fleet/epm/packages/{pkgName}	2	✅ 0
2	/api/fleet/epm/packages/_bulk	2	✅ 0
2	/api/fleet/agent_policies/{agentPolicyId}	2	✅ 0
2	/api/fleet/agent_policies	2	✅ 0
1	/api/fleet/agents/{agentId}/rollback	1	1 remaining (branches share no common property — requires adding synthetic discriminator field + handler change)
1	/api/fleet/agents/{agentId}/privilege_level_change	1	1 remaining (same)
~10	long tail across agents, epm, package_policies	~10	✅ 0
34	Total	34	6 remaining

The 6 remaining unions are all verified ineligible without schema reshaping or breaking API changes. I opened a follow up to track the remaining work: #271410