feat(api): define and signal malformed package versions in queries

Start with the query documentation and the package/version paths for /v1/query and /v1/querybatch; the issue does not name specific files or tests. Read the existing parser behavior and tests, including the npm and PyPI compatibility paths. Done means documenting and testing the chosen malformed-version signal for single and batch queries while preserving supported legacy formats and valid-version matching.

Summary

Please define the API behavior for malformed package versions and provide a machine-readable way to reject or flag them. Today, not-a-version produces ordinary advisory matches for npm lodash and PyPI requests, including through /v1/querybatch. This is a feature request: the query documentation does not promise rejection of malformed versions, and these observations do not demonstrate an existing API contract violation.

Problem to solve

A client that accidentally sends an unusable package version receives HTTP 200 and the same response shape as a normal version-specific query. It cannot tell from the response whether OSV interpreted a supported version or applied permissive parsing or legacy ordering. This can turn a caller's input mistake into apparently version-specific findings.

Small public queries against the deployed API on 2026-11-04 produced the following results. The source baseline inspected separately was master at b8ec03264f64e3db3a87f102380d6ff18f1d356e; this is not a claim about the deployed service's commit.

curl -sS -w '\nHTTP %{http_code}\n' https://api.osv.dev/v1/query \
  -H 'Content-Type: application/json' \
  -d '{"package":{"name":"lodash","ecosystem":"npm"},"version":"not-a-version"}'

The response is HTTP 200 and contains these four IDs:

GHSA-35jh-r3h4-6jhm
GHSA-4xc9-xhrj-v574
GHSA-fvqr-27wr-82fm
GHSA-jf85-cpcp-j695

For the lodash/npm affected entry in each returned record, the range is SEMVER, starts at introduced: 0, and ends at fixed: 4.17.21, 4.17.11, 4.17.5, or 4.17.12, respectively. Those entries have no explicit affected-version list. These are bounded ranges, unlike the unbounded malicious-package example discussed in the historical version-matching clarification.

Controls using the same package and endpoint all returned HTTP 200:

Version	Returned IDs
4.17.21	GHSA-r5fr-rjxr-66jc, GHSA-xxjr-mmjv-4gpg
4.17.21+build.123	The same two IDs as the preceding control
99.0.0	None ({})

The valid SemVer build-metadata control did not reveal a matching error. This request does not claim that a syntactically valid version must exist in the registry.

The same malformed string also produces HTTP 200 and 12 advisory IDs when querying {"package":{"name":"requests","ecosystem":"PyPI"},"version":"not-a-version"}. Sending both malformed cases in one batch returns HTTP 200, with the same per-package ID sets as the corresponding single queries and no invalid-version indication:

curl -sS -w '\nHTTP %{http_code}\n' https://api.osv.dev/v1/querybatch \
  -H 'Content-Type: application/json' \
  -d '{"queries":[{"package":{"name":"lodash","ecosystem":"npm"},"version":"not-a-version"},{"package":{"name":"requests","ecosystem":"PyPI"},"version":"not-a-version"}]}'

Proposed behavior

Define which version syntax and compatibility rules each supported ecosystem query accepts. When input falls outside that policy, provide an explicit invalid-version error or a machine-readable signal that it was not interpreted as a supported package version. Document the chosen behavior for both single and batch queries, including how a caller identifies an affected batch entry. Preserve documented fuzzy matching and any deliberately supported historical version formats.

Acceptance criteria

• The single and batch query documentation defines the handling of malformed versions, including the scope of any legacy or permissive matching.
• A client can distinguish the shown malformed npm input from an ordinary version match through a documented error or machine-readable response signal.
• PyPI handling explicitly accounts for historical version syntax rather than assuming that all strings outside modern syntax should be rejected.
• Valid version matching, including SemVer build metadata, continues to follow the relevant ecosystem ordering. No registry-existence check is required.

Affected area

The package/version paths of /v1/query and /v1/querybatch, their documentation, and their tests.

Non-goals

Checking whether every queried version exists in a registry, resolving Go pseudoversions to commits, changing advisory data, and changing the interpretation of supported valid versions are outside this request.

Alternatives considered

• Return an explicit invalid-version error where the ecosystem has a defined syntax, with documented batch behavior.
• Preserve permissive matching for compatibility while exposing a machine-readable indication that the input falls outside the accepted syntax.
• Keep the current response shape and document that callers must validate versions themselves. This clarifies the contract but leaves clients without server-side feedback when validation is missed.

Supporting context

The query documentation describes a string version and fuzzy matching. It documents HTTP 400 for conflicting version fields but does not define malformed-version handling. The OSV schema defines SemVer range ordering; its rules for advisory range endpoints do not themselves require an API error for an invalid query. The npm package version rules require versions parseable by node-semver. That establishes why this is not a normal npm version, rather than establishing an OSV API rejection contract.

The inspected source delegates npm parsing to a permissive semantic parser and retains a legacy-version path for PyPI. The inspected parser tests cover version comparison and invalid versions for several other ecosystems; they do not establish a public malformed-version rejection requirement for these queries. These are compatibility considerations, not a claim about the deployed implementation's exact revision or an instruction to replace a parser.

References

• #892: Better validation for API requests proposed ecosystem-specific version validation as well as registry-existence checks. Its closing discussion says it was automatically closed as stale; it does not record a fix or a maintainer rejection of syntax validation. This request supplies current single/batch evidence and excludes registry-existence validation.
• #4484: malformed Go PURL query includes a maintainer explanation that general version validity and pseudoversion resolution are not feasible. This request is narrower: define syntactic/compatibility behavior and expose a signal, without checking registry existence or resolving commits.
• #3787: version matching clarification explains unbounded malicious-record matching and accuracy for valid queried versions. The npm example here uses bounded fixed ranges and an invalid input, so that explanation does not define this case's intended API response.
• #5523: invalid/unknown ecosystem policy concerns ecosystem names, suffixes, and PURL types. This request concerns the version field for recognized ecosystems.

Triage assessment

• Impact level: not-applicable
• Assessment status: not-applicable
• Impact basis: This requests a defined validation and signaling capability; no existing public malformed-version rejection contract or valid-input matching failure was established.
• Workaround status: not-applicable
• Workaround basis: Defect impact is not assigned. Callers can apply their own ecosystem validation, but the request is for documented server behavior and feedback.