OpenAPI JSON Validator

Common JSON mistakes behind a failed check

JSON is stricter than YAML, so most failures on a hand-edited file come from syntax rather than from the API design. The usual causes are a trailing comma after the last property, single quotes instead of double quotes, a comment (JSON does not allow them), or a missing closing brace after a long paths object. A broken file typically ends in the message “Could not parse as JSON or YAML”, or in missing-field errors because nothing usable was read.

If you only see a parse error, find the syntax slip first. The structural checks run once the document reads as an object.

A worked example

Take this small document:

{
  "openapi": "3.0.3",
  "info": { "title": "Orders API" },
  "paths": {
    "orders": { "get": { "summary": "List orders" } }
  }
}

It parses, and the openapi field and paths object are present. The report would still show:

Because there is one error, the document is not reported as valid. Add "version": "1.0.0" to info and rename the key to /orders. A second run clears both findings.

What a pass does and does not mean

A clean report means the skeleton is right. It does not follow $ref links, check schemas or confirm that every operation has responses. Treat it as a quick gate before you commit the file, then run a full linter for deeper rules.

A practical workflow for JSON specs

Keep the spec in version control and paste it here before each commit that touches paths. Because the check is quick, it works as a sanity step after merging changes from several people, when duplicated keys or a misplaced brace are most likely. If your JSON is generated by a build script, paste the generated output rather than the template, so you test what readers will actually receive. When the report is clean, share the file or hand it to a documentation generator with more confidence that the top-level structure is sound.