CycloneDX / CycloneDX/transparency-exchange-api

Clarify discovery cardinality, response array, and direct PURL lookup

Open
#279 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
113
Forks
22
Avg merge
8d 12h
Merged PRs (30d)
5

Description

## Summary

Discovery prose and OpenAPI disagree on how many product releases a TEI can resolve to. The discovery document also does not describe the actual success response shape, and it never documented the direct-PURL workflow that #265 added to OpenAPI (“spec only; documentation unchanged”).

## Current gaps

- `discovery/readme.md` says a TEI belongs to a single product release, then later allows the same identifier (e.g. EAN) to span multiple releases.
- Successful `/discovery` is not described as the OpenAPI array of `discovery-info` objects (`productReleaseUuid` + `servers[]`).
- OpenAPI allows `200` with an empty array; a no-match should be `404`.
- Direct `purl=` lookup (already-known API base; exactly one of `tei`/`purl`) is in OpenAPI but missing from the discovery narrative.
- `.well-known` endpoint list vs `servers[].rootUrl` should be explicitly related.

## Proposed direction

- A TEI MAY resolve to multiple product releases; vendors SHOULD prefer one.
- Successful lookup MUST return a non-empty array of `discovery-info`; no match MUST return `404` (not `200` + `[]`).
- Add `minItems: 1` on the discovery response array; document `productReleaseUuid` + `servers[]`.
- Document direct PURL discovery as requiring an already-known API endpoint.

This is consistent with the direction discussed in #274: on a conforming `/discovery` handler, 404 means the identifier is unknown (not “empty success”). #274 can stay focused on overloaded 404 / failover wording; this issue is about cardinality, response shape, and the #265 docs gap.

## My Question

Does this direction look right for a follow-up PR I'd put together?

Contributor guide

Open the contributing guide

Research direction

Start with discovery/readme.md and the existing OpenAPI discovery definitions, comparing their cardinality, response shape, status codes, direct-purl workflow, and endpoint relationships. Update the documentation and schema so the narrative matches the proposed behavior, including a non-empty discovery-info array and 404 for no match; done means the stated gaps are consistent across both sources.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
75/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.