---
type: "article"
title: "The Specification Layer — OpenAPI 3.3 Learned to Say What It Depends On"
summary: "OpenAPI 3.3 has a new top-level keyword. `features` lets a description declare which companion specifications it uses — security, lifecycle — and their versions, and the…"
newsletter: "The Specification Layer"
newsletter_handle: "the-specification-layer"
newsletter_url: "https://usecommune.com/n/the-specification-layer"
author: "Kin Lane (@kinlane)"
published: "2026-10-26T15:16:18.257Z"
canonical_url: "https://usecommune.com/n/the-specification-layer/a/week-of-2026-10-25"
markdown_url: "https://usecommune.com/n/the-specification-layer/a/week-of-2026-10-25.md"
chat_url: "https://usecommune.com/n/the-specification-layer/a/week-of-2026-10-25/chat"
body_source: "native"
likes: 0
replies: 0
body_words: 3011
---

# 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 ](https://github.com/finos/calm-schema/tree/v1.3)[`v1.3`](https://github.com/finos/calm-schema/tree/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](https://github.com/finos/FDC3/issues/2298) 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](https://github.com/Agent-Card/ai-catalog/pull/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.](https://kinlane-images.s3.amazonaws.com/apievangelist/api-evangelist-images/newsletter/2026-10-26-the-lead.png)

## 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,"](https://github.com/OAI/OpenAPI-Specification/pull/5447) 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:

```yaml
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](https://github.com/OAI/sig-security/pull/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](https://github.com/OAI/sig-security/pull/57) 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.](https://kinlane-images.s3.amazonaws.com/apievangelist/api-evangelist-images/newsletter/2026-10-26-from-the-room.png)

## 🎙 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](https://github.com/a2aproject/A2A/pull/2153), [#2322](https://github.com/a2aproject/A2A/pull/2322), [#2308](https://github.com/a2aproject/A2A/pull/2308), Oct 19–20 |
| **SLSA** (Mon) | Build Level 4 merged the same day it was reviewed on the call | [#1646](https://github.com/slsa-framework/slsa/pull/1646), Oct 19 |
| **CloudEvents / xRegistry** (Thu) | NATS binding content-mode clarification and an Avro schema fix approved with no objections and merged | [#1399](https://github.com/cloudevents/spec/pull/1399), [#1404](https://github.com/cloudevents/spec/pull/1404), Oct 22 |
| **FDC3** (Thu) | The FDC3 3.0 adoption vote opened, with the community invited to review the draft | [notes #2298](https://github.com/finos/FDC3/issues/2298), Oct 22 |
| **Overlays** (Mon) | Branch-sync workflows and a fuller agenda template merged | [#413](https://github.com/OAI/Overlay-Specification/pull/413), [#414](https://github.com/OAI/Overlay-Specification/pull/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](https://github.com/a2aproject/A2A/pull/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](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) 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](https://github.com/OAI/Overlay-Specification/discussions/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`](https://github.com/x402-foundation/x402/pull/3023)[ scheme specification for XRPL](https://github.com/x402-foundation/x402/pull/3023), [guidance on what a browser needs to read a price and send a payment](https://github.com/x402-foundation/x402/pull/3809), [a v2 spec fix](https://github.com/x402-foundation/x402/pull/3839), 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.](https://kinlane-images.s3.amazonaws.com/apievangelist/api-evangelist-images/newsletter/2026-10-26-the-description-layer.png)

## 📐 The Description Layer

**OpenAPI** — the lead. The [v3.3.0 board](https://github.com/OAI/OpenAPI-Specification/milestone/18) is at 19/40.

**JSON Schema** merged [#1798](https://github.com/json-schema-org/json-schema-spec/pull/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](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/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**](https://github.com/grpc/grpc/releases/tag/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.](https://kinlane-images.s3.amazonaws.com/apievangelist/api-evangelist-images/newsletter/2026-10-26-events-telemetry.png)

## 📡 Events, Telemetry and the Data Plane

**OpenTelemetry released **[**1.62.0**](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.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](https://github.com/open-telemetry/opentelemetry-specification/pull/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](https://github.com/open-telemetry/opentelemetry-specification/pull/5347) makes the OTLP exporter timeout bound the entire batch export. An opt-in metric advisory parameter ([#4809](https://github.com/open-telemetry/opentelemetry-specification/pull/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](https://github.com/prometheus/OpenMetrics/pull/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.](https://kinlane-images.s3.amazonaws.com/apievangelist/api-evangelist-images/newsletter/2026-10-26-identity-policy-supply-chain.png)

## 🔐 Identity, Policy, Supply Chain

**SLSA defined Build Level 4.** [#1646](https://github.com/slsa-framework/slsa/pull/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](https://github.com/opencontainers/image-spec/pull/1336), fixing [#1333](https://github.com/opencontainers/image-spec/issues/1333)), the image specification's first change in weeks.

**SPIFFE merged a proposal for a Filesystem Delivery standard** ([#376](https://github.com/spiffe/spiffe/pull/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](https://github.com/in-toto/attestation/pull/568), 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.](https://kinlane-images.s3.amazonaws.com/apievangelist/api-evangelist-images/newsletter/2026-10-26-financial-data-standards.png)

## 💹 Financial Services Data Standards

**CALM released schema 1.3** — the tag the harvester fix caught. [#41](https://github.com/finos/calm-schema/pull/41) adds optional `target-type` and `$schema` properties to decorators and a **deployment standard**, and [#43](https://github.com/finos/calm-schema/pull/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.](https://kinlane-images.s3.amazonaws.com/apievangelist/api-evangelist-images/newsletter/2026-10-26-the-quiet-ones.png)

## 🤫 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

***

## Discussion

No replies yet.