Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

CLE endpoints: return ECMA-428 events verbatim, define the projection as a subset

Open
  • Is something wrong?
#322 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Domain
api

Research direction

Start by reading the CLE endpoint context in #213, the projection decision in #278, and the ECMA-428 event definitions referenced in the proposal. Done means the cle schema describes a subset of unchanged ECMA-428 events, removes the TEA-specific mappings, and preserves the stated withdrawal and support-definition rules.

Written by the indexing model from the issue text.

Description

TL;DR: we can reuse the ECMA-428 schema instead of redefining it.

The CLE endpoints from #213 are useful, and the "TEA projection" wording that closed #278 is honest about what they return. But the projection currently changes the event shape: versions[] accepts a TEA-only { version } form, identifiers use idType/idValue instead of CLE's type/value, and cle-event is one flat object with no per-type validation. A consumer that wants to feed the result to CLE tooling has to convert and re-validate it, and the schema itself says the endpoints "are not a substitute for that document".

A simpler definition fixes this without touching the endpoints.

Proposal

  1. Events are ECMA-428 events, unchanged. Each element of events is a CLE 1.0.0 event exactly as defined in ECMA-428, including its per-type required fields. definitions.support is the CLE definition. The TEA-specific { version } specifier and the idType/idValue identifier shape are dropped. The vers scheme a server needs is the PURL type of the component, which it already knows.

  2. The projection is a subset, nothing more. Proposed wording for the cle description:

    The events array contains a subset of the events of the CLE document(s) for the component or product, each event exactly as published there. Servers may omit events that do not apply to the requested object: on a release endpoint, events whose versions do not cover the release's version. Event id values are those of the source document and are not renumbered. A withdrawn event is included if and only if the event it withdraws is included. definitions.support contains at least the policies referenced by the included events.

  3. No further reduction. "Only the latest event per type" is left to the client. It is well-defined only on a single version, the client cannot tell whether the server applied it, and it is one line over a short array.

Effect

The cle schema description shrinks to the paragraph above, the two mapping bullets go away, and the schema can reference or copy the ECMA-428 event definitions. A consumer that needs a full CLE document wraps events and definitions from the component endpoint in the CLE envelope with the component's PURL as identifier, which is lossless once the events are verbatim.

References: #106 (original request), #213 (the endpoints), #278 (the projection decision).

Dominant language
Shell
Stars
116
Forks
23
Avg merge
2d 11h
Merged PRs (30d)
63

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from CycloneDX/transparency-exchange-api

All issues in CycloneDX/transparency-exchange-api

Similar issues

More Shell/Bash issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.