The Specification Layer — OpenAPI's Security Proposal Is Now a Pull Request

This is the eighth issue of The Specification Layer. This newsletter window: September 20 through September 27. Thirty-two specification repositories and twenty-five feeds, all read clean for the eighth consecutive week — no source errored. 144 pull requests merged. 6 releases cut. 20 posts published. Fifteen of the thirty-two specifications did not move. The two release-path dependencies merged 11 between them. This week I also read the rooms at a scale I have not before: six working-group calls I attended, and the public recordings and published notes of fifteen more. What that produced is its own section below, and the short version is the most useful thing I learned this week: the rooms are where things are argued, and the repositories are where they happen. I am reporting outcomes from the rooms, not the arguing. Predictions from last week, graded: Prediction Result Chris Wood's security proposal becomes a pull request within two weeks Right. OAI/sig-security #54, "Formal submission of security profile proposal to SIG," opened September 25 — eight days — at 812 lines. The lead. SPDX 3.1-rc2 misses September 27 Right. The milestone closed its due date at 34 of 49, open. The newest tag is still v3.1-RC1, from January. Arazzo 1.2 by mid-November Seven weeks to run. None of the four feature pull requests merged this week. Deep beneath the neon grid, a finished gold tablet waits on a lit lift platform at the bottom of a tall shaft whose cables hang slack, while a few tiny figures look up toward the closed opening above. The Lead: OpenAPI's Security Proposal Is Now a Pull Request On September 17 I sat in the OpenAPI TDC call while Chris Wood walked five people through roughly seven thousand words in his fork: a rethink of how OpenAPI describes security, built around FAPI 2.0 and GNAP. I wrote that it was the largest design change proposed to OpenAPI's security model that I was aware of, and predicted a pull request within two weeks. Here is how it went, entirely from the public record: Sep 24, 16:45 UTC During Thursday's TDC, @mikekistler on the agenda issue: "We discussed your topic and agreed that the sig-security repo is the right place." Sep 24, 17:57 @handrews opens sig-security #51 — move the existing Security Scheme and OAuth Flow(s) Objects, and their schema $defs, from the OpenAPI Specification into the Security SIG repository, "so we can iterate on any necessary changes." Open. Sep 24, 23:02 #52 merged — a proposals/ directory, because "the one proposal was just sitting at the root." Sep 25, 16:26 @SensibleWood opens #54, "Formal submission of security profile proposal to SIG": proposals/2026-09-25-Security-Profiles.md, 651 lines, and two diagrams. Sep 25, 17:04 The first review request lands on it. Eight days, and the prediction is graded right. The more interesting part is what was decided on the way: not whether OpenAPI's security model changes — nobody has decided that — but where the work lives. The TDC put it in the Security SIG, and the objects it would replace were proposed for a move there the same evening. What the proposal says The problem statement, from the pull request: OAuth Flow Objects require a fixed, static metadata footprint — tokenUrl, authorizationUrl and the rest — that duplicates the real source of truth, OAuth Server Metadata and OpenID Connect Discovery, risks drifting from it, and has no room for the constraints a profile like FAPI 2.0 adds on top of plain OAuth 2.0. OpenAPI can describe the shape of a credential; it cannot describe how to obtain one correctly. The answer is three layers, each with a named owner: Layer Purpose Maintained by OpenAPI Security Specification (OSS) A separate vocabulary of security primitives — Discovery, MTLS, JSON Web Token, Credential, Access Request, Token, Pushed Authorization Request, OAuth Profile — each grounded in a specific RFC Security SIG Security Profile Framework The additional constraints a profile such as FAPI 2.0 layers on the OSS vocabulary A Security Profile working group Ecosystem Registry Jurisdiction- or industry-specific tailoring of a profile — the UK, Brazil, Saudi and UAE open-banking variants of FAPI 2.0 Ecosystem teams Every object carries an implements property pointing at the RFC, BCP or profile it conforms to — "a deterministic hook back to the source of truth" for humans and for agentic tooling alike. Request and consent content is always by reference to a Schema Object, never embedded in the security layers. FAPI 2.0 maps onto the profile framework; GNAP, a standalone protocol rather than an OAuth profile, is proposed to live largely in the OSS itself, with its discovery and access-request split listed among the open questions. The first review asks the right question. Carried over from the informal review, @handrews: "could you add a complete OAD example showing how this all fits together with real endpoints, and walk through how a tool is expected to process the instructions?" A proposal whose whole purpose is giving tools enough information to perform the auth should be judged on exactly that, and the request is on the record before any approval. What this is and is not. It is a proposal document in a SIG repository, open, with no reviews and — per its own checklist — no schema changes. Nothing in the OpenAPI Specification has changed. #51 proposes a move; it has not happened. And one thing to note flatly, in keeping with the running list this newsletter keeps: #54's description ends with a "Generated with Claude Code" line. SLSA disclosed LLM assistance in a PR body in August, FDC3 merged an agent-authored documentation change this month, and now the largest proposed change to OpenAPI's security model arrives with its tooling visible. I report it because it is on the page, not to weigh the work by it. And the rest of OpenAPI's blockers closed Last week OpenAPI merged zero, and I put it down to three things: a broken branch sync, a blocked schema publication, and a release-docs pull request nobody had merged. The schema published last week. This week the other two closed: The sync. #5550, the automated dev ← main sync, had sat open since September 10 because a file kept disappearing. @handrews opened #5555, "Don't delete files we need on sync," on Wednesday; it merged Thursday at 16:28 UTC, and #5550 merged at 16:54 — inside the TDC hour — followed by the three version-branch syncs. The instructions. #5553 from @lornajane, "Improve the instructions for specification releases" — patching "the traps I fell into or found confusing this time around" — open since September 12 with two approvals, merged September 22. Six merges, two by people, and those two are the whole unblocking. Taken with the security week above, OpenAPI went from its quietest week in this newsletter's history to its most consequential in a month without merging a single change to the specification text. A long row of small hexagonal meeting chambers set into a dark foundation wall beneath the neon grid, each holding tiny figures around a table in cool blue light, and in just one chamber a small gold block glowing as a figure sets it into place. 🎙 From the Room: Twenty-One Sessions, Five Outcomes Fourth week of this section, and the first where I read every room I could reach rather than only the ones I sat in: six calls I attended — the AsyncAPI governance board, JSON Schema office hours, the OpenID Foundation's FAPI working group, the A2A AI Catalog weekly, and the MCP Agents and Transports working groups — plus the public recordings and published notes of fifteen more across A2A, OpenTelemetry, SLSA, CloudEvents, OpenFeature, a CNCF MCP initiative, OCI, FDC3, JSON Schema and MCP. Rule for this section, from now on: working meetings are not publications. A room discussing a budget, weighing a proposal, or planning a release is doing its job, and none of that is news until the group writes it down or merges it. I report what came out of a room and landed on the public record, and I leave the deliberation where it was. By that rule, here is what the week's rooms produced: Room Outcome On the record OpenTelemetry Semantic Conventions SIG (Mon) Improved host.id definition merged during the call — lookup priority order, known environments, fallback behaviour semantic-conventions #3916, 15:20 UTC A2A TSC (Tue) Coherent task history — timeline and artifact ordering, ADR-002 — merged that morning and reported to the TSC a2aproject/A2A #2129, 11:38 UTC MCP Inspector V2 working group (Wed) Inspector 2.8.0 released, including the v2 line merged to main inspector 2.8.0, 18:16 UTC FDC3 Standard working group (Thu) Conformance tests versioned with the Standard documentation FDC3 #2233, 12:47 UTC MCP Primitive Grouping interest group (Mon) Agreed to rename itself Progressive Disclosure — agreed, not yet done: the docs pull request is open meeting notes Five of twenty-one. The other sixteen were real work — design debate, review, drafting — and some of it will be news in a month. It is not news this week, and I would rather report it when it lands than describe it while it is still being argued. One more outcome belongs to last week's room and closed this week: Chris Wood's security proposal, now sig-security #54 — the lead. On MCP and this newsletter's scope. Last week I noted that MCP is not in the registry while its foundation launched a certification for it. MCP joined the Agentic AI Foundation, a Linux Foundation directed fund, on December 9, 2025, so the scope rule this newsletter is built on — the specification layer, LF-anchored — now includes it. MCP's working groups publish their own notes, which is how it appears in the table above. Its repository is not yet in the merge count; adding it changes every week-over-week comparison, so it will join the way TRACE and PDPP did, reported alongside the established thirty rather than inside them. Method note: outcomes from calls I attended are from my notes, and every one of them was checked against the repository before it went in the table. Outcomes from calls I did not attend come from the groups' own public recordings and notes, again checked against the repository. Where a room said something was done and the repository did not show it, it is not in the table. The split Who merged it Count Share copybara-service[bot] 40 28% dependabot[bot] 16 11% renovate[bot] 7 5% oai-spec-publisher[bot] 4 3% All bots 67 47% Actual people 77 53% Eight readings: 59% machine, 54%, 72%, 59%, 36%, 41%, 41%, 47%. Merges Human Human share TRACE + PDPP 41 34 83% The other thirty 103 43 42% All thirty-two 144 77 53% The established layer fell back from 50% to 42% human. Not because people did less — Protocol Buffers alone merged 35, all imported by copybara, against 29 last week. The human work was spread wide and thin: CALM ten, SPDX six, OSV Schema six, FDC3 six, OpenTelemetry three. SPDX and CALM were 100% human. TRACE and PDPP, at 41 merges, climbed back from last week's 34. A long conveyor of gold components deep in the understructure beneath the grid, freed after a jam and moving again toward a lift at the far end, a small crew of tiny figures stepping back to watch. 📐 The Description Layer OpenAPI — the sync fix and the release instructions are in the lead. Two boards, as project news: v3.3.0 holds at 19/39 for a fifth week, still labelled internal use only. The v3.2.1 milestone is still open at 10/10 against a September 30 due date — although 3.2.1 itself shipped on September 10. A finished board nobody closed. The \d thread closes. The current published 3.2 schema, 2026-08-30, carries ^3\.2\.[0-9]+(-.+)?$; the two earlier dated schemas keep \d, which is what dated, published artifacts should do. I will stop checking. Arazzo merged three, all bots, and the four pull requests that make up 1.2 and 1.3 are all still open: #533 SOAP (approved September 16, twelve days unmerged), #556 Protobuf RPC, #567 GraphQL, #568 actor-in-the-loop. The group's stated plan is to land them together; mid-November is seven weeks away. GraphQL's draft caught up. Last week the five changes merged on September 17 were not yet in the continuously built draft. They are now — the @oneOf inhabitability text from #1211 is in the page this morning. Accepted and in the draft; the newest edition is still September 2025. The repository merged nothing this week, as batching predicts. Protocol Buffers merged 35, all copybara, and announced breaking changes for v38, expected in the first quarter of 2027: Bazel 9 becomes the minimum and Bzlmod is required, several deprecated build flags and the internal_py_proto_library API are removed, and @system_python is replaced by rules_python. Read the list and every item is build and toolchain — none touches the wire format or the .proto language. It is the most useful advance notice the project has published this year, and it came through the dated news page, not the per-version pages that still 404 (below). gRPC merged seven, two human. AsyncAPI re-added a TSC member. #3635 returns Ruchi Pakhle to the TSC and the bot-generated #3636 updates the roster file — one addition, nobody removed. The specification repository merged nothing, a second fully silent week; the 3.0.0 board holds at 25/28. JSON Schema merged nothing for a third week. Moonwalk: eighth consecutive week, last merge March 31, 2025. There is still no OpenAPI 4. A vast underground junction hall beneath the neon grid, rows of glowing gold junction nodes linked by conduits, one small figure locking a single new node into place among hundreds already lit. 📡 Events, Telemetry and the Data Plane OpenTelemetry stabilised one more Prometheus conversion and specified entity startup. Six merges, three human: #5213 — Prometheus → OTLP: Unknown metrics marked stable. The fourth Prometheus-exporter stabilisation from @dashpole in eight weeks. #5057 from @dyladan — the entities SDK startup specification: SDK behaviour for entity detection, and a Resource Provider that combines it with existing resource detection and merge semantics, with rows added across the language compliance matrices. In semantic conventions, #3916 — the host.id definition, merged during its SIG call (above). Two published stories: OpenTelemetry opened its 2026 Governance Committee election (nominations due October 16), and the OpenTelemetry and Prometheus projects published the results of their interoperability survey on consecutive days, one post on each project's blog. OTLP merged two, both bots. The latest specification release is still v1.61.0 from September 14. CloudEvents, OpenMetrics, xDS and Envoy merged nothing. CloudEvents is stable at 1.0.2 — re-verified this week against the project's release notes, which date it 2022/02/05; the Git tag was re-pointed by a fixup in August 2025, which is why the tag's commit date is misleading. Finished, not dead. A long underground archive of stacked gold ledger plates beneath the grid, tiny figures with lanterns checking the seal on each plate, one section of shelving further along still empty and dark. 🔐 Identity, Policy, Supply Chain SPDX missed 3.1-rc2, as predicted, and did careful annex work instead. Six merges, all human. #1475 from @zvr adds recommended license-expression casing to the annex — operators in capitals, licenses as they appear in the License List — which settles a question every SBOM tool answers slightly differently. @bact landed two 2.3.1 fixes and two new references (QUDT, and PMBOK for the operations profile). The 3.1-rc2 board ended its due date at 34/49 — and its total grew by three during the week. There is no new date. OSV Schema shipped v1.9.1 on September 24: language suffixes for the Echo ecosystem (including Echo:NuGet), an RHLW prefix for Red Hat Lightwell, and documentation of network-dependent package checks. Nine merges, six human. TRACE shipped v0.11.0 and merged 29, 23 human. The normative one is #408: which text takes precedence, and which specification revision, schema digest and verifier a conformance claim must name. A run of hardening fixes — strict signature decoding, malformed-versus-missing signatures, ECMA regex boundaries in record validation — reads like a specification preparing to be implemented by people who are not its authors. #413 proposes profile requirements for stateless MCP transcripts; a proposal, reported as one. PDPP shipped v1.12.1, twelve merges, eleven by @tnunamak, including recording who approved a grant when it is not the data subject (#378). OpenFeature added a requirement — to the draft. #428 adds Requirement 4.4.8: an error in an after hook returns the default value. It is on main; the latest released specification is v0.9.0 from July, which does not contain it. The author chose a new requirement over widening 4.4.7 and said in the pull request that the choice was "the part worth deciding rather than assuming." One release adjacent to the layer: the CNCF distribution registry shipped v3.1.2 on September 24, a security release in which the registry client now verifies content against the requested digest. It came up on the OCI weekly call. It is an implementation, not an OCI specification — image-spec and distribution-spec are both still at v1.1.1. SPIFFE merged a typo fix. Sigstore protobuf-specs merged two, both bots. OCI Image, OCI Runtime, OCI Distribution, in-toto, SLSA, TUF and Notary Project merged nothing. An underground hall beneath the neon grid where tiny figures walk a lit path of gold stepping stones while beside them a large gold lattice framework rises in stages against plain dark walls. 💹 Financial Services Data Standards FDC3 cut two 3.0 alphas in two days. v3.0.0-alpha.4 on September 22 and alpha.5 on September 23, both pre-releases. The change that matters between them is #2243: the Standard package now reports version 3.0, not 2.2, in getAgent and the Web Connection Protocol hello — the moment an implementation starts identifying itself as the next version. #2233 versions the conformance suite with the Standard documentation, and #2001 improves how the REST (OpenAPI) parts render on the site. The 3.0 board reads 41/50 — one closed and three added in a week, which is what a milestone looks like as a release approaches and scope gets written down. Separately, a proposal for an FDC3 Payments Adaptor was closed by its own proposer and moved into the open pull request #2204 after the working group reviewed it. CALM merged ten, all human, and broke its release streak. Seven consecutive weeks of CLI releases ended — the last is cli-v1.60.1 from September 16. The work went into teaching: @rocketstack-matt landed a CALM Lab — lessons defined as data, the first three on creating a node, connecting nodes and adding interfaces — and a fix making the lab's commands match the real CLI. Error reporting also improved in two places, pointing at the actual location of a duplicate unique-id or a timeline problem. 🏛 From the Foundations LF Decentralized Trust added fifteen members including Swift and Wells Fargo, and announced a tokenization project, Panarus, and a cross-ledger protocol lab, CLPR. A protocol lab is exactly what the standing rule says to check; I found no public repository for CLPR yet. Noted, not tracked. OpenSSF and CNCF TAG Security announced the Fall Security Slam, October 5 to November 6. The CNCF blog ran "Which hat am I wearing right now?" on neutrality when an employer pays your salary, which I would put in front of anyone who sits in the rooms above. SpecRef merged two bibliography fixes (WHATWG's SERIAL migration, W3C's SHACL rename). Its governance thread, #959, has had no comment since September 11 — third quiet week. Still following. 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 them. 🤫 The Quiet Ones Fifteen of thirty-two — 12, 19, 16, 13, 15, 19, 14, now 15. (Last week I printed fifteen; the harvest recorded fourteen — OpenAPI and Overlay were quiet, OCI Image was not. Corrected on that page.) Finished, not dead — stable, shipped, carrying load: CloudEvents (1.0.2, February 2022), OCI Image, OCI Runtime and OCI Distribution (all at v1.1.1), Notary Project, xDS, TUF, in-toto. Quiet and worth watching: JSON Schema — third week; the work is at the IETF. AsyncAPI — second fully silent week. GraphQL — back to zero after last week's batch of five, exactly as batching predicts. SLSA — quiet in the repository, meeting weekly. OpenMetrics. Off this list since last week: OpenAPI — the sync that was broken got fixed. Envoy merged nothing in the window and shipped no release; it is an implementation, tracked for releases only. Silence that is the answer to the question I get asked most: Moonwalk. Eighth consecutive week. An intact glowing gold structure standing in a foundation chamber beneath the grid, several dark severed conduits hanging off its sides and lying unlit across the floor, reaching nothing. 📡 Channel Health All twenty-five working feeds returned for the eighth consecutive week. Volume: 20 items, the same as last week. The OpenAPI Initiative's feed has been silent since July 22 — ten weeks — and has still not mentioned OpenAPI 3.2.1, released September 10, or this week's security proposal. Protocol Buffers, re-verified this morning: /news/v35/ and /news/v36/ both still 404 — sixth week — while the dated news page carried the most useful notice the project has published this year. The feed is fine; the per-version pages are what broke. 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) · OpenAPI Initiative (July 2026) · AsyncAPI (August 2026) · OpenFeature (August 2026) · SPIFFE (August 2026) · FINOS (September 3) · SPDX (September 9). 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 20 to September 27, 2026. Merged pull requests are counted by merged_at inside the window. Bot attribution is by author login. Milestone values are GitHub's own, read live and stored week over week. Where this issue makes a claim about what a pull request did, I opened it and read its body or file list. The security timeline is the timestamps on #5554, #51, #52 and #54, and the description of the proposal is its own pull request body, quoted rather than paraphrased where it matters. The GraphQL draft claim is a sentence from #1211's diff found in the rendered draft page. The CloudEvents date is the project's own release notes. Meetings. From the rooms, I report outcomes only — something decided, merged, released or published — and each one was checked against the repository before it went in. Outcomes from calls I attended are from my notes; the rest come from the groups' own public recordings and published notes. Discussion, budgets, plans a group has not yet published, and personal matters are left out — a proposal counts once it is filed publicly, and is reported as a proposal — including where a room described something as done and the repository did not yet show it. Standing rules, applied throughout: a merge to a specification repository is not a change to a published specification — check the artifact at its canonical URL, and say draft when it is a draft (this week: OpenFeature 4.4.8, and the security proposal). Milestones and planning boards are project news, never specification news. The registry is a source of findings, never a boundary on them. Report the specifications' dependencies as well as the specifications — OAI/build-infra and specinfra/specref merged 11 between them and are counted separately from the 144. A claim repeated every issue gets re-verified every issue. Predictions on the record: the security proposal gets its complete OpenAPI description example before it gets an approval. Arazzo 1.2 by mid-November with SOAP and Protobuf/RPC. The schema-date question comes back the next time a 3.2 schema changes. And MCP's repository joins the registry as a new row, reported alongside the established thirty. Unsubscribe | 606 W 57th New York, NY 10019