CycloneDX / CycloneDX/transparency-exchange-api
CLE in OpenAPI vs ECMA-428 CLE 1.0.0 — align or name a TEA projection?
- Dominant language
- Shell
- Stars
- 113
- Forks
- 22
- Avg merge
- 8d 12h
- Merged PRs (30d)
- 5
Description
## Summary
TEA’s OpenAPI CLE schemas are described as based on ECMA-428 TC54 TG3 CLE Specification v1.0.0, but the model does not match the pinned CLE 1.0.0 schema ([cle-1.0.0.schema.json](https://tc54.org/schemas/cle/cle-1.0.0.schema.json)). As written, a payload that validates against TEA OpenAPI is not necessarily a valid CLE 1.0.0 document, and vice versa.
Before patching individual fields, it would help to decide whether TEA 1.0 intends CLE responses to be CLE documents, or a TEA-specific projection with explicit conversion rules.
Relevant schemas: `cle-event-type`, `cle-version-specifier`, `cle-event`, `cle-definitions`, and `cle`.
## Current gaps:
Compared with CLE 1.0.0:
- Incomplete envelope: CLE requires top-level `$schema`, `identifier`, and `updatedAt` (plus `events`). TEA’s `cle` schema only requires `events`.
- Identifier shape: CLE `componentRenamed` identifiers use `type` / `value`. TEA reuses its own `identifier` shape (`idType` / `idValue`).
- Version selectors: CLE version entries require `range`. TEA’s `cle-version-specifier` also allows `{version: ...}`, and examples use both forms.
- Event-specific requirements: CLE makes fields required by event type (e.g. `released` → `version`, `withdrawn` → `eventId`, end-of-* → `versions`, etc.). TEA lists those fields as optional on a single flat `cle-event`, so incomplete events can still validate.
- Unavailable CLE: README says CLE inclusion is optional, but the response contract when CLE is not available for a product/component/release is not clearly defined in OpenAPI.
Adding one missing field (for example only `updatedAt`) would patch a symptom and still leave a half-specified "CLE" surface?
## Decision:
A — Align with CLE 1.0.0: Treat TEA CLE endpoints as returning CLE documents. Reference or otherwise conform to the pinned CLE 1.0.0 schema, update TEA examples accordingly, and define behavior when CLE is unavailable.
B — Name a TEA-specific projection: Keep a TEA CLE-derived model in OpenAPI, but stop implying bit-identical CLE 1.0.0 documents. Explicitly name the projection and document conversion rules to/from CLE 1.0.0 (identifiers, version selectors, envelope fields, event-specific requirements).
## My question
For TEA 1.0, should CLE responses be CLE 1.0.0 documents (A), or an explicitly named TEA projection with conversion rules (B)?
I notice I keep framing these as binary choices — brains apparently love an A/B. If there's an option C hiding in here, I'd love to hear it too.
Contributor guide
Research direction
Start with the pinned ECMA-428 CLE 1.0.0 schema and compare it with the relevant OpenAPI schemas: cle-event-type, cle-version-specifier, cle-event, cle-definitions, and cle. Read the README section on optional CLE inclusion. Done means the project chooses and documents A, B, or another option, including the resulting schema, examples, conversion rules, and unavailable-CLE behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100