Debug OAS

Overview

Use node ./scripts/validate_oas_docs.js to validate Kibana OAS, but always scope output with --path so developers can focus on the API area they are actively changing.

Use this skill when the developer needs issue breakdown, categorization, or representative examples. For quick pass/fail only, use validate-oas first.

If results look stale or surprising, refresh generated OAS first using the environment setup flow in validate-oas. Treat stale oas_docs as a setup problem, not a debugging conclusion.

The validator can surface two broad categories of issues:

• structural: invalid OAS problems that usually block correctness, such as schema violations, invalid shapes, unresolved references, or mismatches between path definitions and the spec structure.
• quality: documentation completeness problems such as missing description, summary, example, or examples.

When reporting results, always separate these categories. Lead with structural issues first.

Required interaction flow