Building Schema Doctor: A Tool Born From Frustration

As someone who works with APIs and automation on a daily basis, I’ve spent more hours than I care to count wrangling OpenAPI schemas. Whether it’s vendors pushing half-baked specs, autogenerated documentation riddled with issues, or circular references that throw parsers into chaos, the struggle is very real. Schema Doctor is my attempt to push back against that chaos.

What started as a simple utility to help me get work done faster has evolved into a lightweight, client-side tool that cleans up messy OpenAPI schemas. It was originally built to scratch my own itch. I needed something that could help with schema debugging, and I didn’t want to rely on slow online validators or bulky local installs just to make a few fixes.

Schema Doctor now lives on a clean static site, and I’ve begun sharing it more widely so others can get value from it too. It still has plenty of room to grow, but the core functionality already solves several major pain points in schema work.

Why Schema Validation Sucks

OpenAPI is an excellent standard on paper. It provides a consistent way to describe REST APIs, enabling everything from documentation to testing to code generation. But in practice? It’s a bit of a mess.

The problem is that not everyone uses the spec consistently. Some vendors treat it like a rough suggestion. Others lean heavily on auto-generated output from frameworks that don’t prioritize clean specs. Even open-source tools that claim OpenAPI support often fail to produce valid or usable schemas.

As someone automating workflows and integrating with third-party services, I found myself constantly:

• Chasing down syntax errors buried in thousand-line JSON files

• Hitting reference loops that break tools like Swagger UI or Postman

• Manually adding missing operation IDs just so my generator wouldn’t crash

I realized I was repeating a lot of the same cleanup steps over and over. That’s where Schema Doctor began.

What It Does

Schema Doctor is a browser-based utility that parses and fixes OpenAPI 3.0 and 3.1 schemas. It doesn’t try to be an all-in-one solution for editing or generating specs. Instead, it focuses on automating the most annoying fixes.

Here’s what it helps with right now:

• Handling Circular References
  It identifies and restructures circular $ref loops so they no longer break tools that expect trees instead of graphs.

• Fixing Syntax Errors
  It runs basic JSON parsing and schema-level checks to spot and report common formatting mistakes.

• Adding Missing Operation IDs
  For tools that require every operation to have a unique operationId, Schema Doctor can auto-generate these based on method and path.

• Flattening Complex Schemas (experimental)
  If a schema is split across multiple components with deep nesting, Schema Doctor can flatten it into a more portable format.

The best part? It all runs client-side. No uploading sensitive schema data to a third-party server, and no dependency hell. Just open the page, paste your schema, and hit the button.

Building It: Fast and Functional

Schema Doctor was built with simplicity in mind. I wanted something that could load instantly, work offline, and run in any modern browser. The tech stack reflects that:

• Plain HTML + JavaScript
  No frameworks, no dependencies, just browser-native code.

• Swagger-Parser under the hood
  For validation and parsing, I used the excellent Swagger-Parser library. It handles a lot of the heavy lifting and catches edge cases I might miss.

• Modular JS functions
  Each fix is implemented as a standalone helper, so I can continue adding new ones without overcomplicating the codebase.

There’s no user login, no telemetry, no fluff. The goal was utility, not analytics.

Why Share It?

Initially, I wasn’t planning to release Schema Doctor publicly. It felt too rough, too specific to my workflow. But the more I used it, the more I realized others might benefit too. Every time I fixed a broken schema from a new vendor, I thought, "someone else is probably hitting the same wall."

So I cleaned up the UI, added better error handling, and hosted it with GitHub Pages. Now it's live, free to use, and something I genuinely hope saves others time.

If you’re an automation nerd, an API integrator, or someone stuck cleaning up vendor garbage on the regular, give it a try. It's already helped me clean up dozens of specs and get integrations running faster.

If you’ve got a schema that breaks something and want to see if Schema Doctor can help,
You can try it out at: https://schemadoctor.com