{
  "id": "p_AryXmKTj0T4cUToA",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_AryXmKTj0T4cUToA",
  "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: \"Check Two OpenAPI Versions For Breaking Changes, And Know What It Cannot See,\" Kin Lane, November 2, 2026, https://apievangelist.com/2026/11/02/check-two-openapi-versions-for-breaking-changes-and-know-what-it-cannot-see/\n\nMarisol maintained the OpenAPI contract for her team's internal booking service, and on Monday morning she read the post with a mug going cold beside her keyboard. She did not expect to like it. Her team's merge checks already ran a linter, and she was tired of tools that promised to tell her whether a change was safe.\n\nThe first paragraph did not oversell, which she noticed. It said \"Reading a YAML diff tells you which lines moved, not what happens to the people integrating with you.\" That was exactly her complaint about the pull request view. She had approved diffs that looked tidy and then spent a Thursday on a call with a partner.\n\nThe payment example won her over a little. A one-line change adding required: true to a request body, with info.version still at 1.0.0, and the tool returned one breaking change anyway. She liked that the post said \"compatible is a single field a pipeline can act on\". She could picture the CI step already. She also thought about how many times a version number had reassured her when it shouldn't have.\n\nThen the table made her stop. Two commits, a cvc field changing from integer to string and a booking schema gaining two required fields, both came back as compatible: true with zero changes. The author wrote \"The tool saw nothing\". Marisol read the row twice. Her service's contract had far more of its weight in components than in paths. If she had adopted this tool without reading to the end, her pipeline would have turned green on exactly the changes her partners felt most.\n\nShe was uncomfortable, and not only about the tool. A passing check changes how people behave. Her teammates would see the green mark and stop looking at the schemas, which was the opposite of what the post advised. She wondered whether a gate that was silently blind to the largest part of her contract was worse than no gate. She did not settle that. Part of her thought the honest limits made it more trustworthy than most vendor pages. Another part thought honesty in a blog post does not stop a green checkmark from being believed on a Friday afternoon.\n\nShe also disagreed, mildly, with nothing in particular and everything in general. The 3.2 gap meant the tool undercounted new surface, and her team had been talking about moving to 3.2. She wrote that on a sticky note.\n\nShe did not wire anything into CI. The post's closing advice was smaller than that, and she followed it. She pulled the last two tagged versions of her own contract from the repository and saved them as old.yaml and new.yaml. She ran the REST call from the post with jq and curl and saved the response to a file. Then she opened the plain YAML diff in the next window and went through it line by line, ticking off what the tool had mentioned.\n\nThe tool named one removed path. The diff showed four changes under components that the result never mentioned. She copied those four into a note titled for her team's channel, with the post's advice to \"review changes to your schemas separately\" at the top, and posted it before lunch.",
  "title": "Fiction: A reader of \"Check Two OpenAPI Versions For Breaking Changes, And Know What It Cannot See\"",
  "topics": [
    "apis",
    "api-evangelist",
    "fiction"
  ],
  "published_at": "2026-11-02T14:59:25.921Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}