Your API spec should fit in your head.

Open your biggest OpenAPI file. Scroll. Keep scrolling.

Somewhere past line 800, a question worth asking: how did describing a pet store come to require 22,000 characters of YAML? I once counted what's actually contract in that file — names, types, statuses, prose. About a third. The rest is scaffolding: in: query, required: true, application/json, repeated forever.

We all quietly accepted this. I stopped accepting it.

ReSwag (the format) and reOpenAPI (the project) are built on one idea: a spec is something a human should be able to read, remember, and diff. Not a new standard — the graveyard of RAML and API Blueprint teaches that you don't fight OpenAPI. ReSwag is a notation for OpenAPI, the way shorthand is notation for longhand.

Five sigils carry the whole language: * means required. (...) holds human prose. [...] holds lists. {...} marks URL variables. <- and -> show data flow. Four defaults absorb the boring case: GET, 200, String, JSON cost zero characters.

One line of a real spec:

/pet/findByStatus?*status:ENUM|available|pending|sold=available -> [Pet]

The receipts, because claims are cheap

• The Swagger Petstore: 22,105 bytes of YAML → 8,262 bytes of ReSwag. 62.6% smaller.
• Round-trip verified: ReSwag → OpenAPI → ReSwag, zero semantic diffs, byte-stable across five generations.
• Every feature covered — OAuth flows, callbacks, webhooks, discriminators, XML, vendor extensions.
• Examples live in a companion file of pure in/out samples: Pet.id <> 10.

And a 2026 reason to care: we now feed specs to LLM agents. Tokens are money. 60–75% smaller specs are 60–75% cheaper context.

Your API deserves a description you can hold in your head. Compression isn't the trick — conviction is: write down only what you decided, never what everyone already knows.

What would your spec look like at one-third the size?

Ten years ago, as CTO at Awfis, I lived out of a cabin bag.

We were opening coworking centres across India faster than I could visit them — but the software wasn't per-centre. It was one central platform, a single nervous system every new centre plugged into: operations, sales, billing, door entry, meeting-room booking, down to switching a room's AC on before your meeting and off after it. Central meant powerful — one API change lit up every building in the country. Central also meant unforgiving: these APIs had to work in tandem, and if the correlation broke, it didn't break in one centre — a paying customer somewhere stood in front of a door that wouldn't open, in a room that wouldn't cool.

My problem wasn't writing these APIs. It was holding the whole tandem in my head — on a flight to Hyderabad, reasoning about how a contract change in bookings would ripple into access control and the AC schedule, with no laptop space and no patience for 800 lines of YAML per service.

So I did what engineers do under constraint: I invented a shorthand. One line per endpoint. * for required. Arrows for what goes in and what comes out. Types inline, right in the path. Defaults for everything obvious — GET, 200, string, JSON — because writing down the obvious is how specs get fat. It fit on paper. It fit in my head. It let me correlate five systems in one glance at 35,000 feet.

Then it sat in my notebooks for a decade.

Cut to this year. Consulting with Keychain, I hit a very 2026 version of the same wall: an API spec so large I had to raise Claude's max-token limits just to reason about it. And unlike a human, an LLM charges you every single time it re-reads the file. Keeping a bloated spec in context isn't a readability problem anymore — it's a line item. The scaffolding I'd been scrolling past for years (in: query, required: true, application/json, repeated hundreds of times) was now billed by the token.

I reached for the old notebook trick. It worked so well it deserved to be real.

That became ReSwag (the format) and reOpenAPI (the project) — my airplane shorthand, grown up and held to an engineering standard: it converts to full OpenAPI/Swagger and back with zero semantic loss, machine-verified across every feature — OAuth flows, webhooks, callbacks, discriminators, XML, vendor extensions. The Swagger Petstore drops from 22,105 bytes of YAML to 8,262 bytes — 62.6% smaller — and from 838 lines to 151. Examples live in a companion file of pure in/out samples, so the contract stays pure signal. Serialize and deserialize it five generations deep and you get the identical file back, byte for byte.

The benefits landed exactly where the pain was, twice: humans can read their systems again — review a contract in a glance, diff a change in three lines — and LLMs consume the same contract at a third of the tokens, which means a third of the cost, every single call.

The best tools, I've learned, are born in transit, under constraint, solving your own problem.

If your specs no longer fit in your head — or your context window — maybe it's time for shorthand.

Ask your team a simple question this week: when did a human last actually read one of our OpenAPI specs, end to end?

In most organizations the honest answer is never. The spec is the legal contract of your architecture — the thing your gateways enforce, your SDKs are generated from, your partners integrate against — and it has quietly become write-only. An 800-line YAML file doesn't get reviewed; it gets approved. Contract drift, breaking changes discovered in production, integration incidents that post-mortem back to "the spec said so but nobody saw it" — these are not tooling failures. They are readability failures at the contract layer.

There is now a second bill for the same problem. If your teams use AI coding agents — and they do — your specs are being read constantly, by the token. A spec that is 60–75% larger than it needs to be is a 60–75% surcharge on every agent call that touches it, forever. I hit this personally while consulting at Keychain: a spec so large I was raising model token limits just to reason about one API. Verbosity stopped being an aesthetic complaint and became a line item.

ReSwag / reOpenAPI is my answer, and the reason it belongs on a decision-maker's desk is not the compression — it's the risk profile.

The numbers first: the Swagger Petstore drops from 22,105 bytes / 838 lines of YAML to 8,262 bytes / 151 lines. Sixty-three percent smaller, five to eight times fewer lines. A human-memorable notation — five punctuation marks, four defaults — carries the entire OpenAPI feature set: OAuth flows, webhooks, callbacks, discriminators, vendor extensions, all of it.

Now the risk profile. ReSwag is not a migration. It is a lossless, bidirectional view of the OpenAPI you already have — machine-verified: convert any spec in, convert it back, zero semantic difference, byte-stable across repeated cycles. Your Swagger UI, code generators, gateways, and contract tests keep consuming OpenAPI exactly as today. Nothing in your toolchain changes. Which means this is a Bezos two-way door: if it doesn't earn its keep, you convert back and delete it, having lost nothing.

Compare the alternatives honestly. Adopting TypeSpec or Smithy is a platform commitment — new language, build toolchain, one-way importers. Betting on a friendlier standard is how companies ended up holding RAML when the market consolidated. ReSwag deliberately refuses both bets: it is notation, not platform; a projection of OpenAPI's own model, not a rival to it.

What you actually buy: API reviews that happen because the diff is three readable lines. Onboarding where a new engineer holds the contract surface in their head in an afternoon. Design discussions conducted in a form that fits on a screen — or a whiteboard. And a standing 60–75% discount on every token your AI tooling spends reading contracts.

The pilot costs one afternoon: convert your three most-touched specs, put the ReSwag view in the next design review, measure the discussion.

Two-way doors this cheap are rare. Walk through it.