1- # TEA release and collections
2-
3- ## The TEA release object (TRO)
4-
5- The TEA Component Release object corresponds to a specific variant
6- (version) of a component with a release identifier (string),
7- release timestamp and a lifecycle enumeration for the release.
8- The UUID of the TEA Component Release object matches the UUID of the associated TEA Collection objects (TCO).
9-
10- A TEA Component Release object has the following parts:
11-
12- - __ uuid__ : A unique identifier for the TEA Component Release
13- - __ version__ : Version number
14- - __ releaseDate__ : Timestamp of the release (for sorting purposes)
15- - __ preRelease__ : A flag indicating pre-release (or beta) status.
16- May be disabled after the creation of the release object, but can't be enabled after creation of an object.
17- - __ identifiers__ : List of identifiers for the component
18- - __ idType__ : Type of identifier, e.g. ` tei ` , ` purl ` , ` cpe `
19- - __ idValue__ : Identifier value
20- - __ formats__ : List of different formats of this component release
21- - __ id__ : A short name for this release format
22- - __ description__ : A free text describing the component variant
23- - __ identifiers__ : List identifiers for this release format
24- - __ idType__ : Type of identifier, e.g. ` tei ` , ` purl ` , ` cpe `
25- - __ idValue__ : Identifier value
26- - __ url__ : Direct download URL for the release format
27- - __ signatureUrl__ : Direct download URL for an external signature of the release format
28- - __ checksums__ : List of checksums for the release format
29- - __ algType__ : Checksum algorithm
30- - __ algValue__ : Checksum value
1+ # TEA Releases and Collections
2+
3+ ## The TEA Component Release object (TRO)
4+
5+ A TEA Component Release object represents a specific version of a component,
6+ identified by a unique release identifier and associated metadata.
7+ Each release may include multiple distributions,
8+ which capture variations such as architecture, packaging, or localization.
9+
10+ - For software components,
11+ each distribution typically corresponds to a different digital file delivered to users
12+ (e.g., by platform or packaging type).
13+ - For hardware components, distributions may reflect differences in packaging, language, or other physical attributes.
14+
15+ Each distribution is assigned a unique ` distributionType ` , defined by the producer,
16+ which is used to associate relevant TEA Artifacts with that distribution.
17+ Since TEA Artifacts can be associated with multiple release objects,
18+ the taxonomy for ` distributionType ` values should be defined on a TEA service level
19+ and consistently applied to all TEA Artifacts published by that producer.
20+ This ensures global uniqueness and reliable association across releases.
21+
22+ The ` uuid ` of the TEA Component Release object is identical to the ` uuid ` of its associated
23+ [ TEA Collection object (TCO)] ( #the-tea-collection-object-tco ) .
24+
25+ ### Structure
26+
27+ A TEA Component Release object contains the following fields:
28+
29+ - __ uuid__ : Unique identifier for the TEA Component Release.
30+ - __ version__ : Version number of the release.
31+ - __ createdDate__ : Timestamp when the release object was created.
32+ - __ releaseDate__ : Timestamp of the actual release.
33+ - __ preRelease__ : Boolean flag indicating if this is a pre-release (e.g., beta).
34+ This flag can be disabled after creation, but not enabled.
35+ - __ identifiers__ : List of identifiers for the component.
36+ - __ idType__ : Type of identifier (e.g., ` tei ` , ` purl ` , ` cpe ` ).
37+ - __ idValue__ : Value of the identifier.
38+ - __ distributions__ : List of release distributions, each with:
39+ - __ distributionType__ : Unique identifier for the distribution type.
40+ - __ description__ : Free-text description of the distribution.
41+ - __ identifiers__ : List of identifiers specific to this distribution.
42+ - __ idType__ : Type of identifier (e.g., ` tei ` , ` purl ` , ` cpe ` ).
43+ - __ idValue__ : Value of the identifier.
44+ - __ url__ : Direct download URL for the distribution.
45+ - __ signatureUrl__ : Direct download URL for the distribution's external signature.
46+ - __ checksums__ : List of checksums for the distribution.
47+ - __ algType__ : Checksum algorithm used.
48+ - __ algValue__ : Checksum value.
3149
3250### Examples
3351
@@ -129,32 +147,55 @@ The TEA Collection object has the following parts:
129147 - __ type__ : Type of update reason.
130148 See [ reasons for TEA Collection update] ( #the-reason-for-tco-update-enum ) below.
131149 - __ comment__ : Free text description.
132- - __ artifacts__ : List of TEA artifact objects.
133- See [ below] ( #artifact-object ) .
134-
135- ### Artifact object
136-
137- The TEA Artifact object has the following parts:
138-
139- - __ uuid__ : UUID of the TEA Artifact object.
140- - __ name__ : Artifact name.
141- - __ type__ : Type of artifact.
142- See [ TEA Artifact types] ( #tea-artifact-types ) for a list.
143- - __ componentFormats__ :
144- List of ` id ` s of component formats that this artifact applies to.
145- If absent, the artifact applies to all components.
146- - __ formats__ : List of objects with the same content, but in different formats.
147- The order of the list has no significance.
148- - __ mime_type__ : The MIME type of the document
149- - __ description__ : A free text describing the artifact
150- - __ url__ : Direct download URL for the artifact
151- - __ signature_url__ : Direct download URL for an external signature of the artifact
152- - __ checksums__ : List of checksums for the artifact
153- - __ algType__ : Checksum algorithm
154- See [ CycloneDX checksum algorithms] ( https://cyclonedx.org/docs/1.6/json/#components_items_hashes_items_alg ) for a list of supported values.
155- - __ algValue__ : Checksum value
156-
157- ### The reason for TCO update enum
150+ -
151+ - __ artifacts__ : List of TEA artifact objects.
152+ See [ below] ( #artifact-object ) .
153+
154+ ## The TEA Artifact object
155+
156+ A TEA Artifact object represents a security-related document or file linked to a component release,
157+ such as an SBOM, VEX, attestation, or license.
158+ Artifacts are strictly ** immutable** : if the underlying document changes, a new TEA Artifact object must be created.
159+ URLs referenced in this object must always resolve to the same resource to ensure that published checksums remain valid and verifiable.
160+
161+ TEA Artifacts can be reused across multiple TEA Collections,
162+ allowing the same document to be referenced by different component releases or even different components.
163+ This promotes consistency and reduces duplication.
164+
165+ Optionally, each artifact can specify the ` distributionType ` identifiers of the distributions it applies to.
166+ If this field is absent, the artifact is considered applicable to all distributions of the release.
167+
168+ ### Structure
169+
170+ A TEA Artifact object contains the following fields:
171+
172+ - __ uuid__ : The UUID of the TEA Artifact object. This uniquely identifies the artifact.
173+ - __ name__ : A human-readable name for the artifact.
174+ - __ type__ : The type of artifact. See [ TEA Artifact types] ( #tea-artifact-types ) for allowed values (e.g., ` BOM ` , ` VULNERABILITIES ` , ` LICENSE ` ).
175+ - __ componentDistributions__ (optional):
176+ An array of ` distributionType ` identifiers indicating which distributions this artifact applies to.
177+ If omitted, the artifact applies to all distributions.
178+ - __ formats__ :
179+ An array of objects, each representing the same artifact content in a different format.
180+ The order of the list is not significant.
181+ Each format object includes:
182+ - __ mime_type__ : The MIME type of the document (e.g., ` application/vnd.cyclonedx+xml ` ).
183+ - __ description__ : A free-text description of the artifact format.
184+ - __ url__ : A direct download URL for the artifact. This must point to an immutable resource.
185+ - __ signature_url__ (optional): A direct download URL for a detached digital signature of the artifact, if available.
186+ - __ checksums__ :
187+ An array of checksum objects for the artifact, each containing:
188+ - __ algType__ : The checksum algorithm used (e.g., ` SHA_256 ` , ` SHA3_512 ` ).
189+ - __ algValue__ : The checksum value as a string.
190+
191+ ### Notes
192+
193+ - The ` formats ` array allows the same artifact to be provided in multiple encodings or serializations (e.g., JSON, XML).
194+ - The ` checksums ` field provides integrity verification for each artifact format.
195+ - The ` signature_url ` enables consumers to verify the authenticity of the artifact using detached signatures.
196+ - Artifacts should be published to stable, versioned URLs to ensure immutability and traceability.
197+
198+ ## The reason for TCO update enum
158199
159200| ENUM | Description |
160201| ------------------| ----------------------------------------|
@@ -167,7 +208,7 @@ The TEA Artifact object has the following parts:
167208Updates of VEX (CSAF) files may be handled in a different way by a TEA client,
168209producing different alerts than other changes of a collection.
169210
170- ### TEA Artifact types
211+ ## TEA Artifact types
171212
172213| ENUM | Description |
173214| -----------------| -------------------------------------------------------------------------------------|
0 commit comments