CycloneDX / CycloneDX/transparency-exchange-api

CLE in OpenAPI vs ECMA-428 CLE 1.0.0 — align or name a TEA projection?

Open
#278 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

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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.