Skip to content

Schema URLs: a missing stable version is served silently as another version, and 3.2 is a 404 while v3.2 works #8958

Open

Description

@KonstantinMirin

adcontextprotocol.org answers a request for a stable version that doesn't exist with another version's file and a 200, and its version spellings don't overlap: v3.2 works but 3.2 is a 404. I'd like to send the fix for both once the direction is clear. Measured on 2026-11-12 with adagents.json.

A missing stable version is served as another version's file. /schemas/3.3.0/, /schemas/3.4.0/, /schemas/3.9.9/ and /schemas/3.2.99/ all return 3.2.10's file, whose $id names 3.2.10; /schemas/3.1.99/ returns 3.1.33's. /compliance/3.3.0/ does the same, while /protocol/3.3.0.tgz is a 404. This is the docs-gap fallback from #5690 and #5691, which #7528 keeps for stable versions, and frozen doc links need it. But the only sign is Cache-Control: no-cache instead of immutable, the case #8347 called "worse than a 404". Could a resolved fallback redirect to the exact version, as a directory request already does, or carry a header naming the version served? And should 3.3, which has only betas, fall back to 3.2 at all?

The spellings don't overlap. Aliases need a leading v: /schemas/v3.2/ serves 3.2.10, /schemas/3.2/ is a 404 (ALIAS_PATH in server/src/schemas-middleware.ts and workers/artifact-cdn/src/index.js). Exact versions on the public site must not have one: the Worker answers /schemas/v3.2.7/ with a 404, while the Fly middleware accepts it because semver.valid drops the v. Accepting both spellings on both origins, and saying so on the schemas page, would remove the trap.

The change is ALIAS_PATH in both files and the Worker's SEMVER_PATH, with tests; it covers /compliance/ too and can stack on #7528.

Related: #7528, #8347, #5690, #5691, #2242, #8318.

Activity

  1. added this to the Evergreen milestone on Nov 13, 2026
  2. added
    bugSomething isn't working
    websiteAny issues related to the website
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    on Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingclaude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.websiteAny issues related to the website

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions