CycloneDX / CycloneDX/transparency-exchange-api
Align TEA API version grammar and /v{version} URL construction
- Dominant language
- Shell
- Stars
- 113
- Forks
- 22
- Avg merge
- 8d 12h
- Merged PRs (30d)
- 5
Description
## Summary
Advertised TEA API versions claim SemVer 2.0.0, but the `.well-known` schema pattern, examples, and OpenAPI `tea-server-info.versions` do not agree — so clients cannot implement “highest mutual version + `/v{version}`” consistently.
## Current gaps
- `discovery/tea-well-known.schema.json` accepts non-SemVer values such as `1.0`, `01.0.0`, and invalid prereleases, and rejects valid SemVer build metadata.
- The schema example includes `"1.0"` while describing SemVer 2.0.
- OpenAPI `tea-server-info.versions` items are unconstrained strings.
- The OpenAPI `servers` example uses `/v1`, which does not match discovery’s “append `/v` + exact advertised version” rule (`/v1.0.0`, `/v0.2.0-beta.2`, …).
## Proposed direction
- Use one SemVer 2.0.0 grammar in the well-known schema and OpenAPI: `MAJOR.MINOR.PATCH` with optional prerelease.
- Do not advertise build metadata (`+…`) in API path versions (awkward in URL paths).
- Fix examples to full versions (e.g. `1.0.0`).
- State clearly: select the highest mutually supported version; append `/v` followed by that exact advertised string.
- Align the local OpenAPI server example with `info.version` (e.g. `/v0.5.0`).
Does this direction look right before a PR ?
Contributor guide
Assessment
This issue has not been assessed yet.