The Specification Layer — OpenAPI 3.3 Learned to Say What It Depends On

This is the twelfth issue of The Specification Layer. This newsletter window: October 18 through October 25. Thirty-six specification repositories and twenty-five feeds, all read clean for the twelfth consecutive week. 174 pull requests merged. 7 releases cut. 23 posts published. Ten of the thirty-six did not move. The two release-path dependencies merged 1. Last week's fix earned its keep. After SPDX 2.3.1 shipped as a git tag that my harvester never saw, I taught it to count new tags as releases. This week it caught one: CALM's v1.3, a tag with no GitHub Release object behind it, and the first change to the CALM schema since August. Without the fix, this issue would have told you CALM's schema hadn't moved. Predictions from last week, graded: Prediction Result MCP's release-timeline post confirms no December specification release Open. SEP-3398 was voted through on October 14 but is still unmerged, and no post has appeared. FDC3 3.0 final by the end of November Open, moving. The October 22 notes open the adoption vote. No result yet; v3.0.0-beta.1 is still the newest release. The A2A AI Catalog ships its 0.9 release candidate before AgentCon Wrong. AgentCon came and went — the catalog's own Thursday call was all but cancelled because most of the group was there — with no 0.9 tag and #117 still open. The OpenAPI security proposal gets its complete example before its first approval Open, and quiet since September 25 — though the security work moved in a different direction this week. Arazzo 1.2 by mid-November At serious risk. Arazzo merged two dependency bumps. The three feature pull requests are all still open. PDPP locks v0.1.0 on October 26 Graded next week — the date falls outside this window. ORD 1.18 by the end of the year Open. Beneath the neon grid, a great gold load-bearing slab with a row of small empty sockets along its edge, and from two of the sockets thick gold cables running down into separate smaller foundation chambers, tiny figures carrying a heavy block out of the main slab into one of the side chambers. The Lead: OpenAPI 3.3 Learned to Say What It Depends On On October 22 the OpenAPI Initiative merged #5447, "v3.3: First pass at explaining SAFs," into the 3.3 development branch. It was opened in July, reviewed by eight people, and approved by @mikekistler and @miqui before @lornajane merged it. It adds a new top-level keyword to OpenAPI, and it changes what the core specification is responsible for. Standardized API Features. The merged text defines them as "features defined by other standards bodies and referred to from an OpenAPI Description," specified for OpenAPI in companion specifications that are "versioned independently of this specification." The reasoning is the one I have heard argued on the community calls all autumn: "Many SAFs have behavior that is difficult or impossible to infer from descriptions of paths, parameters, headers, or other operation elements, and so benefit from special handling. For example, the Authorization header is managed through the Security Scheme Object rather than the Parameter Object." The keyword is features. A map from a companion specification's name to a version: openapi: 3.3.0 features: security: 1.0.0 lifecycle: 1.1.0 Three details matter if you build tooling: The default preserves 3.2. With no features field, a 3.3 document behaves as if it said security: 1.0.0 — the Security Scheme, OAuth Flows and Security Requirement objects work as they always have. But if you give an explicit features value, you must list security yourself to keep it. Multi-document descriptions must agree. "Implementations MUST raise an error if different SAFs are included in different documents within the OAD," and SHOULD raise one when versions are incompatible. It is a deliberately strict, fail-fast rule — the kind that can be relaxed later and can't easily be tightened. Compatibility is spelled out. Only major and minor versions count, 3.1 is compatible with 3.2, which is compatible with 3.3, and "OAS 3.0 is not compatible with any other version." And the security objects started moving out the same day. sig-security #51, from @handrews, copies the Security Scheme and OAuth Flow objects and their schema definitions out of the OpenAPI Specification into the security group's repository, merged 22 minutes before #5447. Its description is candid about scope: "This just moves things over so we can iterate on any necessary changes." The objects have not yet been removed from the core document, so nothing breaks. Read it as a draft, and read it carefully. Both changes are on development branches (v3.3-dev and v1.0-dev); nothing is published. And there is already one inconsistency to fix: the prose says the default is {"security": "1.0.0"}, while the JSON Schema the same pull request adds declares default: security: '1.1.0'. That is exactly what a first pass is for — but if you are prototyping 3.3 support from the schema, it is worth knowing which number to trust. Why it matters. Since the Swagger days, everything an OpenAPI description could say about security lived inside OpenAPI itself, versioned with it. From 3.3, the core specification describes HTTP, and the things that change faster than HTTP — security first, deprecation and sunset next — get their own specifications and their own release cadence. It's the right separation, and it makes OpenAPI a document that declares its dependencies. It also means tooling has a new question to answer on every file: which features does this description use, and do I support those versions? I was on the community call where the remaining questions were worked through, and the minimal GNAP proposal that came next — a bare-minimum security scheme for GNAP's runtime-negotiated access — is still open for review. The security group also has a registry gap I should own: OAI/sig-security is not in my registry. It joins next issue, alongside the OpenAPI repository it now carries part of. A long row of small hexagonal meeting chambers set into a dark foundation wall beneath the neon grid, tiny figures around tables in cool blue light, and from several of the chambers a thin gold line running down into a common channel in the floor. 🎙 From the Room: Fourteen Sessions, and the Agent Protocols Converge Eighth week of this section. Fourteen sessions in the groups' public recordings and notes, and I sat in on the OpenAPI community call and the Overlays call. Outcomes only, each checked against the repository. Room Outcome On the record A2A TSC (Tue) Bidirectional SendLiveMessage merged into the 1.1 work; clients can now write artifacts through SendMessageRequest; Bloomberg joined the Technical Steering Committee #2153, #2322, #2308, Oct 19–20 SLSA (Mon) Build Level 4 merged the same day it was reviewed on the call #1646, Oct 19 CloudEvents / xRegistry (Thu) NATS binding content-mode clarification and an Avro schema fix approved with no objections and merged #1399, #1404, Oct 22 FDC3 (Thu) The FDC3 3.0 adoption vote opened, with the community invited to review the draft notes #2298, Oct 22 Overlays (Mon) Branch-sync workflows and a fuller agenda template merged #413, #414, Oct 20 OpenAPI community call (Thu) The security-object move and the features keyword — the lead Oct 22 The one I want to dwell on came from A2A's repository the next day. #2240, merged into the 1.1 development branch on October 21, rewrites A2A's agent-discovery guidance to make the AI Catalog — /.well-known/ai-catalog.json — the "Preferred" mechanism, keeping /.well-known/agent-card.json as an option with documented limits. The reason it gives is concrete: the agent-card path "only supports advertising a single Agent Card per domain. This breaks multi-agent and multi-tenant deployments." A2A's own IANA-registered path now carries a SHOULD pointing at the catalog. Three weeks ago MCP Server Cards handed domain-level discovery to the AI Catalog. Now A2A's draft does the same for agents. Two of the agent protocols, converging on one front door — while the AI Catalog itself is still waiting on its 0.9. That combination is worth watching: the catalog is becoming load-bearing before it has shipped. On the Overlays call the group worked through RFC 3986 terminology for relative references and the purpose-statement wording in discussion #412; I'm a participant in that thread, so read my view there, not here. No specification text changed. Announced, not landed by Sunday: A2A 1.1 (still at v1.0.1). The AI Catalog's 0.9 and #117. FDC3 3.0 final. MCP's progressive-disclosure primitive, deferred to a vote at the group's next meeting. No outcome: the AI Catalog call (most of the group was at AgentCon), MCP's interest groups (process decisions only), OpenFeature, Envoy's AI gateway, and the CNCF MCP authentication initiative. The split Who merged it Count Share dependabot[bot] 23 13% copybara-service[bot] 16 9% renovate[bot] 7 4% mintlify[bot], claude[bot] 3 2% All bots 49 28% Actual people 125 72% Twelve readings: 59% machine, 54%, 72%, 59%, 36%, 41%, 41%, 47%, 43%, 52%, 42%, 28% — the most human week this newsletter has recorded. Merges Human Human share The six newest rows 109 98 90% …of which x402 66 64 97% The established thirty 65 27 42% All thirty-six 174 125 72% The headline 72% is mostly x402, which merged 66 — more than the established thirty combined. Under my rule for that monorepo, four touched the specification: a new upto scheme specification for XRPL, guidance on what a browser needs to read a price and send a payment, a v2 spec fix, and one Solana fix that touched both. Eight of x402's merges were by PhilBot402, the machine account counted as a person under the login rule; counted as machines, the week is 33% machine. The established layer was 42% human, up from 28%. A deep foundation workshop beneath the neon grid where two tiny figures check a single new gold beam against a long row of older ones while a crew of small automated arms works quietly further down the hall. 📐 The Description Layer OpenAPI — the lead. The v3.3.0 board is at 19/40. JSON Schema merged #1798 from @jdesrosiers, supporting links to sections in other documents — tooling for the specification's own text. ORD polished its 1.17 guidance. Overlay merged the two workflow changes above; Arazzo merged two dependency bumps. MCP reorganised its working groups. #3440 forms a Tasks and Events Working Group, combining the Tasks scope from the Agents group with the events and triggers scope, and turns Agents into an Interest Group. It was written by claude[bot] at David Soria Parra's request and merged by him — the same pattern as the SEP rule I reported in issue #09. gRPC shipped v1.84.1 and bumped its 1.85 branch; Protocol Buffers merged 16, all copybara. AsyncAPI, GraphQL and Moonwalk merged nothing. Moonwalk: twelfth week, last merge March 31, 2025. An underground junction hall beneath the neon grid where rows of glowing gold nodes stretch into the distance, and tiny figures turn a large valve at the junction to limit the flow through a gold pipe. 📡 Events, Telemetry and the Data Plane OpenTelemetry released 1.62.0, rolling up the sampler shutdown operation, the journald mapping and the entity-aware resource detectors I reported over the past three weeks. Two merges this week deserve more than a changelog line. #5357 adds a security exception to the versioning rules: until now the SDK stability rules left "no explicit security exception for changing documented behavior, configuration defaults, or supported values," which made it hard to add safeguards against unbounded telemetry without breaking stable release lines. And #5347 makes the OTLP exporter timeout bound the entire batch export. An opt-in metric advisory parameter (#4809) landed too. CloudEvents merged the two fixes in the room table. The specification is stable at 1.0.2 — finished, not dead. OpenMetrics updated its maintainers list (#325), its first merge in two weeks. Envoy shipped patch releases on four lines, tracked for releases only. A long underground archive of stacked plain gold slabs beneath the grid, where tiny figures fit one more heavy layer onto the top of a tall stack while the long rows of older stacks run on into the distance. 🔐 Identity, Policy, Supply Chain SLSA defined Build Level 4. #1646 from @arewm adds a new requirement, Dependencies complete: the build platform "MUST have technical controls ensuring all artifacts consumed during the build are recorded in resolvedDependencies." Pre-fetching in the trusted control plane, network interception or vendoring all qualify — network isolation is not required — and a complete build-time SBOM can satisfy completeness. It "resolves the longstanding Build L4 workstream." It is in SLSA's development draft, not a released version. OCI deprecated ImageID in the image configuration (#1336, fixing #1333), the image specification's first change in weeks. SPIFFE merged a proposal for a Filesystem Delivery standard (#376). Kubernetes Pod Certificates and Cluster Trust Bundles, going GA in 1.37, deliver keys, certificates and trust bundles to a pod's filesystem; the proposal is a common standard for doing that with SPIFFE identities — the Workload API, through the filesystem instead of a socket. A proposal document, not an adopted standard. in-toto merged seven, including runtime-trace v0.2, which defines the shape of network entries in the monitor log. SPDX added the term component to its definitions. TRACE merged 32, 27 by people. PDPP merged eight ahead of its lock date. OSV Schema, TUF, OCI Runtime, OCI Distribution and Notary Project merged nothing. An underground hall beneath the neon grid where a tall gold lattice framework stands complete, and a row of tiny figures at its base raising their hands together. 💹 Financial Services Data Standards CALM released schema 1.3 — the tag the harvester fix caught. #41 adds optional target-type and $schema properties to decorators and a deployment standard, and #43 adds a control evaluation decorator standard. The pull request is careful about scope: target-type allows only architecture for now, though a draft schema in the tooling repository allows more, and "a later minor release can add them." The first schema change since August. FDC3 3.0 went to its adoption vote on October 22. The repository merged nine, all dependabot. x402 — four specification changes, in the split above. 🏛 From the Foundations AgentCon took most of the agent-protocol community out of their weekly calls this week, and the repositories show it: A2A's work went into branches, the AI Catalog stood still. Bloomberg joining A2A's Technical Steering Committee is the governance move worth noting. SpecRef, a release-path dependency, merged one alias. A long subterranean colonnade of tall plain dark monoliths receding into blackness, their edges traced in cold gold, most of them unlit and silent while the load-bearing neon grid floor runs on past them. 🤫 The Quiet Ones Ten of thirty-six — 12, 19, 16, 13, 15, 19, 14, 15, 14, 11, 10, now 10. Finished, not dead: xDS, OCI Runtime, OCI Distribution, Notary Project, TUF. Quiet and worth watching: Arazzo, whose 1.2 is slipping in plain sight. AsyncAPI, whose specification repository has merged only dependency bumps for weeks. GraphQL. OSV Schema. Open Component Model, as expected. Silence that is the answer to the question I get asked most: Moonwalk. Twelfth consecutive week. 📡 Channel Health All twenty-five working feeds returned for the twelfth consecutive week. Volume: 23 items, from 19. The OpenAPI Initiative's feed has now been silent for fourteen weeks — in the week its specification gained a new top-level keyword. The work is real; the channel isn't carrying it. How This Was Made One harvest run against the GitHub REST and GraphQL APIs and twenty-five feeds, October 18 to October 25, 2026. Merged pull requests are counted by merged_at inside the window. A release is a GitHub Release or a new tag — the rule added last week, which caught CALM 1.3 this week. Bot attribution is by author login; machine accounts with ordinary logins are counted as people and disclosed. Milestone values are GitHub's own. Where this issue says what a pull request did, I opened it and read its body or its diff. The lead quotes the merged text of #5447 and its schema, and #51's description. The A2A discovery change is from #2240's description and files. Meetings. I attended the OpenAPI community call and the Overlays call; neither has a public recording, so from them I report only what the repositories confirm. From every room I report outcomes only, each checked against the repository or the group's published notes. Standing rules: a merge to a development branch is not a published specification — this week that covers OpenAPI 3.3's features, the security-object move, A2A's discovery change, SLSA Build L4 and SPIFFE's proposal. Milestones are project news; a milestone is not a release. Report the dependencies: OAI/build-infra merged nothing, specinfra/specref one. Predictions on the record: the features default inconsistency (1.0.0 in the text, 1.1.0 in the schema) is fixed before 3.3 reaches a release candidate. OAI/sig-security joins the registry next issue. The AI Catalog ships 0.9 before the end of November. FDC3 3.0 final by the end of November (carried). PDPP locks v0.1.0 on October 26 (graded next week). Arazzo 1.2 by mid-November (carried, at serious risk). ORD 1.18 by the end of the year (carried). You are receiving this because you subscribed to this newsletter. Unsubscribe 606 W 57th New York, NY 10019