From 5ea95bbb5845fed49e4a92005586c14c62e4b96c Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 24 Oct 2026 10:02:16 +0000 Subject: [PATCH] docs(downgrader): note that a mutualTLS-only security list is removed in 3.1 to 3.0 An operation's list then falls back to the document's security, and the document's own list leaves no security required. Reword the convertSecurity comment, which said removing a list avoids "no security is needed". Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01J3j7B1BpNEjm9ct3FPQTBD --- packages/downgrader/README.md | 2 +- packages/downgrader/src/v3.1-to-v3.0.ts | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/packages/downgrader/README.md b/packages/downgrader/README.md index 9133402..cab1d34 100644 --- a/packages/downgrader/README.md +++ b/packages/downgrader/README.md @@ -170,7 +170,7 @@ Schema Objects inside the document convert as in [Schema](#schema-downgradeschem - `$ref`s into removed parts are recognized by their `#/webhooks/` or `#/components/pathItems/` prefix as written, not percent-encoded. - Links and discriminator `mapping` values that point into a removed part, and Links that name a webhook operation by `operationId`, are left as written. - Encoding Objects pass through, although 3.0 serializes `multipart` parts by other defaults: it ignores `style`, `explode`, and `allowReserved` there, and gives an untyped part no `application/octet-stream` default. -- An operation whose only `security` alternatives use mutual TLS loses its `security`, so it falls back to the document's. +- A `security` list whose alternatives all use only mutual TLS is removed. On an operation it then falls back to the document's `security`, and on the document it leaves none, so no security is required. ### Schema (`downgradeSchemaV31ToV30`) diff --git a/packages/downgrader/src/v3.1-to-v3.0.ts b/packages/downgrader/src/v3.1-to-v3.0.ts index 9b6314c..2a0fe60 100644 --- a/packages/downgrader/src/v3.1-to-v3.0.ts +++ b/packages/downgrader/src/v3.1-to-v3.0.ts @@ -741,9 +741,11 @@ function schemeType(scheme: unknown, ctx: Context): unknown { } // 3.0 has no mutual TLS, so security requirements lose the schemes that use -// it. A requirement left empty is removed, and so is a list left empty, -// because an empty one would mean that no security is needed. 3.0 also -// allows scopes only for OAuth2 and OpenID Connect. +// it. A requirement left empty is removed, because an empty one would mean +// that no security is needed. A list left empty is removed too, so an +// operation falls back to the document's `security`, though the document's +// own list then needs no security either way. 3.0 also allows scopes only for +// OAuth2 and OpenID Connect. function convertSecurity(value: unknown, ctx: Context): unknown { if (!Array.isArray(value)) { return clone(value)