OpenAPI: Lint, Format and Structure a Maintainable API

OpenAPI: Lint, Format and Structure a Maintainable API

operationId, tags, error responses: practical rules that prevent spec debt when you lint and format OpenAPI files online.

09.08.2026
8 min read
Share this article:
openapilintformatapi-designRESTTutorial

Linting and formatting OpenAPI specs before merging

A spec can pass schema validation yet still ship without operationId, missing tags, or only a default response. That technical debt shows up weeks later, when SDK generators, API portals, or contract tests fail silently. Formatting alone does not fix those gaps, while linting catches the style and completeness rules that validators ignore. FastMinify's online OpenAPI linter applies a fixed Spectral-style subset to path operations, entirely in your browser. Pair it with the OpenAPI formatter for readable PR diffs and the OpenAPI validator for schema conformance. If structural errors block you first, start with our OpenAPI validation guide, then explore the API tools hub.

Catch missing operationId, tags, and 2xx responses before SDK or portal generation
Spectral-style subset: info-contact, paths-kebab-case, operation-description, and more
Format JSON or YAML for stable PR diffs, with optional recursive key sort
100% local: specs never leave the browser, which suits internal contracts
Recommended chain: validate → format → lint → commit

Honest limits and maintainable API design

What lint-openapi does not do

A No blocking issues result means no issues in the v1 rule subset, not that your API is production-ready or fully documented.

No security testing (auth flows, scope enforcement)
No runtime contract testing against live endpoints
No automatic multi-file bundling: paste one self-contained spec per run
No Swagger 2.0 support: OpenAPI 3.x only
Warnings do not block a “Valid with warnings” result, so treat them as merge blockers if your team policy says so
operationId, tags, and error responses

These fields prevent spec debt that validators miss but generators and portals require.

operationId: stable, unique, camelCase, and never renamed without a deprecation plan
tags: group by domain or bounded context to match your developer portal sections
2xx responses: lint enforces their presence, so add explicit 400, 401, 404, and 500 responses with schemas where clients need them
info.description and info.contact: lint warns when they are missing, so fill them in for external APIs
Path naming: prefer /pet-orders to /petOrders, since the kebab-case rule aligns with REST conventions
When to escalate to CI tooling

Browser tools speed up feedback, while pipelines enforce org-wide policy.

Custom Spectral rulesets (naming, security headers, pagination patterns)
Breaking-change detection between spec versions
Bundling multi-file specs with external $ref resolution
Gateway-specific import validation (AWS API Gateway, Kong plugins)
Document the OpenAPI target version (3.0 vs 3.1 JSON Schema draft) in the repo README

Validate, format, then lint in a design-first workflow

Three tools, three intents

Do not swap steps during review, because each tool answers a different question about your OpenAPI file.

Validate (validate-openapi): OpenAPI 3.x schema conformance via Scalar, with a valid or invalid verdict
Format (format-openapi): indentation and readability, without fixing semantic or style gaps
Lint (lint-openapi): Spectral-style rules on path operations, with warnings and errors kept apart from schema validation
Recommended order: validate → format → lint before merge
JSON syntax alone is not enough, so see the validation guide for schema versus lint
Lint rules in v1 (Spectral-style subset)

FastMinify lint is not full Spectral. It ships a fixed rule set focused on maintainable path operations (ADR-OAS-009).

not-openapi (error): the root must be OpenAPI 3.x with an info object, as an entry check before the other rules
info-contact (warning): info.contact should be present
info-description (warning): non-empty info.description
paths-kebab-case (warning): path segments should be kebab-case or vN
operation-operationId (warning): every operation needs a non-empty operationId
operation-tags (warning): at least one tag per operation
operation-description (warning): summary or description required
operation-success-response (error): at least one 2xx response, and default alone does not count
path-item-ref (warning): path item $ref not expanded in v1 lint
What lint does not cover (v1)

An honest scope: do not assume parity with Spectral, Redocly, or gateway policy engines.

Path operations only, so webhooks and callbacks are out of scope in v1
No custom ruleset upload: the subset is fixed and not a Spectral runner
Lint does not replace schema validation, so run validate-openapi for Scalar conformance
No fetching of external $ref URLs, so paste a self-contained spec
512 KiB input limit, so very large specs belong in CI tooling
Format for review, not for semantics

The formatter rewrites JSON or YAML with a 2 or 4 space indent and can sort keys recursively for stable diffs.

JSON in gives JSON out and YAML in gives YAML out, so the input kind is preserved
YAML comments are lost on format, so snapshot before reformatting annotated specs
Numeric openapi: 3.0 in YAML normalizes to string 3.0.0
Sorting keys helps PR review, but it is not an OpenAPI-aware reordering of sections
Invalid OpenAPI may still format if parsing succeeds, so always re-validate after heavy edits

Lint and format OpenAPI, step by step

Using the OpenAPI linter

The OpenAPI linter parses JSON or YAML (max 512 KiB), checks the not-openapi entry rule, then runs path-operation rules. The result reads No blocking issues, Valid with warnings, or Blocking issues found, and it is never a plain green when warnings exist.

Live linting in the Monaco editor after a short debounce
Issue list with rule code, level, and JSON Pointer path
Results panel: error and warning counts, plus path and operation stats
Parse errors come with line numbers when known
Swagger 2.0 documents fail the not-openapi check, so migrate to OpenAPI 3 first
Using the OpenAPI formatter

The OpenAPI formatter rewrites the document for human review. It formats automatically on paste, and the Format button (⌘↵) applies after manual edits.

Indent of 2 or 4 spaces, depending on team convention
Optional recursive key sort for stable git diffs
Shiki-highlighted output panel
Chain format → validate → lint for a full pre-merge pass
Pair it with the JSON validator if raw syntax is suspect
SDK generation blocked by a missing operationId

Your mobile pipeline generates a client from the spec, and warnings you ignored become hard failures downstream.

1

Validate schema conformance

Paste it into validate-openapi. Fix Scalar errors first, because lint will not help on a structurally invalid spec.

2

Lint the path operations

Open lint-openapi. Resolve operation-operationId and operation-tags warnings on every public endpoint.

3

Format and open the PR

Run the fixed spec through format-openapi, with key sort if your team uses stable diffs. Lint again before you commit.

An unreadable YAML diff in contract review

A designer exports minified YAML, and reviewers cannot spot accidental path renames.

1

Format for readability

Paste into format-openapi, pick a 2-space indent, and enable sort keys if the team agrees.

2

Validate, then lint

Validate with Scalar, then lint for paths-kebab-case and operation-success-response on new endpoints.

3

Document the error responses

Lint enforces the presence of a 2xx response. Add 4xx and 5xx responses with descriptions by hand for production-grade contracts, since v1 lint errors do not cover them.

PR review workflow, from design-first to merge

Recommended pre-merge checklist

Treat the browser trio as a fast gate before git push. CI remains the team's source of truth, but catching issues locally saves pipeline minutes. Run validate-openapi to fix Scalar errors, then format-openapi for a readable diff. Finish with lint-openapi to resolve errors and then warnings per team policy, and commit.

Reviewer focus areas

Beyond a green validate, ask whether operationId values are unique and stable for codegen. Ask whether tags map to your API portal navigation, and whether every operation documents at least one success response. Ask too whether common error shapes are described for client teams.

Pairing with CI and sibling tools

In CI, teams often run Spectral, openapi-cli, or Redocly with custom rulesets stricter than FastMinify v1. Combine browser lint with our CI/CD automation guide. For schema pivots, use json-schema-to-openapi and openapi-to-json-schema on the hub. To validate payloads against a schema once the contract is sound: see our JSON Schema validation guide.

Conclusion

Maintainable OpenAPI specs need more than schema validation. Lint catches the operationId, tag, and response gaps that block generators, and formatting keeps PRs reviewable. Validate first, format for humans, and lint for style, all locally before CI. Explore the API hub for JSON Schema conversion and GraphQL SDL validation when your contract work expands beyond REST.

Chain validate → format → lint before every spec PR
Treat lint warnings as merge blockers when SDK generation is in scope
Enable key sort only if the whole team agrees, because it changes diff semantics
Re-read the validation guide when Scalar errors appear before debugging lint
Move to Spectral or Redocly in CI for org-specific rules beyond the v1 subset
Share this article
Share this article: