OpenAPI Validation Errors: Path Parameters and $ref
Short answer: most OpenAPI validation errors come from a small set of reasons: a path parameter that is not marked required: true, a $ref that points to nothing, or a required list naming a property that the schema never defines. Paste the document into the OpenAPI Validator and it lists each problem as an error or a warning, with a line number for JSON and an approximate one for YAML.
What the validator checks
The tool checks the structure of OpenAPI 3.0 and 3.1 documents, in JSON or YAML. Among other things it reports:
- path parameters that are missing
required: true; $refvalues that cannot be resolved inside the document;- entries in a schema's
requiredlist that are not declared underproperties.
Swagger 2.0 files are detected, but not validated as OpenAPI 3.
The three errors you will see most
1. A path parameter without required: true
If the path is /users/{id}, the id parameter must be declared with in: path and required: true, because a path segment cannot be left out.
parameters:
- name: id
in: path
required: true
schema:
type: string
2. An unresolved $ref
A $ref such as #/components/schemas/User must point at something that exists. The usual causes are a typo, a schema that was renamed, or one that was never added. Check the exact spelling and letter case of every segment.
3. A required property that is not defined
If required: [id, email] is written but properties only defines id, the document describes an object that cannot be built. Either add the property or remove it from required.
Errors, warnings and line numbers
Errors are things that make the document invalid. Warnings are things worth a look. For JSON the line numbers are exact. For YAML they are marked as approximate, so use them to find the neighbourhood, then read the lines around it.
How to find OpenAPI validation errors with the OpenAPI Validator
- Open the OpenAPI Validator.
- Paste your JSON or YAML document.
- Read the errors first, then the warnings.
- Fix one problem at a time and validate again, because one mistake can hide others.
If the YAML will not even parse, fix that first: see the YAML syntax errors guide. For JSON that will not parse, see JSON syntax errors.
Limits to know
- This is not a full implementation of the OpenAPI specification. A clean result means the checks it performs found nothing, not that every rule is satisfied.
- Swagger 2.0 is detected only.
- YAML line numbers are approximate.
- Everything runs in your browser.
Frequently asked questions
Why must a path parameter be required: true?
Because the value is part of the URL itself, so a request cannot leave it out.
What does an unresolved $ref mean?
The reference points to a location in the document that does not exist.
Does the validator support OpenAPI 3.1? Yes, 3.0 and 3.1 are checked. Swagger 2.0 is only detected.
Are the YAML line numbers exact? No. JSON line numbers are exact; YAML ones are approximate.
Can I check AI-written code against my spec? Yes. The API Hallucination Check compares code with your OpenAPI document.
Related tools and guides
- JSON Schema Validator
- API Hallucination Check
- YAML Validator
- JSON Validator
- AI hallucinated packages guide