CycloneDX / CycloneDX/transparency-exchange-api

Align TEA API version grammar and /v{version} URL construction

Open
#280 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.