{
  "id": "p_Gna7UHFYSloXK2uV",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_Gna7UHFYSloXK2uV",
  "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: \"How The Specifications Relate,\" Kin Lane, November 9, 2026, https://apievangelist.com/2026/11/09/how-the-specifications-relate/\n\nMarisol read the post on a Monday morning with her coffee going cold. She is a platform engineer at a mid-sized logistics company, and for three weeks her team had been stuck on the question the author says they get every week: do we need OpenAPI or MCP? Her manager wanted a decision by Friday.\n\nThe post's first claim stopped her. The author wrote that \"these specifications aren’t competing for one job.\" She had spent a month treating them as rivals, with a spreadsheet and a column for each. She felt a little foolish, then a little annoyed. If the question dissolves that easily, why had nobody said so earlier?\n\nShe kept reading. The post covers twenty specifications and 52 connections, and she liked the rule behind the map: \"Every line on the map names the property that proves it.\" She had read plenty of architecture diagrams where arrows meant whatever the drawer wanted. This one admitted that other relationships exist across the six hundred or so catalog entries and kept them on a separate page. She wished more vendors were that strict.\n\nThe section on shared schemas made her uncomfortable. The author says that when people argue about OpenAPI versus MCP, they are often arguing about \"two wrappers around the same schemas.\" Marisol half agreed. Her team had spent days on that argument, so it stung. But she thought a wrapper can still matter. An agent calling a tool at runtime is not the same as a developer reading a reference page, and the post's tidy picture seemed to flatten that. She wrote a note to herself saying so. The post had not claimed otherwise, she admitted, but it had not spent much time on it either.\n\nThe part she trusted most was the author's own admission of gaps. APIs.json has a property type for GraphQL but none for gRPC or JSON-RPC, and the author says so about their own spec. The fourteen-job table leaves out eight specifications because their cells haven't been read, and an empty cell would claim something unchecked. Marisol had never seen anyone leave a cell blank on purpose, and she found it more convincing than a full table would have been.\n\nShe also noticed the line about extensions like x-mcp and x-mcp-tool. The post says no specification defines them and the tooling does it anyway. Her team had a few of those markers sitting in an internal spec, added by someone who had since left. She had assumed they were official.\n\nHer disagreement didn't go away, but it shrank. She did not need to settle OpenAPI versus MCP by Friday. She needed to know what her team had already described at the bottom of the stack.\n\nSo she did one small thing. She opened the OpenAPI file for their shipment-tracking service, searched for operationId, and counted the operations that lacked one. Eleven did. She pasted the list into the team's thread with a single sentence: before we pick anything, these need names. Then she closed the spreadsheet with the columns and went to refill her coffee.",
  "title": "Fiction: A reader of \"How The Specifications Relate\"",
  "topics": [
    "apis",
    "api-evangelist",
    "fiction"
  ],
  "published_at": "2026-11-09T18:31:48.337Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}