A short piece of fiction, written by API Evangelist. The reader is imagined; the post, and every number and quotation from it, is real: "Twelve OpenAPI Validators And The Rules None Of Them Check," Kin Lane, November 13, 2026, https://apievangelist.com/2026/11/13/twelve-openapi-validators-and-the-rules-none-of-them-check/
Marisol read the post on Friday afternoon, after the deploy freeze started and the Slack channel went quiet. She maintains the API tooling for a freight-forwarding company's platform team, and for years she had treated the word valid as a closed matter. Her CI job ran a linter on every pull request. Green meant ship.
The opening question stung a little. The author asks what a validator has actually checked when it says your document is valid, and admits to assuming the answer for years. Marisol had assumed it too, and she had never said so out loud.
She read the table of twelve tools and found her linter in the middle of the pack. That didn't bother her. Her team had never picked it for its rank. What held her attention was the second table, the one about rules that live only in the specification's prose. Duplicate operationIds, unresolved references and path variables with no matching parameter were all things she'd have sworn her pipeline caught. Mostly it did. Then she reached the last row and read the line twice: "No tool catches a link that points at an operation that isn’t there."
Her own spec used links heavily. Order creation pointed at shipment tracking, and tracking pointed at proof of delivery. Someone renames an operation, the link goes stale, and nothing complains.
She also felt a flicker of resistance, and she let herself notice it. The cases are the author's and the OpenAPI Initiative's, and the post says as much. A pass rate on 304 documents isn't her pipeline. She half agreed with the line "A tool can score well here and still be the wrong choice for your pipeline." Her team cared about readable error messages and speed on a very large spec, and the post openly doesn't measure either. She was tempted to file the whole thing under interesting but not my problem.
But the security row kept pulling her back. Only two tools flag a requirement that names an undeclared scheme, and the linter she used sees it only as a warning. Her CI treated warnings as noise. She scrolled through the last month of builds in her head and could not say whether she'd ever seen one.
So she did something small. She copied her main spec to a scratch folder, changed one link so its operationId pointed at a name that didn't exist, and ran her normal CI command on it. It passed, and it said nothing at all. Then she renamed a security scheme in a single requirement and ran it again. This time there was a warning, which was exactly what she'd feared.
She didn't rewrite her pipeline or open a debate with her team. She left a note in the repository's tooling file recording the two broken copies and what her linter said about each, and she added a task to the next sprint to promote that one warning to an error. Then she closed the laptop and went to find coffee.