Why don't Vision plugin API version numbers match documentation?

You're not missing anything - there does appear to be a discrepancy between what you see in the Vision plugin's API version dropdown and the comprehensive list of API versions in the API Versioning documentation.

Here's what I can confirm from the documentation:

About Sanity's API versioning: According to the API Versioning docs, Sanity uses a date-based versioning system where "you don't have to use specific dates, any past or present date is valid, and today's date will always give you the latest version." The documentation lists several important milestone versions like v2021-03-25, v2021-10-21, and v2025-02-19, each introducing significant changes to GROQ behavior or API functionality.

About the Vision plugin: The Vision plugin documentation confirms that Vision "allows you to query against different datasets within your project and select different API versions," but it doesn't specifically document which versions appear in the dropdown or why.

What's likely happening: The Vision plugin dropdown probably shows a curated subset of the most significant API versions rather than all possible date-based versions. However, I couldn't find official documentation confirming this is intentional behavior versus potentially outdated plugin versions.

What you can do: Even if a newer API version like v2025-02-19 doesn't appear in Vision's dropdown, you can still use it by:

1. Configuring it in your Vision plugin settings:

visionTool({
  defaultApiVersion: '2025-02-19'
})

2. Setting it in your Sanity client configuration for your actual application queries

If you're seeing significantly outdated versions in the dropdown, it might be worth updating your @sanity/vision package to the latest version with npm install @sanity/vision@latest.

If the mismatch is causing confusion or you need specific newer API versions available in the dropdown, I'd recommend reaching out to Sanity support or posting in the Sanity community to confirm whether this is expected behavior or if there's a configuration option to show more versions.