The Specification Layer

← All newsletters

This is the first issue of a new thing. Every week I read the API industry’s blogs. That newsletter still goes out, and it covers what vendors and practitioners wrote. This one covers something different and much less visible: what actually changed inside the specifications themselves. Not the commentary about OpenAPI — the merges into OAI/OpenAPI-Specification. Not a post about supply-chain security — the diff that added WordPress to the OSV schema.

The Linux Foundation quietly became the neutral home of nearly every contract that describes an API. OpenAPI and its new siblings Arazzo and Overlay, AsyncAPI, GraphQL, JSON Schema, gRPC, CloudEvents, OTLP, OpenMetrics, xDS, SPIFFE, OpenFeature, SPDX, OpenChain, the three OCI specs, in-toto, OSV, SLSA, TUF, Notary, Sigstore — one foundation, one IP framework, one governance model. Add Protobuf, which is Google’s and not LF-governed but sits underneath half of the above, and FINOS’s FDC3 and CALM, and you have thirty repositories that between them define how REST, event-driven, RPC, and GraphQL APIs are described, how telemetry is encoded, how workloads prove identity, and how software artifacts are signed and inventoried.

Nobody publishes a weekly read of those thirty repositories. So I built one. Here is week one.

The window: August 2 through August 9. Thirty specification repositories and twenty-five feeds, all read clean — no source errored, which will not always be true and which I will always tell you when it isn’t. 150 pull requests merged. 4 releases cut. 24 posts published.

Beneath the dark neon grid, a long steel gantry carrying an endless line of identical automated riveting arms working a gold seam, while at one point three small figures on a ladder set a single glowing joint by hand.

The Lead: 59% of Specification Activity Is Now Machines

I expected to open this newsletter with a version number. Instead I want to show you the composition of that 150.

Who merged it	Count	Share
`copybara-service[bot]`	34	23%
`dependabot[bot]`	29	19%
`renovate[bot]`	13	9%
`oai-spec-publisher[bot]`	11	7%
`github-actions[bot]`	2	1%
All bots	89	59%
Actual people	61	41%

Fifty-nine percent. If I had led with “150 changes landed in the specification layer last week,” that would have been true and it would have misled you. Most of the motion in these repositories is a dependency bump, a branch sync, or an internal export from a company’s private monorepo.

This is not a complaint. Branch-sync automation is how the OpenAPI Initiative keeps four live version branches coherent; copybara is how Protobuf’s development inside Google reaches the public repo at all. That plumbing is doing real work. But it means any headline count of specification activity is mostly measuring robots, and I would rather establish that in issue one than quietly inflate a number every week for a year.

The interesting cut is the inverse. Four specifications had zero bot merges last week — every single change was made by a person: JSON Schema (7), SPDX (7), SLSA (3), and SPIFFE (1). Those four are also the ones where the merges are prose: wording, grammar, definitions, conformance dependencies. That is what a specification under genuine editorial work looks like, and it does not scale, and it does not automate.

Meanwhile FDC3 merged 18 pull requests of which 15 were dependency bumps, and Protobuf merged 35 of which 31 were machine exports. Same headline number, completely different week.

A foundation chamber underneath the neon grid, dozens of gold and grey conduits converging from every wall down into one blank white slab set into the floor, the distant grid city visible through the opening beyond.

📐 The Description Layer

OpenAPI has a patch release fully loaded and nobody has pulled the trigger. The v3.2.1 milestone stands at 9 of 9 issues closed — 100% — with a due date of September 30. Everything scoped for that patch is done. Sitting next to it, v3.3.0 is at 17 of 45 closed (38%) with a due date of September 3rd: twenty-eight open issues and about three and a half weeks. One of those two dates is going to move. Watch which one.

The human merges into OAS this week were small and honest — @karenetheridge fixing whitespace mistakenly introduced into v3.2 and v3.3, and a schema error in contentType on v3.1; @handrews fixing a dead Slack invite link twice. The other eight of thirteen were the publisher bot syncing dev, v3.1-dev, v3.2-dev and v3.3-dev.

The genuinely interesting OpenAPI activity was in discussions, not merges, and both are the kind of question that has bitten every one of us:

Allow using deprecated: true to tag Response Objects — you can deprecate an operation and a parameter, but not a response you intend to stop returning.
Is type: string, format: binary “invalid” in 3.1, or is it “deprecated”? — a question with an enormous amount of deployed tooling riding on the answer.

JSON Schema is the one to watch, and the story is governance. Seven merges, all human, all editorial: RFC-2119 keyword matching fixed so it stops matching inside other words, meta-schema paths resolved as file URLs for Windows, grammar in the media-type descriptions. Ordinary spec hygiene.

But two of those seven touch the IETF, and that is not ordinary. #1748 “Update dates so ietf builds don’t break” merged August 3rd, and #1752 merged August 7th fixing wording in a file called adr/2022-09-decouple-from-ietf.md. JSON Schema wrote a formal architecture decision record in 2022 to decouple from the IETF — and this week they were maintaining the IETF build so it wouldn’t break, and polishing the language of the decoupling decision itself.

Meanwhile the IETF has an active jsonschema working group, charter revision 01, last touched 2026-04-30. I checked the datatracker directly rather than take anyone’s word for it. So the specification that is the connective tissue underneath OpenAPI, AsyncAPI, CloudEvents, OSV and SPDX has a standing decision to leave the IETF and a live IETF working group at the same time. JSON Schema also ships no GitHub releases at all — it versions by draft, still 2020-12. If you build tooling on JSON Schema, the question of where the next version gets decided is not settled, and this week is the first week I have seen both threads move at once.

Arazzo and Overlay were pure housekeeping — four and two merges, almost all bots. Worth noting the milestone boards anyway: Overlay has Release 1.2 at 7/7 closed (100%), Release 2.0 at 4/7, and a Release 1.3 that is 0/3. Arazzo shipped 1.1.0 back in May.

AsyncAPI merged three dependency bumps and nothing else. Its “Issues to consider before 3.0.0 Release” milestone sits at 25/28 — 89% — and has been close for a while. The one real signal was in asyncapi/community, where the roadmap docs were removed to align with the website and changes in community direction. Deleting your public roadmap is a decision, not a chore. The July community update landed August 3rd.

Protocol Buffers cut v36.0-rc2 on August 3rd and merged 35 changes, 31 of them machine exports from Google’s monorepo. Their own July 13th news post says Edition 2026 is planned for the 36.x line in Q3 2026 — so that release candidate is the vehicle for a new edition, and Q3 has about seven weeks left in it.

gRPC merged four, including GOAWAY support in the PH2 server work. GraphQL merged nothing at all — more on that below.

A service corridor running below the grid floor, a receding rank of tall dark bulkheads with light spilling between them, gold and cyan streams of telemetry curving along the plating underfoot into the distance.

📡 Events, Telemetry and the Data Plane

OpenTelemetry was the busiest genuine specification of the week — 15 merges, only 5 from bots, and unlike most of this issue they were substantive:

Composable views matching mode
AttributeValueDepthLimit for array and map attribute values — a bound on nesting depth, which is the sort of limit you add after someone puts an entire JSON document in an attribute
Max request and response size options on the OTLP exporter
Clarified Logs SDK emit-time LoggerConfig filtering rules
Prometheus exporter: content negotiation versus translation strategy

And #5252, “Release 1.60.0”, merged August 7th — the tag was not yet published when I harvested, so treat 1.60.0 as cut but not shipped. opentelemetry-proto merged six, mostly dependency work plus removing BCR publishing.

Their blog also published a practical guide to metric cardinality limits — the memory-safety valve in the metrics SDK, which is exactly the kind of thing nobody reads until an incident.

CloudEvents, OpenMetrics and xDS merged nothing. For CloudEvents that is the steady state — the spec has been stable at 1.0.2 since 2022 and a graduated, finished specification is allowed to be finished. I will keep saying that rather than implying decay.

Inside a vaulted understructure lit gold and cyan, one massive chain rises from a blank white anchor block in the floor straight up through the ceiling, every link carrying the weight of the hall above it.

🔐 Identity, Policy, Supply Chain

OSV Schema shipped v1.9.0 on August 6th, the only real release of the week in this category. Two changes worth naming: wildcard package name * support in the schema and linter, and WordPress added as an ecosystem. A vulnerability format adding WordPress is a statement about where vulnerabilities actually live.

SPDX did the week’s most thankless work — seven merges, every one by a person, mostly @bact and @zvr: a dependency from the Software profile to the Licensing profile conformance, a rewrite of the serialization section to remove “you”, a dead EO 14028 link, a POSIX ERE fix in the license-matching guidelines. This is what maintaining an ISO-ratified standard looks like from the inside.

Their milestone board deserves a flag, though. SPDX 3.1 sits at 45/102 closed, 3.1-rc2 at 24/44, and 3.0.2 is at 33/38 with a due date of April 30th — over three months past due. A stale milestone date is a small thing, but SPDX is ISO/IEC 5962 and procurement teams read these boards.

SPIFFE merged exactly one change: wit-svid added to the list of supported use values. One line, and it widens the set of things that can carry a workload identity.

SLSA merged three, all human, and two were logo changes on the website — IBM and Red Hat added to the collaboration section, Verizon’s removed. Who is and is not on your adopters page is a real signal, in both directions.

OpenFeature merged three: two dependency bumps and a dead CNCF Slack invite link. Which is the second dead Slack invite fixed in a specification repo this week, after OpenAPI’s two. Somewhere a Slack invite expiry policy is quietly generating pull requests across the entire Linux Foundation.

in-toto merged one dependency bump. All three OCI specs, TUF, the Notary Project and Sigstore’s protobuf-specs merged nothing at all.

Two tall angular pylons rising from the neon grid under a near-black sky, a suspended span of glowing gold coins strung between them like a cable, a stepped pyramid standing on the far bank at either end.

💹 Financial Services Data Standards

FINOS is where the volume was, and it is a different kind of volume.

CALM merged 20 changes and cut two CLI releases in six days — v1.52.0 on the 3rd, v1.53.0 on the 5th. The substance is a versioned artefact storage redesign landing type by type in CALM Hub, plus layout persistence and a VS Code plugin update. Only 7 of 20 were bots. CALM is behaving like a product, not a specification, and it is the fastest-moving thing on this entire list.

FDC3 merged 18, of which 15 were dependency bumps. The real ones were @kriswest improving CVE scan coverage and @julianna-ciq removing an unused security dependency. FDC3 3.0 sits at 19/39 closed, with a 3.1 candidates milestone opened at 0/9 — so 3.1 is being scoped before 3.0 is finished.

FINOS also published From AI Principles to Executable Governance on the 8th, marking the transition from frameworks to running controls. “Executable governance” is a phrase I expect to steal.

A wide bedrock plain under the neon grid carrying dozens of low gold-edged stepped platforms, each one a separate foundation footing, all of them lit and holding up a structure that is out of frame above.

🏛 From the Foundations

The Linux Foundation’s press channel had a genuinely busy week:

The Tokenomics Foundation launched with 30 industry participants, to build open frameworks, specifications and practices for measuring the cost, value and return of AI spend. A new foundation whose output is specifications for measuring AI cost — file that next to every FinOps conversation you are about to have.
The SAFE Working Group was proposed as a community effort on AI security.
Dell, HP, Lenovo and NVIDIA backed the Linux Vendor Firmware Service.
Intel joined the OCUDU Ecosystem Foundation as a premier member for open source RAN.

CNCF published eight pieces, with K8gb accepted as an incubating project and Cortex completing its OSTIF security audit. OpenSSF announced OpenBao v2.6. OpenChain shipped its July newsletter — the most dependable publishing cadence of any project on this list.

A long subterranean colonnade of tall blank monoliths receding into the dark, most of them unlit and cold, only a handful still glowing pale gold, the load-bearing grid running on past all of them.

🤫 The Quiet Ones

This section is the reason I built the harvester. Twelve of the thirty specifications had no merged change, no release and no commit in the window:

Moonwalk (OAS 4 design) · GraphQL Specification · CloudEvents · OpenMetrics · xDS · Envoy · OCI Image Spec · OCI Runtime Spec · OCI Distribution Spec · TUF · Notary Project · Sigstore protobuf-specs

Read that list carefully, because silence means different things in it.

CloudEvents, TUF and the OCI specs are finished. A stable graduated specification that nobody needs to change is the goal, not a warning sign. OCI image-spec’s last merged pull request was in 2017 and the format still runs every container registry on earth.

Moonwalk is the one to actually notice. The OpenAPI 4.0 design effort last merged anything on 2025-03-31 — over sixteen months ago. Every few weeks someone asks me what is happening with OpenAPI 4. The answer, from the repository rather than from a rumor: nothing is happening, there is no release date, and 3.3.0 is where the work is. Do not plan around a 4.0.

GraphQL merged nothing this week and its last merge into the spec was 2025-07-01, with 196 open issues. It publishes editions — the September 2025 edition is current — so a quiet repo is not a dead standard. But the contrast with 45 open issues on OAS v3.3.0 and a three-week deadline is worth sitting with.

An intact glowing stepped pyramid and a lit monolith standing on the neon grid, a thick bundle of conduits strung between them gone dark and slack, severed ends hanging loose above the floor.

📡 The Channels Are Rotting

While wiring this up I probed every publishing channel these projects offer. The results are their own story, and I am reporting them because a specification that cannot tell you what changed has a real problem no matter how good the spec is.

No working feed at all:

Sigstore — blog.sigstore.dev returns 404 on /rss/, /feed and /rss.xml. The served page is 7.7KB of client-rendered markup with no post links and no dates in it. The project whose entire purpose is making software supply chains verifiable does not publish a machine-readable feed of its own announcements.
Envoy — blog.envoyproxy.io fails to connect outright and /blog/index.xml 404s.
JSON Schema — publishes a blog with no feed on any conventional path.
OpenSSF — /blog/feed/ and /blog/rss/ both return HTTP 200 with zero items. A 200 that yields nothing is worse than a 404, because every tool downstream records it as a success. The working feed is at /feed/.
Protobuf — the feed exists and every single item is stamped Mon, 01 Jan 0001. The real date is only in the URL. I now parse the URL.

Dormant, longest first: in-toto (last post May 2023) · CloudEvents (July 2024) · Notary Project (June 2025) · OpenFeature (March 2026) · OCI (April 2026) · SLSA (May 2026) · gRPC (June 2026) · GraphQL (June 2026).

Eight of the specifications that the industry depends on have not posted anything in months, and three have not posted in over a year. The repositories are alive. The announcement channels are not. If you are trying to track this layer by subscribing to blogs, you are watching the wrong surface — which, uncomfortably, is the argument for this newsletter existing.

How This Was Made

No estimates, no vibes. Every number above came from one harvest run against the GitHub REST and GraphQL APIs and twenty-five feeds, on a window of August 2 to August 9, 2026. Merged pull requests are counted by merged_at inside the window. Bot attribution is by author login. Milestone percentages are GitHub’s own open/closed counts, read live.

Two deliberate exclusions: Envoy’s pull requests are not counted — it is a high-volume implementation repository, not a specification, and including it would drown every real spec in the issue; only its releases count. And a source that fails to respond is reported as an error, never as zero activity, because “quiet week” and “my harvester broke” look identical in a chart and only one of them is true. This week every source returned.

If a number here is wrong, the repository is the authority and I will correct it in the next issue. If there is anything missing that you’d like to see let me know. The goal is to bring activity across all of the Linux Foundation specs into view so we can think more about what is needed across them.

Next Monday: whether OAS ships 3.2.1 or slips 3.3.0, and the first week-over-week numbers now that there is a baseline to compare against.