Skip to content

[OAS] Implement support for discriminator#249078

Merged
jloleysens merged 23 commits intoelastic:mainfrom
jloleysens:oas/generate-discriminator
Jan 23, 2026
Merged

[OAS] Implement support for discriminator#249078
jloleysens merged 23 commits intoelastic:mainfrom
jloleysens:oas/generate-discriminator

Conversation

@jloleysens
Copy link
Copy Markdown
Contributor

@jloleysens jloleysens commented Jan 14, 2026 •
edited
Loading

Summary

Close #181994

Support generating OAS for @kbn/config-schema's using our new schema.discriminatedUnion type #246095

Notes

  • Force developers to define a { meta: { id: '...' } } for the objects inside a schema.discriminatedUnion so that we can generate the correct OAS. Guidance for name is as follows: <your-id>-<your-team-or-area>. The intention is that IDs are globally unique while remaining somewhat user readable as they will be surfaced in our docs.
  • Tackled a few unrelated OAS/schema chores in this PR

Conversion

Given a schema like:

    schema.discriminatedUnion('type', [
      schema.object(
        { type: schema.literal('str'), value: schema.string() },
        { meta: { id: 'my-str-my-team' } }
      ),
      schema.object(
        { type: schema.literal('num'), value: schema.number() },
        { meta: { id: 'my-num-team' } }
      ),
    ]),

Produce OAS like:

    {
      oneOf: [
        {
          $ref: '#/components/schemas/my-str-my-team',
        },
        {
          $ref: '#/components/schemas/my-num-team',
        },
      ],
      discriminator: {
        propertyName: 'type',
      }
    }
...
components: {
  schemas: {
      'my-str-my-team': {
        type: 'object',
        properties: {
          type: { type: 'string', enum: ['str'] },
        },
      },
      'my-num-team': {
        type: 'object',
        properties: {
          type: { type: 'string', enum: ['num'] },
        },
      },
    },
}

@jloleysens jloleysens self-assigned this Jan 14, 2026
jloleysens
jloleysens commented Jan 14, 2026
View reviewed changes
src/platform/packages/shared/kbn-config-schema/README.md
* [Custom validation](#custom-validation)
* [Default values](#default-values)
* [Extending object schemas](#extending-object-schemas)
- [`@kbn/config-schema` — The Kibana config validation library](#kbnconfig-schema--the-kibana-config-validation-library)
Copy link
Copy Markdown
Contributor Author

@jloleysens jloleysens Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not related to this PR, just adding missing README entry 🧹

src/platform/packages/shared/kbn-router-to-openapispec/src/process_versioned_router.test.ts
Copy link
Copy Markdown
Contributor Author

@jloleysens jloleysens Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also not related, just deleting some unused/legacy code branches

src/platform/packages/shared/kbn-router-to-openapispec/src/process_versioned_router.ts
Copy link
Copy Markdown
Contributor Author

@jloleysens jloleysens Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also not related, just deleting some unused/legacy code branches

@jloleysens
Copy link
Copy Markdown
Contributor Author

jloleysens commented Jan 15, 2026

/ci

@jloleysens
Copy link
Copy Markdown
Contributor Author

jloleysens commented Jan 15, 2026

/ci

@jloleysens
Copy link
Copy Markdown
Contributor Author

jloleysens commented Jan 15, 2026

/ci

@jloleysens
Copy link
Copy Markdown
Contributor Author

jloleysens commented Jan 16, 2026

/ci

@jloleysens jloleysens marked this pull request as ready for review January 19, 2026 10:31
@jloleysens jloleysens requested a review from a team as a code owner January 19, 2026 10:31
@jloleysens jloleysens added Team:Core Platform Core services: plugins, logging, config, saved objects, http, ES client, i18n, etc t// release_note:skip Skip the PR/issue when compiling release notes backport:skip This PR does not require backporting Feature:OAS Work or issues related to Core-provided mechanisms for generating OAS labels Jan 19, 2026
@elasticmachine
Copy link
Copy Markdown
Contributor

elasticmachine commented Jan 19, 2026

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

@lcawl
Copy link
Copy Markdown
Member

lcawl commented Jan 19, 2026

Is it possible to also add support for an optional "title" value alongside the "id" value (to map to the https://spec.openapis.org/oas/v3.0.3#schema-object title property)? As shown in https://www.elastic.co/docs/api/doc/kibana/operation/operation-post-alerting-rule-id#operation-post-alerting-rule-id-body-application-json-params, the tab labels in our published docs currently default to the schema id (my-str-my-team and my-num-team in this example). As soon as next week there will be changes on the publishing site such that if a "title" exists that'll be used instead of the schema ID, which should make for more readable tab labels. If this needs to be deferred to a later PR that's fine too.

@jloleysens jloleysens mentioned this pull request Jan 20, 2026
Closed
@jloleysens
Copy link
Copy Markdown
Contributor Author

jloleysens commented Jan 20, 2026

Yeah that sounds really useful @lcawl , I've added this as a follow up to reduce the surface area of this PR:

#249655

gsoldevila
gsoldevila reviewed Jan 23, 2026
View reviewed changes
src/platform/packages/shared/kbn-config-schema/src/oas_meta_fields.ts Outdated
'x-oas-get-additional-properties' as const;
export const META_FIELD_X_OAS_DEPRECATED = 'x-oas-deprecated' as const;
export const META_FIELD_X_OAS_DISCRIMINATOR = 'x-oas-discriminator' as const;
export const META_FIELD_X_OAS_DISCRIMINATOR_CATCH_ALL = 'x-oas-discriminator-catch-all' as const;
Copy link
Copy Markdown
Member

@gsoldevila gsoldevila Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC this is similar to the default: case in the context of a switch() { ... } statement.
I wonder if the catch-all naming won't be a bit missleading, in the sense that it is not catching errors.

Copy link
Copy Markdown
Contributor Author

@jloleysens jloleysens Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, naming stuff is tricky, happy to go with another name here! FWIW this should not be surfaced to end users of the docs in any way.

Copy link
Copy Markdown
Contributor Author

@jloleysens jloleysens Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed to

export const META_FIELD_X_OAS_DISCRIMINATOR_DEFAULT_CASE =
  'x-oas-discriminator-default-case' as const;

@elasticmachine
Copy link
Copy Markdown
Contributor

elasticmachine commented Jan 23, 2026

💛 Build succeeded, but was flaky

Failed CI Steps

Test Failures

  • [job] [logs] FTR Configs #125 / Agent Builder agents Edit agent should edit agent name

Metrics [docs]

Async chunks

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

id before after diff
lens 2.0MB 2.0MB +166.0B
observability 1.8MB 1.8MB +166.0B
securitySolution 10.8MB 10.8MB +161.0B
stackConnectors 1.1MB 1.1MB +161.0B
total +654.0B

History

cc @jloleysens

@jloleysens jloleysens enabled auto-merge (squash) January 23, 2026 16:13
@jloleysens jloleysens merged commit e281447 into elastic:main Jan 23, 2026
15 of 16 checks passed
@jloleysens jloleysens deleted the oas/generate-discriminator branch January 27, 2026 10:13
@jloleysens jloleysens mentioned this pull request Feb 6, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@gsoldevila gsoldevila gsoldevila approved these changes

Assignees

@jloleysens jloleysens

Labels

backport:skip This PR does not require backporting Feature:OAS Work or issues related to Core-provided mechanisms for generating OAS release_note:skip Skip the PR/issue when compiling release notes Team:Core Platform Core services: plugins, logging, config, saved objects, http, ES client, i18n, etc t// v9.4.0

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[OAS] Support discriminator

5 participants

@jloleysens @elasticmachine @lcawl @gsoldevila @kibanamachine