The Specification Layer

← All newsletters

This is the third issue of the Specification layer. Last week I led on the OpenAPI Initiative’s milestone board — a due date that came off 3.3.0 without a commit to point at. This week the same board came back with a label on it.

This newsletter window: August 16 through August 23. Thirty specification repositories and twenty-five feeds, all read clean again — no source errored. 109 pull requests merged. 2 releases cut. 13 posts published. Sixteen of the thirty specifications did not move at all. It is summer though. To be expected.

One hundred and nine merges is down forty-seven from last week, and the drop is not distributed the way the headline suggests. Machine merges fell by five. Human merges fell from 72 to 30 — a 58% collapse in a single week — which pushed the machine share of the entire specification layer from 54% to 72%, its highest reading since I started counting. A lot of my work on Spotlight Rules and APIs.json are machine-driven. Curious how the rest of the space compares.

Deep beneath the dark neon grid, a foundation chamber where a colossal gold-edged bedrock slab is bisected by a heavy chain barrier, a single small lit lamp on the near side and the vast structure receding into darkness beyond it.

The Lead: Two Standards Bodies Told Me the Same Thing in Eight Days

First, a correction. In the August 16 issue I wrote that JSON Schema “found a bug in its own meta-schema” and called it “a normative artifact rejecting conformant input.” That was wrong. The file that pull request changed is an unpublished draft in the v1 line, added to the repository in June, and the published 2020-12 meta-schema does not contain the construct at all. Nothing anyone deployed was ever affected. Karen Etheridge of the JSON Schema TSC flagged it, I corrected the published issue on August 19, and her second point is the one that mattered more than the first: work in flux is not news, and reading an in-progress branch as a shipped defect is a mistake this newsletter is structurally prone to because it harvests merged pull requests for a living.

Eight days later, the OpenAPI Initiative said the same thing in its own repository, in capital letters.

The v3.3.0 milestone now carries this description:

INTERNAL USE ONLY. Our process is not your process, information about specification changes should be taken only from the in-progress, publicly-available specification versions in the repository. ;-)

And the project’s release-planning discussion, #5116, is now titled:

[OUTDATED, DO NOT CITE PUBLICLY!!!] 3.3+ planning ideas

Here is what I can and cannot take as evidence, because that distinction is a significant part of this job. GitHub does not expose edit history for a milestone description or a discussion title, so I cannot show you the moment either one changed. What I can show you is that both were touched inside the window and inside minutes of each other: issue #1416 closed at 18:07:20 on August 21, milestone 18’s updated_at reads 18:19:55, and discussion #5116’s updated_at reads 18:27:42 — while its most recent comment is from July 2, so that August 21 timestamp is a metadata edit, not a conversation. Twenty minutes, one sitting, three artifacts.

I did not record milestone descriptions in my harvest before this week, so I cannot prove the “INTERNAL USE ONLY” text is new. I am recording them from now on, and if a maintainer tells me that label has been there for months I will say so next week.

Now the number that makes their point better than the label does. OpenAPI merged eleven pull requests this week. I opened every one and listed the files. Exactly one touched a specification document: #5515 from @ralfhandl, on the v3.2-dev branch, +2/-2 in src/oas.md. The complete diff capitalizes “Encoding object” to “Encoding Object” in a normative sentence and in a YAML comment. Pedantic details. It is good though.

Two weeks. Twenty-three merged pull requests. Two words of specification text.

Everything else was the build migration I wrote about last week, still propagating. #5503 from @handrews moved the project off npm and onto yarn — 4,152 added, 5,888 deleted — because, quoting the PR, “NPM has too many weirdnesses with platform-specific issues and interactions with GitHub.” That change then replayed across dev, v3.1-dev, v3.2-dev and v3.3-dev as four identical +4164/-5915 sync merges from the publisher bot, plus three smaller syncs and #5499 wiring the dev branches into the shared build-infra schema test helpers. Six of the eleven merges were bots replaying one human decision onto four branches.

So both readings of the OAI’s week are true at once, and only one of them is worth anything to you. Read the repository and you see a busy project. Read the specification and nothing happened except a capital O. I will continue to search for the signal in the noise. Each issue I will learn more, and strengthen my automation.

The milestone board moved, and almost none of it was work

Milestone	Aug 16	Aug 23
v3.3.0	17 / 45 (38%)	18 / 39 (46%)	1 closed, 6 items gone
v3.2.1	9 / 9 (100%)	10 / 10 (100%)	due 2026-09-30

3.3.0 gained eight percentage points this week. One issue was finished — #1416, “Security Requirement Consistency with Server Objects”, closed August 21. The other six points came from six items leaving the milestone entirely, and I want to flag a gap in my own evidence: GitHub’s repository events feed covers this window, and it records exactly one milestone event across the whole repository — @ralfhandl adding #5515 to 3.2.1. There are zero demilestone events. Six things left milestone 18 and the events API does not narrate how.

I am not implying anything was hidden. I am saying that a percentage on a planning board went up by eight points while one issue got done, and that this is precisely the thing the OAI has now labeled internal — with, on this evidence, some justification.

The rule I am adopting is theirs, verbatim: information about specification changes gets taken from the in-progress specification versions in the repository — the v3.x-dev branches and the published documents — not from the milestone board. Milestone numbers will still appear in this newsletter, because a spec’s planning surface is legitimately interesting, but from now on they are reported as project news and never as specification news, and the distinction gets said out loud every time.

The machines took the layer back

Who merged it	Count	Share
`copybara-service[bot]`	34	31%
`dependabot[bot]`	26	24%
`oai-spec-publisher[bot]`	8	7%
`renovate[bot]`	5	5%
`opentelemetrybot`	4	4%
`github-actions[bot]`	2	2%
All bots	79	72%
Actual people	30	28%

Three weeks of this split now: 59% machine, 54%, 72%. Last week I wrote that the flat headline count was hiding a fifth more human work landing than the week before. This week it is hiding the reverse, harder: the headline fell 30% and human effort fell 58%. The busiest human across all thirty specifications merged four pull requests. Last week one person merged twenty-eight.

Dependabot alone out-merged every human being working on every specification in this newsletter, at 26 to 30 across the field.

A vaulted undercroft beneath the neon grid where an enormous blank stone tablet stands lit in gold, and on its entire surface just two small carved marks, while all around it dozens of gold scaffolding gantries are being disassembled and rebuilt by tiny figures.

📐 The Description Layer

Protocol Buffers shipped v36.0 — the only specification-bearing release in the entire layer this week. Published August 20, after release candidates on July 9 and August 3.

This one carries language-level change, not just runtime. From the release notes: default_symbol_visibility becomes STRICT in Edition 2026; a new enforce_proto_limits feature is added and turned on by default in the descriptor for Edition 2026; reserving field number INT_MAX is now disallowed; the top-level unittest protos have been migrated from Edition 2024 to Edition 2026; and (py|cc|java)_generic_service now emits deprecation warnings. Editions are how Protobuf versions its language now, and Edition 2026 is visibly being assembled in the open.

Protobuf also merged 32 pull requests, 30 of them copybara-service[bot] — Google’s monorepo exporting outward, same as every week. The two human merges were @JasonLunn cherry-picking release commits onto the 36.x branch. It remains the most automated specification in the set by a distance.

And then the part that belongs in the channel-health section but is too good to bury: the most recent version announcement on protobuf.dev/news is v34. protobuf.dev/news/v35 and protobuf.dev/news/v36 both return 404. Two major versions have shipped since the news channel last described one, and the v36.0 release notes open by pointing readers at that news page for “additional announcements.”

JSON Schema merged one change, and it is the same file as last week. #1763 from @RedZapdos123, merged August 22, adds "pattern": "^[^#]*$" to $schema in specs/meta/meta.schema.json, so a $schema value containing a fragment fails meta-schema validation. It ships three test cases: no fragment valid, empty fragment invalid, named fragment invalid.

Applying the rule properly this time. That file is an unpublished draft in the v1 line. The change brings it into agreement with the v1 prose in specs/jsonschema-core.md, which says the value of $schema “MUST be an absolute IRI (without a fragment).” The published 2020-12 core specification says something different — “MUST be a URI (containing a scheme) and this URI MUST be normalized,” with no fragment prohibition — and the published meta-schema at https://json-schema.org/draft/2020-12/meta/core types $schema as a plain uriString with no pattern at all. So this is a v1 design decision being made machine-checkable inside a draft, not a fix to anything you are running. If you write $schema values today, nothing has changed for you.

Arazzo and Overlay were dependency bumps and nothing else. Arazzo merged four, all bots — two respec/highlight.js bumps and two publisher syncs. Overlay merged three, all dependabot, and its milestone board is now frozen at identical numbers for the third consecutive week: Release 2.0 4/7, Release 1.2 7/7, Release 1.3 0/3. A finished 1.2 milestone has now sat unshipped for three weeks in this newsletter’s record.

AsyncAPI merged nothing at all, and its “Issues to consider before 3.0.0” milestone is unchanged at 25/28 for the third straight week.

gRPC’s ratio inverted. 14 merges, ten of them human — after a week of 11 bots to 1 human. Almost all of it is release engineering rather than protocol: @asheshvidyut bumping versions on the v1.82.x and v1.83.x branches, and backporting a Python fix that makes StatusCode enums actual ints across three release branches, plus @shivaspeaks fixing PSM interop CI on three branches and @aslam9691 on workflow preservation. Real people doing real work, none of it in the protocol.

Moonwalk is still silent. Third consecutive week, last merge March 31, 2025. GraphQL merged nothing again.

A service corridor deep under the grid floor, its telemetry conduits still lit gold and flowing, but every junction box along its length worked by small automaton arms on rails, not a single human figure anywhere in the passage.

📡 Events, Telemetry and the Data Plane

OpenTelemetry went from the most human-driven specification in the layer to zero human merges in seven days.

Last week: 14 merges, 11 by people, including a Prometheus exporter section stabilized on the back of a written SDK conformance survey. This week: four merges, all four machine — opentelemetrybot adding a shared security scanning workflow and moving to the shared OSSF Scorecard workflow, and renovate on lock-file maintenance and a cspell action bump. OTLP merged two, both the same bot, both the same two CI changes.

Six merges across the two repositories, zero people, zero specification. It is one week and one week is not a trend, but it is the single largest week-over-week swing in the harvest and it is worth watching whether the OTel spec repos come back.

CloudEvents, OpenMetrics and xDS all merged nothing. For CloudEvents the standing note holds: stable at 1.0.2 since 2022, carrying a large share of the industry’s event plumbing. That is finished, not dead.

A vaulted chamber beneath the neon grid where one enormous sealed door stands closed and dark, and pinned across its face a single large glowing gold map or chart, lit from within, the only light in the room.

🔐 Identity, Policy, Supply Chain

The most consequential specification news of the week came from a repository that merged nothing. SPIFFE published The SPIFFE Standard Roadmap on August 18 — SIG-Spec’s twelve-month plan, written by Arndt Schwenkschuster, and the first time in this newsletter’s short life that a project has laid out where its specification is going rather than shipping a diff.

Three things are on it. SPIFFE Filesystem Delivery standardizes what has been reinvented per-deployment for years: fixed file names for the bundle, the certificate and the private key, plus a single SPIFFE_CREDENTIAL_FOLDER environment variable pointing at the directory — X.509 SVIDs only for now, JWT deferred pending interest. That proposal is PR #376, and I want to be exact about its status: open since February 21, 355 lines, not merged, last touched August 20. The roadmap is the news; the specification is still a proposal.

Transaction Tokens is the one to watch, and the motivation is stated plainly in the post: an X.509 SVID tells the fifth service in a chain that the fourth one called it, and nothing about whose request started the chain or whether the amount was modified in flight. Their words: “With non-deterministic workloads like AI agents entering these chains and the industry acknowledging the problem, we want SPIFFE to secure it end-to-end.” Short-lived signed JWTs carrying originating actor and purpose, issued on demand through an experimental profile on the Workload API. That PR has not been posted yet. A remote Workload API is the third, aimed at managed-node environments — EKS Auto Mode, GKE Autopilot — where there is nowhere to put a node agent.

If agent-to-service call chains are going to have a machine-readable identity contract, this is the specification where the argument happens. Nothing merged. Everything to watch.

The supply chain woke up, quietly and usefully. Seventeen merges across in-toto Attestation, Sigstore, OSV Schema and SPDX, and four of them are worth your time:

in-toto attestation #578 from @arpitjain099 fixes a genuine defect in a published Go module. digest_set.md says gitCommit, gitTree, gitBlob and gitTag hold either SHA-1 (40 hex) or SHA-256 (64 hex), but HexLength() returned 20 bytes for all four, so ResourceDescriptor.Validate rejected a perfectly valid SHA-256 git digest with ErrIncorrectDigestLength. The library now tracks accepted byte sizes per algorithm. That is a shipped implementation disagreeing with its own specification, and this time I have checked which side is published: the Go module is.
OSV Schema #557, also @arpitjain099, adds linter check REC:005 constraining OSV record ids to ^[a-zA-Z0-9:_.-]+$ — the stated rationale being to avoid URL encoding and to prevent shell-script breakage on ids containing spaces or slashes. A linter rule, not a schema change.
OSV Schema #588 from @jess-lowe clarifies how to represent a vulnerability that spans both a strict ecosystem like Go or npm and a generic Git repository: distinct entries in the affected array rather than one merged entry. Documentation, and the kind that stops two tools disagreeing.
SPDX’s only two merges were both @bact and both editorial — #1441 correcting the stated conformance-point count to 14, and #1447 adding a hyperlink for CNSSI 4009. His note on the second one is a small artifact of the world we work in: the CNSS website requires a DoD root certificate installed in your browser to reach it.

Sigstore cut but did not ship. #925 “Prepare for 0.5.2 release” merged August 21, and there is no 0.5.2 release published — the newest release on that repository is a Java artifact from January 2025. A merged release-prep PR means cut, not shipped, and I check that every week for exactly this reason. The substantive merge there was #923 from @loosebazooka adding a custom java_package to envelope.proto.

SPDX’s boards barely moved and the overdue one did not move at all. 3.1-rc2 went 24/44 to 26/44. 3.0.2 is unchanged at 33/38 with a due date of 2026-04-30 — now approaching four months past. Reported, per this issue’s new rule, as project news and not as specification news.

Which matters because of the calendar. OpenSSF published another Cyber Resilience Act podcast on August 18, the third consecutive week they have led with CRA. Their own practitioner’s guide calls it “the September 2026 reporting deadline rapidly approaching.” September starts in eight days. The specifications that would carry that compliance in machine-readable form merged, between them, two editorial fixes and a linter rule.

OCI Image, OCI Runtime, OCI Distribution, SLSA, TUF, Notary Project and OpenFeature all merged nothing.

A gold-edged foundation slab beneath the neon grid, mostly dark and cold, with a single small figure standing alone at one corner where a whole crew of figures worked the week before.

💹 Financial Services Data Standards

Last week I ended on a sentence I now get to grade: “When people ask what a standard actually runs on, this is the answer more often than anyone admits: it runs on somebody.” @julianna-ciq had merged 28 pull requests into FDC3 — 39% of all human specification activity across all thirty repositories.

This week FDC3 merged 13. Twelve were dependabot. One was @julianna-ciq, #2113, bumping the remaining fdc3-conformance dependencies.

I do not know why, and I am not going to speculate about one person’s week. What I will report is the shape: a standard that produced a deprecation removal, four substantive schema merges and a new maintainer seven days ago produced, this week, a dependency sweep. The thesis was that FDC3’s throughput rests on a very small number of people. One week of data is consistent with it. That is all one week of data can be.

FDC3’s flagship milestone went backwards. FDC3 3.0 held at 26 closed while its total grew from 41 to 43 — two issues added, none finished, 63% down to 60%. 3.1 candidates grew from 10 to 11 and remains at zero closed. Project news, not specification news.

CALM shipped cli-v1.56.0 on August 17 — a tool release, the second of the two releases in the window, and the third consecutive week CALM’s tooling has shipped while the CALM schema itself has not. Eight merges, evenly split human and bot: @willosborne added the missing hub push/pull/list interface subcommands to the CLI and trimmed the root AGENTS.md, @ppcvote fixed generated front matter to emit POSIX-style paths, and @byrash fixed requirement-URL display in the VS Code plugin.

A wide bedrock plain beneath the neon grid, a single new gold-edged footing freshly cut and glowing among older weathered ones, all of them bearing an unseen structure above.

🏛 From the Foundations

The Xen Project launched a Shared Functional Initiative for safety-critical systems, announced August 17. The Xen Safety Committee’s stated purpose is a collaborative path to develop and maintain reusable engineering artifacts for functional safety certification — which is a specification-shaped problem wearing different clothes. Safety certification evidence is one of the last places where every organization still builds its own artifacts from scratch, at enormous cost, to say the same things. Worth tracking for whether the artifacts become anything a machine can read.

CNCF graduated Kubeflow on August 17, the second graduation in two weeks after Cloud Native Buildpacks, and framed in the announcement as solidifying a standard for cloud native AI operations.

Egeria 6.0 shipped at LF AI & Data, written up August 20 by project leader Mandy Chessell as part one of a four-part series — a metadata-interoperability project whose whole reason for existing is open exchange formats between data catalogs, and one I should probably be reading more closely than I am.

CNCF’s blog also ran two pieces on sovereignty this week — multi-plane architecture and data sovereignty — which is where a lot of the next round of interoperability requirements is going to come from, whether or not anyone writes them down as specifications.

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

Sixteen of thirty specifications recorded no merged change, no release and no commit in the window — down from nineteen last week, up from twelve the week before.

Finished, not dead — stable and carrying enormous load right now: CloudEvents (1.0.2 since 2022), OCI Image, OCI Runtime and OCI Distribution, Notary Project, TUF, SLSA, xDS.

Quiet and worth watching, where silence is ambiguous and I keep counting the weeks: Overlay (three weeks, milestone board frozen identically, a completed 1.2 unshipped), AsyncAPI Specification (three weeks, 3.0.0 board unchanged at 89%), AsyncAPI community, OpenMetrics (2.0 still experimental), OpenFeature, GraphQL.

SPIFFE is in this list on merges and should not be read as idle — it published the most substantive roadmap in the harvest. That is the limitation of counting pull requests, stated plainly.

Silence that is the answer to a question people keep asking: Moonwalk. Third consecutive week, no activity, last merge March 31, 2025. There is no OpenAPI 4 in progress.

Envoy is excluded from pull-request counting by design — implementation, not specification — so its appearance here means it cut no release, not that it was idle.

An intact glowing stepped structure standing on the neon grid with a thick bundle of conduits running off it into the dark, the far ends severed and hanging loose above the floor, one of them freshly cut and still faintly glowing.

📡 Channel Health

All twenty-five working feeds returned. Volume fell again — 24 items, then 17, now 13.

The finding of the week is Protobuf. It shipped a GA major release on August 20 and the newest version post on protobuf.dev/news is v34; /news/v35/ and /news/v36/ both 404. The v36.0 release notes themselves open with “Protobuf News may include additional announcements or pre-announcements for upcoming changes” and link to a page that has not described the last two majors. If you follow Protocol Buffers through its news channel, you do not know Edition 2026 is being assembled.

The OpenAPI Initiative’s feed has now been silent since July 22 — five weeks, through a full build-system migration, a dropped release date, and a planning board relabeled internal use only. Nothing about any of it reached the announcement channel.

Unchanged since issue one: Sigstore publishes no feed on any path, Envoy’s blog host does not resolve, and OpenSSF’s real feed remains /feed/ while /blog/feed/ and /blog/rss/ both answer HTTP 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) · SPDX (June 2026) · Protocol Buffers (July 2026) · OpenAPI Initiative (July 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 August 16 to August 23, 2026. Merged pull requests are counted by merged_at inside the window. Bot attribution is by author login, with opentelemetrybot counted as a machine. Milestone percentages are GitHub’s own open/closed counts, read live. Week-over-week deltas compare against the two stored harvests, not against memory.

Where this issue makes a claim about what a pull request did, I opened the pull request and read its file list, its diff or its body. The “two words of specification” finding is the file lists of all eleven OpenAPI merges plus the full patch of #5515. The published-versus-draft reading of JSON Schema #1763 is the merged patch against specs/jsonschema-core.md in the repository and against the live documents at json-schema.org/draft/2020-12/. Sigstore’s unshipped 0.5.2 is the releases list on that repository. Protobuf’s missing news posts are two HTTP 404s I fetched myself.

Two things I cannot fully evidence and am flagging rather than asserting: when the OAI milestone description and discussion title changed, because GitHub exposes no edit history for either — I have updated_at timestamps twenty minutes apart on August 21 and no baseline of my own, and I have started recording milestone descriptions so there is a baseline next time. And how six items left milestone 18, because the repository events feed covers the window and records no demilestone events at all.

The standing rule, now applied twice: a merge to a specification repository is not a change to a published specification. Most of these repositories hold the work in progress of the next version while the released artifact lives on the standards body’s own site. Before framing any merge as a defect, a break or a change you should act on, I check which artifact it lands in and whether that artifact is published. If it is a draft, it gets called a draft. Added this week, from the OAI’s own wording: planning boards, milestones and release discussions are project news, never specification news, and the difference gets stated in the text.

Two standing exclusions: Envoy’s pull requests are not counted, only its releases — it is a high-volume implementation repository and including it would drown every real specification in the issue. 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, as the two before it, every source returned.

If a number here is wrong, the repository is the authority and I will correct it — in the next issue, and on this page. The goal of this newsletter is to provide a weekly accounting across the specifications to see where there can be more information sharing, communication, and investment by humans and agents to help get work done, but also potentially align the specs.

Next Monday: whether 3.2.1 actually ships against its September 30 date now that it is fully loaded for the second week running, whether OpenTelemetry’s specification repositories come back after a week with no human in them, and whether the supply-chain layer moves in the last days before the CRA reporting date it has spent three weeks writing about.