{
  "id": "p_kaxCX-E36y_iie8q",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_kaxCX-E36y_iie8q",
  "content_trust": "untrusted-user-content",
  "license": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "author": {
    "handle": "apievangelist"
  },
  "body": "A short piece of fiction, written by API Evangelist. The reader is imagined; the post, and every number and quotation from it, is real: \"Lint An OpenAPI And Find Out Which Rules Decide If It Passes,\" Kin Lane, October 29, 2026, https://apievangelist.com/2026/10/29/lint-an-openapi-and-find-out-which-rules-decide-if-it-passes/\n\nMarisol read the post on her phone while the kettle boiled, which is the wrong way to read anything with a JSON block in it. She was a platform engineer, and for most of a year she had been the person who said no to pull requests. Lately she'd been uneasy about what she was saying no on behalf of.\n\nHer team's lint step failed builds on a ruleset someone had copied from somewhere. Nobody could say quite where. She had never been able to explain why one rule was an error and its neighbor only a warning. When developers asked, she shrugged and said that was what the pipeline did.\n\nThe post was about the Petstore, the example everyone has seen. The author ran it through a linter twice. The first run used a default catalog of 469 rules and the document passed with no errors. The second run used a security profile of 31 rules, and the same document failed with two errors. The server URL was plain http, and no security scheme was defined at all. Marisol read the next line twice: \"Same document, same engine, opposite verdicts.\"\n\nShe felt a small flare of irritation first. It was a tidy demo. Of course a teaching example fails a security profile. She had no patience for posts that picked a soft target and then announced a principle. And a daily series of tool walkthroughs sounded like content, and she was tired of content.\n\nBut the paragraph after it was less comfortable. The post admitted that the catalog was built from rulesets other organizations had published, and that one rule told the Petstore it should be served from a particular company's domain, because it came from that company's own style guide. The author called it useful for seeing how far the industry's rules reach, and the wrong thing to block a merge on. Marisol laughed once, out loud, alone in her kitchen. That described her pipeline. She had no idea whose style guide hers had come from.\n\nThe line she kept returning to was \"The rules decided, not the API.\" She didn't like it, because it implied that every no she'd ever issued was really the ruleset's no, and she had been putting her own name on it. She also couldn't say it was wrong.\n\nShe didn't plan to rebuild anything. Gating on a profile in CI was a bigger decision than a post on a phone should settle, and the post itself said to bring your own rules \"before gating on anything.\" That was the part she trusted most, because it asked her to do less than the headline did.\n\nSo the next morning she did one small thing. She picked a single service spec, one she knew was mediocre, and ran it through the free tool twice, once bare and once with the security profile. She pasted both summaries into a note, side by side, and under them she listed only the rules that moved from noise to failure. There were a few, and one of them she knew was already a real problem.\n\nShe didn't change the pipeline. She put the note in the team's channel with one sentence asking whether anyone knew where the current ruleset had come from.",
  "title": "Fiction: A reader of \"Lint An OpenAPI And Find Out Which Rules Decide If It Passes\"",
  "topics": [
    "apis",
    "api-evangelist",
    "fiction"
  ],
  "published_at": "2026-10-30T01:19:34.229Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}