OpenAPI 3 · Reference validator
OpenAPI $ref & operationId validator A reference check for JSON specs, not a full schema validator
Drop one OpenAPI 3 JSON file. findings.csv lists each local $ref that points nowhere, each operation without an operationId and each remote $ref. endpoints.csv lists every operation. What it leaves out
or drop it here
YAML or pasted text? Check the syntax and turn it into JSON in your browser first
- Paste the spec into the Config Format Converter. It runs in your browser, nothing is uploaded, and it shows YAML or JSON syntax errors with line numbers.
- Choose JSON as the output and download the file.
- Drop that .json file above for the $ref and operationId check.
Free: 3 checks a dayPro: €12.99/month
- 3 endpoints
- 3 $refs checked
- 2 findings
In the spec
paths./orders.posthas nooperationIdpaths./orders/{id}.getresponse schema is{"$ref": "#/components/schemas/Invoice"}components.schemascontains onlyOrder
findings.csv
- ErrorBROKEN_LOCAL_REF
#/components/schemas/Invoice - WarningOPERATION_ID_MISSING
POST /orders
endpoints.csv
| Path | Method | Operation ID |
|---|---|---|
/orders | get | listOrders |
/orders | post | empty |
/orders/{id} | get | getOrder |
Download: findings.csv · endpoints.csv · manifest.json
What it checks and what it leaves out
Checked
- The
openapifield is a 3.x version. Swagger 2.0 files get an OPENAPI_VERSION error. - A
pathsobject exists. - Every get, post, put, patch, delete, head and options operation has an
operationId. - Every
$refstarting with#/resolves inside the same file. - Every other
$refis listed as REMOTE_REF_BLOCKED and never fetched.
Not checked
- The document against the OpenAPI schema: types, required fields, parameters, responses.
- Duplicate operationIds.
- YAML files and pasted text directly. Convert them to .json in your browser first.
- Line numbers. Findings name the missing target or the operation.
Need full schema validation? Check the file against the official schema listed in the OpenAPI Specification and its JSON Schemas, or run a schema validator in your build. This check is a quick first pass before that step.
How the check works
- 1
Add the JSON file
One OpenAPI 3 file with up to 10,000 operations. There are no settings. A free account is needed.
- 2
References are resolved
Every $ref in the file is collected. Local pointers are followed inside the document, remote ones are listed and not fetched.
- 3
Download three files
findings.csv with every problem, endpoints.csv with every operation, and manifest.json with a record of the source.
Reading the results
findings.csv
Each row has a severity, a code and the evidence. BROKEN_LOCAL_REF and REMOTE_REF_BLOCKED are errors and show the $ref value. OPERATION_ID_MISSING is a warning and shows the method and path, such as POST /orders. The file does not give line numbers, so search your spec for the listed pointer or path to find each spot. A wrong version marker or a missing paths object shows up as an error at the top.
endpoints.csv
One row per operation with its path, method and operationId. Operations without an ID keep an empty cell, which makes them easy to filter in a spreadsheet. Fix the listed spots and run the file again to confirm they are gone.
manifest.json
It records the file name, size and SHA-256 hash of the file you sent, the summary counts, all findings and the hashes of the result files.
Questions before you run it
Does it read OpenAPI YAML, or can I paste the spec?
The check itself reads one .json file. For YAML or pasted text, paste the spec into the free Config Format Converter on WoluTools. It runs in your browser, nothing is uploaded, and it shows syntax errors with line numbers. Pick JSON as the output, download the file and drop it here. YAML anchors and aliases (&, *) are not supported by the converter, so expand them first.
What counts as a broken local reference?
A $ref that starts with #/ and does not resolve to a node in the same file, for example #/components/schemas/Invoice when components.schemas has no Invoice. findings.csv lists it as BROKEN_LOCAL_REF with the pointer as evidence. It gives no line number, so search your spec for the pointer to find each place that uses it.
What happens to references to other files or URLs?
Any $ref that does not start with #/ is not fetched. It is listed as REMOTE_REF_BLOCKED, so the check never pulls content from another host. Bundle external files into one document first if you want those targets checked.
Does it validate the full OpenAPI schema?
No. It checks the openapi version marker (3.x), the paths object, operationIds and local $ref targets. Types, required fields, parameters and response objects are not validated, so a file can pass here and still fail full schema validation against the official OpenAPI JSON Schema.
What is in endpoints.csv?
One row per operation (get, post, put, patch, delete, head, options) with the columns Path, Method and Operation ID. The Operation ID cell stays empty where none is set, and findings.csv lists that operation as OPERATION_ID_MISSING.