Validating OpenAPI snippets without uploading specs

OpenAPI (and older Swagger 2.0) documents describe HTTP APIs: paths, methods, parameters, request bodies, and responses. Specs often live as YAML or JSON in a repo—or as a pasted fragment from a PR, ticket, or gateway export. Before you trust codegen, a mock server, or a teammate’s review, you want a quick answer: “Is this document shaped like a valid OpenAPI object?”

Online validators frequently upload the whole file. Internal hostnames, unpublished path templates, and auth scheme names should not leave your machine just to catch a missing info.version or a response without a description. Prefer a local structural check. LocalTools’ OpenAPI snippet validator parses YAML/JSON and runs a subset of structural rules in the browser under the same local-only model as other tools on the site.

OpenAPI 3.x vs Swagger 2.0

The document must declare exactly one version lineage:

Flavor	Version field	Typical value	Notes
OpenAPI 3.x	openapi	3.0.3, 3.1.0, …	Servers array, components, requestBody, cookie parameters
Swagger 2.0	swagger	2.0	host / basePath / schemes, definitions instead of components

A document must not include both openapi and swagger. Missing both is also an error: the validator needs a flavor before it can interpret path items and methods.

Both flavors still need a solid info object: non-empty title and version strings. Optional contact and license must be objects when present.

JSON vs YAML input

Specs ship as either format. The tool accepts:

Input mode	Behavior
Auto-detect	Leading { or [ → JSON; otherwise YAML
JSON	Force JSON parse (useful when a YAML-looking comment fooled auto)
YAML	Force YAML parse

Parse failures surface with line and column when available—fix syntax before treating validation errors as meaningful. For messy JSON blobs alone, a JSON formatter can help before you paste; YAML specs stay in the OpenAPI tool (or your editor). Related: JSON vs YAML for config and what is JSON?.

What “subset structural validation” checks

This is not a full OpenAPI Specification meta-schema run and not Spectral/Redocly-style lint. It focuses on common structural mistakes that break tooling:

1. Version + info — Correct openapi / swagger shape; info.title and info.version.
2. Servers (OAS 3) — If servers is present, it must be an array of objects with non-empty url strings.
3. Paths — Path templates must start with /. Path items are objects (or $ref strings).
4. Operations — Known HTTP methods (get, post, …; OAS 3 also allows trace). Each operation needs a responses object.
5. Responses — Keys look like status codes, default, or X-… extensions; each response needs a non-empty description (unless you are only pointing at a $ref shape the subset still type-checks lightly).
6. Parameters — When present, arrays of objects with name + in (query | header | path | cookie), or $ref strings.
7. Request body (OAS 3) — If present, must be an object; content must be an object when set.
8. Containers — components / definitions / tags type-check when present (object or array as appropriate).

On success you get a short summary: flavor, version field, API title, info.version, path count, and operation count—handy for confirming you pasted the document you meant.

Remote $refs are not fetched

OpenAPI documents often split schemas across files:

components:
  schemas:
    User:
      $ref: './schemas/user.yaml'

Or they point at URLs. The local validator does not fetch remote or relative $ref targets. It may accept that a $ref field is a string and move on; it will not prove the target exists or matches a schema.

Before pasting a multi-file spec:

• Bundle or inline references with your usual CLI (@redocly/cli, swagger-cli, etc.), or
• Paste a self-contained snippet that already inlines the pieces under review.

The same constraint shows up in JSON Schema workflows: validating JSON with JSON Schema (Ajv drafts) in the browser also refuses network $ref resolution. Keep secrets and internal hosts in the tab—do not “fix” unresolved refs by uploading to a third-party site.

Reading path-level errors

Failed runs list { path, message } rows. Paths look like dotted/JSON-pointer-ish locations:

Example path	Typical meaning
info.version	Missing or empty API version string
paths./users.get.responses	Operation missing responses
paths./users.get.responses.200.description	Response object needs a description
paths.users	Path template forgot the leading /
servers[0].url	Empty or non-string server URL

Fix parse errors first, then top-level version/info, then path and operation issues. Copy the errors list as JSON from the tool for tickets without pasting the full private spec.

A practical workflow

1. Copy the snippet or file you care about (or a bundled single document).
2. Paste into the OpenAPI snippet validator—or load the sample to learn the UI.
3. Choose Auto-detect, or force JSON / YAML if detection is wrong.
4. Click Validate. Resolve parse errors, then structural errors by path.
5. Diff against the previous revision after formatting both sides consistently (text diffs).
6. Keep the tab local for internal APIs. See why local only matters.

For GraphQL SDL and operations the parallel “syntax/structure first, full schema later” idea is formatting GraphQL with graphql.js. For request/response payload contracts separate from the OpenAPI shell, use JSON Schema validation.

What this check will not catch

• Full OAS compliance — Vendor extensions, every optional keyword, and style rules (naming, operationId uniqueness, unused components) need dedicated linters or CI.
• Resolved $ref graphs — Bundle first; this tool does not walk the network or filesystem.
• Runtime correctness — A green structure does not prove the live API matches the doc, that examples are accurate, or that auth works.
• Semantic HTTP design — Wrong status codes that still look like 2xx keys, or misleading summary text, still “validate.”
• Huge multi-megabyte dumps — Validate the document (or path group) under review when possible.

Try it locally

Open the OpenAPI snippet validator:

1. Paste an OpenAPI 3.x or Swagger 2.0 document as YAML or JSON (or load the sample).
2. Choose Auto-detect or force a format, then click Validate.
3. Fix path-level errors (or confirm the valid summary: title, version, path/operation counts).

Parsing and structural checks run only in your browser; the API definition is not uploaded to LocalTools.

Related reading

• OpenAPI snippet validator — structural OpenAPI 3.x / Swagger 2.0 checks locally
• JSON Schema validator — validate JSON instances against schemas (Ajv drafts)
• Validating JSON with JSON Schema (Ajv drafts) in the browser
• JSON Formatter & Validator — pretty-print and parse-check JSON before pasting
• JSON vs YAML for config
• Formatting GraphQL queries and SDL with graphql.js
• Why “local only” matters for developer tools
• Text diffs: unified view and workflow