The Specification Layer

This is the sixth issue of The Specification Layer.

This newsletter window: September 6 through September 13. Thirty-two specification repositories and twenty-five feeds, all read clean for the sixth consecutive week — no source errored. 139 pull requests merged. 10 releases cut. 26 posts published. Nineteen of the thirty-two specifications did not move at all — the highest quiet count I have recorded. Separately, the two release-path dependencies I added last week merged 15 more.

Three weeks ago I made a prediction and said I would be graded on it. Time to collect.

Deep beneath the neon grid, two parallel gold rail tracks run out of a foundation vault: on one, a lit carriage has departed and is well down the line; on the other, an identical carriage sits dark and unmoved at the platform with a single small figure watching the first one go.

The Lead: OpenAPI 3.2.1 Shipped — and the Defect Could Not Ride Along

On August 31 I wrote that the v3.2.1 milestone had been 10 of 10 closed for two weeks against a September 30 due date, and that either it ships in the next four weeks or a finished board sits unshipped and I report that instead.

OAS 3.2.1 released September 10, twenty days early. The first OpenAPI release in almost a year — 3.2.0 shipped September 2025.

And the chain that got it there is the chain this newsletter has been reporting week by week, which is the most satisfying thing I have got to write since I started:


Sep 3	build-infra cuts `v1.0.0`, its first tag, live on the TDC call
Sep 6	SpecRef comes back after nine days down, unblocking bibliography resolution
Sep 8–11	build-infra `v1.0.1` and `v1.0.2`; OpenAPI bumps to each
Sep 10	3.2.1 ships

Three weeks of infrastructure work that produced no specification text at all, and then a release. I spent two issues reporting that work as it happened without knowing whether it would pay off. It paid off.

Now the part I have to be honest about

Last week I reported that the OpenAPI validation schema’s version pattern used \d, which under Python and .NET regex engines matches any Unicode digit — so openapi: 3.2.৪, written with BENGALI DIGIT FOUR, validates as a legal version string. @karenetheridge fixed it on August 31 in #5529 and #5530, changing \d to [0-9]. I noted the published schemas still carried the defect.

A release shipped nine days later. So I went to check whether the fix rode along.

It did not. I fetched every 3.2 schema the OAI publishes this morning:

Published schema	`openapi` pattern
`oas/3.2/schema/2025-09-17`	`^3\.2\.\d+(-.+)?$`
`oas/3.2/schema/2025-11-23`	`^3\.2\.\d+(-.+)?$`
`v3.2-dev` branch (unpublished)	`^3\.2\.[0-9]+(-.+)?$`

Here is the part that makes this interesting rather than a gotcha. Before writing a word about it I went and read the OAI’s own contribution rules, because the standing rule in this newsletter is that when the published check comes back yes, the reporting bar goes up. CONTRIBUTING.md says:

Schema changes are made on the same branch, but can be released independently. … Patch releases cannot contain changes that require a schema update.

And the patch-release criteria are editorial changes and “clarifications or additions that do not change the meaning of the specification.”

So 3.2.1 could not have carried the schema fix. Not an oversight, not a miss — a documented policy working exactly as written. The specification prose and the machine-readable schema ship on separate tracks, which is why the OAI publishes dated schemas (2025-09-17, 2025-11-23) that do not line up with specification version numbers at all.

The consequence is still real, and it is worth naming precisely: a defect can be fixed in the repository, and a release everyone reads as “the new version” can go out, and the machine-readable artifact your validator actually downloads is unchanged. If you validate OpenAPI documents in Python or .NET today, against the current published 3.2 schema, 3.2.৪ still passes. The fix exists. It is not where your tooling looks.

That seam — between the document humans read and the schema machines fetch — is invisible from the outside, and it is the kind of thing I would never have found by reading a release announcement.

The vote took three and a half minutes

Not a criticism, just a fact worth recording, because the OAI’s written process has real numbers in it. From CONTRIBUTING.md: “Patch-level releases require majority approval by TSC members. (Max voting period 3 days).”

PR #5549, “Release for 3.2.1”, from @lornajane:

created 16:51:33
approved by @miqui, @mikekistler and @karenetheridge — all three at 16:52
merged 16:55:01

Three minutes, twenty-eight seconds from open to merged. Three days is a ceiling, not a floor, and a majority arrived inside a minute, so nothing here breaks the written rule. It is simply a striking thing to see next to the other release vote that happened in the same organisation the same week, which took a day, cleared a higher bar, and still has not shipped. That one is below.

A small underground chamber beneath the grid where a handful of tiny figures cluster around one gold-lit workbench carrying a single small structure freshly assembled and glowing, the vast dark understructure rising away above them.

🎙 From the Room: Overlay Bi-Weekly, September 8

Second week of this section. The Overlay Specification had been in The Quiet Ones for five consecutive weeks with a milestone board that had not been touched since December 2025. This week it merged six pull requests, every one of them by a person and not a bot. I sat in on the bi-weekly to find out what changed.

Overlay is deliberately the guinea pig. The group’s own framing, from the call: there was general agreement in the broader community to use Overlay as the test subject for the whole new build infrastructure, on the reasoning that it is a smaller group than the main OpenAPI project and can absorb the breakage. That is why Overlay’s sudden burst of activity is entirely plumbing — #379 “Prepare for new Build Infra” from @lornajane removes every previous script and dependency in favour of the shared package, and @baywet’s #394 follows it through CI. The milestone boards were not touched at all — I checked the stored updated_at values against last week’s harvest and they are byte-identical: Release 2.0 last modified December 16 2025, Release 1.2 on July 28, Release 1.3 in May.

Six merges, zero specification change. The repository woke up; the specification did not.

They merged it live and then built the document on the call. #379 went in during the meeting, and the release was then rehearsed locally end to end — yarn install --immutable, yarn test, yarn validate-markdown, yarn build — and it worked. The reaction, and I wrote this one down because it is the whole argument for the three weeks of infrastructure work: “we just built that everybody. This is fun. Why don’t we do this every week?”

And then the sentence that explains why specification releases are so consistently painful. Paraphrasing closely: Overlay deploys once a year or less, so something always breaks; the old process was a sequence of scripts where, when one failed, you had to go find the script and work out what it did; and releases only ever happen live on a video call, at the end of a working day, with everyone watching. “I’ve never had a good experience doing this.”

That is not a complaint about tooling. It is a structural observation about the specification layer that applies far beyond Overlay: a release path exercised once a year is a release path that is broken every time you use it. Every project in this newsletter that releases rarely has this problem, and none of them can see it, because the failure only appears on the day it matters most.

Two smaller things worth recording. Overlay does not have the automated main→dev→version branch sync that OpenAPI uses — it is an available option the project has deliberately not enabled, on the grounds that it was a nightmare on the bigger repo. And the new build makes Unix assumptions: a Windows participant found things breaking and planned to retry under WSL, with the group leaning toward simply telling Windows contributors to use WSL.

The vote that has not closed. At 15:53 during that call, @lornajane opened issue #392, “VOTE: Approve release of OpenAPI Overlay Specification v1.2”. @baywet noted immediately that a minor release needs two thirds of the TSC — four people. Five approvals landed within a day: @lornajane, @earth2marsh, @mikekistler, @miqui and @ralfhandl.

The issue is still open and 1.2 has not shipped. @mikekistler’s approval came with a condition: he wants to hear the group’s thinking on discussion #5538, “Terminology: relative URI reference”, before anyone pushes the button.

So the Overlay 1.2 milestone that has read 7 of 7 closed through six consecutive issues of this newsletter is now, genuinely, one terminology discussion away from shipping. That is the closest it has been, and it is the first time I can point at what is actually holding it.

Method note, same as last week: quotes are from my notes of the call, speaker attribution is reconstructed from content rather than captured speaker by speaker, and anything carrying a claim was checked against the repository record — the vote, the approvals, the merged pull requests and the milestone timestamps above are all links you can open. The group also discussed whether its written release-approval terms match how releases actually run, and expects to revise that text to be more workable. I am reporting that they are revisiting it, and not characterising any particular release, because that is what I can evidence.

The split

Who merged it	Count	Share
`copybara-service[bot]`	29	21%
`dependabot[bot]`	12	9%
`renovate[bot]`	8	6%
`oai-spec-publisher[bot]`	7	5%
`github-actions[bot]`	1	1%
All bots	57	41%
Actual people	82	59%

Six readings: 59% machine, 54%, 72%, 59%, 36%, 41%.

Last week I warned that the human-majority headline was an artifact of adding two young, fast-moving repositories. Same split this week, and the picture is better:

	Merges	Human	Human share
TRACE + PDPP	44	41	93%
The other thirty	95	41	43%
All thirty-two	139	82	59%

The established layer went from 32% human to 43% — its best reading in three weeks, and this time it is real work, not a reporting artifact. Overlay merged six and all six were people. FDC3 merged fourteen with ten by people. OpenAPI, OpenTelemetry and CALM all landed genuine human changes. The layer came back.

A foundation vault holding two enormous stone tablets on separate plinths — the left freshly cut, clean and brightly gold-lit, the right older, dimmer and chipped at one corner — with no walkway between the two plinths.

📐 The Description Layer

What is actually in 3.2.1, from the release notes, because “no significant changes” undersells it: corrections to the table of Style Examples used in parameter encoding; new notes on prohibited in/style/explode combinations (in: cookie, style: form, explode: false with arrays or objects; style: form, explode: true with arrays or objects in encoding objects); corrections to how encoding objects work including prefixEncoding and itemEncoding; clarification of how paths are matched when a template variable contains a /; and an ABNF for the encoding/<name>/contentType field. Editorial in the governance sense, load-bearing if you implement parameter serialisation.

JSON Schema merged nothing at all. First fully silent week I have recorded from that repository, and it ends a five-week run in which @RedZapdos123 was the only human merging there. The action is at the IETF: draft-ietf-jsonschema-json-schema is at revision -03, dated August 26, with an informational RFC expected around 2027.

Arazzo merged five and all five were bots — three publisher syncs and two dependency bumps. Every piece of 1.2’s actual content remains an open pull request: SOAP has been open since July 27, alongside GraphQL, Protocol Buffer RPC and actor-in-the-loop.

AsyncAPI merged one dependabot bump, its 3.0.0 board frozen at 25/28 for a sixth week. GraphQL merged nothing. Moonwalk merged nothing — sixth consecutive week, last merge March 31 2025. There is still no OpenAPI 4.

Protocol Buffers merged 26, of which 23 were copybara, and the substance is memory-safety hardening: an in-place map reallocation that halves peak memory when it triggers, an overflow check in bounded ZeroCopyInputStream parsing, a buffer-underflow guard in GzipInputStream::BackUp, and 0-length packed field handling in Java Lite. gRPC shipped v1.84.0 on September 11.

A subterranean conduit hall where one pipe run carries three identical gold test-rigs clamped along its length, each lit, and at the end of the run a heavy gold seal clamped shut.

📡 Events, Telemetry and the Data Plane

OpenTelemetry stabilised something, and the three-week arc is the model I wish every specification followed.

August 24 — #5265 clarified maxExportBatchSize behaviour on the Periodic exporting MetricReader, explicitly “based on feedback and findings from prototype implementations.”
September 11 — #5291 marks it stable, and the pull request lists the three prototype implementations that merged in between, in Go, Java and JavaScript.

Ambiguity found by implementers, clarified in the document, built three times independently, then declared stable with the evidence attached. Three weeks, in public, with links. That is what a healthy specification loop looks like and it is rarer than it should be.

A requirement got relaxed, deliberately. #5294 from @carlosalberto makes global Propagators recommended rather than required, bringing them in line with global TracerProvider, MeterProvider and LoggerProvider. The PR states plainly that this is not considered a breaking change because the specification is relaxing a hard requirement, so existing implementations keep working. A body that can loosen a MUST on purpose, and say why, is a body paying attention to its own consistency.

#5280 also lets language SDKs expand the scope of the service resource detector, and @cijothomas and @herin049 filled in more Python compliance-matrix entries.

And OpenTelemetry is asking for help on a genuinely hard problem. Their September 11 post on environment variable context propagation puts it well: a trace does not always cross a network boundary. A workflow runner starts a shell, the shell launches a build tool, the build tool starts test processes. There is no HTTP header to carry context through that chain. If you run CI at any scale, this is the specification to go and read.

OTLP merged one renovate bump. CloudEvents, OpenMetrics, xDS and Envoy merged nothing — CloudEvents stable at 1.0.2 since 2022, finished rather than dead, as always.

A vast foundation vault where a heavy gold gate has swung fully open on an empty hall, and beyond it a long row of enormous finished tablets stands completely dark, cold and unattended, with no figures anywhere.

🔐 Identity, Policy, Supply Chain

The EU Cyber Resilience Act’s first hard deadline landed on September 11, and the specifications that encode compliance evidence merged nothing.

OpenSSF published a community guide to the September 11 deadline for manufacturers and a practitioner’s guide recap noting vulnerability reporting obligations to ENISA arriving that day, with the full weight of the law in December 2027. The Linux Foundation published how OSPOs are preparing. This is the sixth consecutive week OpenSSF has led with CRA content.

In the same seven days: SPDX, OCI Image, OCI Runtime, OCI Distribution, in-toto Attestation, OSV Schema, SLSA, TUF and Notary Project all merged nothing. Sigstore merged one dependabot bump. Nine of the ten supply-chain specifications recorded no change in the week the regulation that makes machine-readable software inventory mandatory hit its first enforcement date.

I want to be careful about what that does and does not mean. These are mostly mature specifications — SPDX is an ISO standard, in-toto and SLSA shipped major work in August — and a quiet week is not a dead project. Compliance on September 11 runs on what was already published, not on what merged that week, and that is arguably the system working. But if you expected a regulatory deadline to show up as a burst of specification activity, the honest answer from the repository record is that it shows up as blog posts and guidance, and not one line of specification text.

SPDX’s 3.0.2 milestone remains at 33/38 against a 2026-04-30 due date, now more than four months past, for a sixth week.

TRACE merged 27 and 26 were people, and the shape of the week is a specification being attacked by its own maintainers: reject a malformed signature field with the documented error rather than a crash, validate signed decision enums, require cnf.jwk confirmation keys to actually carry key material, add non-JCS signature rejection controls. Two stand out for intellectual honesty. #310 states that profile floors are specification choices, not regulatory derivations — a spec explicitly declining to claim its thresholds come from law. And #315 corrects a “can’t fake hardware” claim in its own sandbox adapter documentation. Walking back your own security marketing inside your own docs is a good sign.

PDPP merged 17 and cut six releases, v1.11.1 through v1.12.0, though the week was mostly site and packaging work rather than specification text.

SPIFFE and OpenFeature merged nothing.

An understructure beneath the neon grid where a crew of small figures works a gold-lit beam joint while beside them a second crew's tools lie set down mid-task on the dark floor, the work passed from one crew to the other.

💹 Financial Services Data Standards

FDC3 came back, and so did the maintainer I have now written about three times.

Fourteen merges, ten by people. @julianna-ciq — who merged 28 in one week in August, then 1, then nothing for two weeks — is back with five: conformance tests for addEventListener, tests for omitted metadata in proxy requests, validation of retained context response invariants, an ESLint 10 upgrade, and a trace-ID fix in the example apps.

I have amended my “FDC3 rests on very few people” thesis twice now. The third data point says the load rotates rather than rests: this week @Roaders landed #1983, making the context argument of raiseIntent optional, which is his second normative interface refinement in three weeks after newInstance. Apps that raise an intent only to get a result no longer have to pass fdc3.nothing explicitly; the proxy substitutes it, so the wire protocol is unchanged. Schema, interface, reference docs and conformance tests moved together again.

Governance moved too: @Yannick-Malins removed himself from MAINTAINERS.md and retired the FDC3 Identity & Security Working Group meeting. A working group being formally wound down is worth noting; it is the kind of change that never makes an announcement.

The FDC3 3.0 board went from 29/42 to 32/48 — three closed, six added. Project news, not specification news.

CALM shipped cli-v1.59.0 — the sixth consecutive week its tooling has released while the CALM schema has not changed. But this week the tooling is doing something interesting: @jpgough-ms landed a five-slice run adding OIDC-driven auth to calm-hub with VS Code plugin login, a GitHub API response cache and observability dependencies, and @rocketstack-matt shipped calm-lab, an in-browser learning lab running on the real CALM engine rather than a simulation. A standard that gives you somewhere to learn it without installing anything is doing adoption work most specifications never attempt.

🏛 From the Foundations

The SpecRef governance thread moved, and it is going somewhere. Last week I said I would follow issue #959 — the maintainer asking who should own the bibliography service’s domain, hosting and credentials long term. Two substantive replies arrived inside this window. @xfq proposed designating a legal entity to hold the assets — domain, cloud accounts, CDN, trademarks — with a separate SpecRef steering committee, and noted the entity could be W3C or another candidate. Then @ianbjacobs: “I would like the nascent W3C OSS program to be able to accommodate the governance needs of a multi-SDO community. I’d love to have a discussion about needs/requirements.”

That is a concrete institutional offer to host a shared dependency for a community that spans multiple standards bodies, made in public, ten days after the outage. Worth following to a conclusion.

SpecRef itself merged eight pull requests, all operational hardening — a /health endpoint for Clever Cloud’s checks, deployment documentation, structured logging with pino “so that whatever takes the process down leaves a trace”, configurable IP filtering, serving the full 27MB bibliography dump as a gzip stream instead of building it as one enormous string, caching and pre-compression, and a robots.txt confining crawlers to /bibrefs. A service that spent years as somebody’s side project got a fortnight of real operations work because it fell over. That is the usual price.

CNCF graduated Karmada at KubeCon Shanghai, announced September 7 — multi-cluster, multi-cloud Kubernetes orchestration reaching production maturity. CNCF also welcomed new silver members including SoftBank and Crusoe, and China Merchants Bank won the end-user case study contest for lifting accelerator utilisation from 35% to over 60%.

Mandy Chessell closed out her four-part Egeria series, and LF Decentralized Trust shipped Hyperledger Cacti v3 for cross-chain interoperability.

A long subterranean colonnade of tall blank dark monoliths receding into blackness, their edges traced in cold gold, standing silent while the load-bearing neon grid runs on past all of them.

🤫 The Quiet Ones

Nineteen of thirty-two — the highest count in six weeks of doing this, and almost the entire increase is the supply chain going dark at once. The series now reads 12, 19, 16, 13, 15, 19.

Finished, not dead — stable, shipped, carrying load: CloudEvents (1.0.2 since 2022), OCI Image (last merge 2017), OCI Runtime, OCI Distribution, TUF, Notary Project, xDS.

Quiet and worth watching: JSON Schema (first silent week, and the work has moved to the IETF), SLSA and in-toto (one and two weeks after major landings), SPDX (second silent week, overdue board), OSV Schema, SPIFFE, OpenFeature, OpenMetrics, GraphQL, AsyncAPI community.

Silence that is the answer to the question I get asked most: Moonwalk, sixth consecutive week.

Overlay is not in this list for the first time since I started counting — though as the section above explains, what it merged was build tooling, not specification.

An intact newly-lit gold structure standing on the neon grid, with a single conduit running away from it that goes dark a short distance out and lies unlit across the floor into the distance, never reaching anything.

📡 Channel Health

All twenty-five working feeds returned for the sixth consecutive week. Volume recovered to 26 items from 17.

This week’s finding is a good one. OpenAPI shipped its first release in almost a year, and its own announcement feed said nothing. openapis.org/feed has been silent since July 22 — eight weeks — and 3.2.1 came and went inside that silence. If you follow the OpenAPI Initiative through the channel it publishes for exactly this purpose, you do not know there is a new version of OpenAPI.

Protocol Buffers, re-verified this morning: protobuf.dev/news/v34/ returns 200; /news/v35/ and /news/v36/ both 404. Four consecutive weeks.

Unchanged since issue one: Sigstore publishes no feed on any path, Envoy’s blog host does not resolve, and OpenSSF’s working feed remains /feed/ while /blog/feed/ and /blog/rss/ answer 200 with zero items.

The dormancy leaderboard, longest first: in-toto (May 2023) · CloudEvents (July 2024) · Notary Project (June 2025) · OCI (April 2026) · SLSA (May 2026) · gRPC (June 2026) · GraphQL (June 2026) · Prometheus/OpenMetrics (June 2026) · Protocol Buffers (July 2026) · OpenAPI Initiative (July 2026) · AsyncAPI (August 2026).

How This Was Made

Every number above came from one harvest run against the GitHub REST and GraphQL APIs and twenty-five feeds, over September 6 to September 13, 2026. Merged pull requests are counted by merged_at inside the window. Bot attribution is by author login. Milestone percentages, descriptions and updated_at timestamps are GitHub’s own values, read live and stored week over week — which is how I can say Overlay’s boards were untouched rather than merely unchanged.

Where this issue makes a claim about what a pull request did, I opened it and read its file list, diff or body. The schema finding is every published 3.2 schema fetched from spec.openapis.org this morning and compared against v3.2-dev, then read against the OAI’s own CONTRIBUTING.md before I wrote a sentence about it — the rule that a patch release cannot carry a schema update is theirs, quoted, and it is the reason the story is a seam and not a failure. The 3.2.1 vote timings are the pull request’s creation, review and merge timestamps. Overlay’s vote, its five approvals and its open condition are issue #392.

Meeting material is from my notes of the Overlay bi-weekly on September 8. Speaker attribution is reconstructed from content rather than captured speaker by speaker, so anything carrying a claim was corroborated against the repository record; where the group’s discussion could not be evidenced against an artifact, I have described what they are doing rather than characterised anyone’s conduct.

Standing rules, applied throughout: a merge to a specification repository’s default branch is not a change to a published specification — check which artifact it lands in and whether that artifact is published. Milestones and planning boards are project news, never specification news. The registry is a source of findings, never a boundary on them. And report the specifications’ dependencies, not just the specifications: OAI/build-infra and specinfra/specref merged 15 pull requests between them this week and are counted separately from the 139, because a build tool and a bibliography service are not specifications, but either one can stop a release dead.