12 Annotations information section
12.1 Annotator field
12.1.1 Description
This field identifies the person, organization or tool that has commented on a snippet, file, package, or the entire document. The metadata for the annotator field is shown in Table 71.
Table 71 — Metadata for the annotator field
Attribute | Value |
---|---|
Required | Conditional |
Cardinality | 0..1 conditional (Mandatory, one), if there is an Annotation. |
Format | Single line of text with the following keywords."Person: person name" and optional "(email)" |
12.1.2 Intent
It may also be important for participants in the software supply chain to validate and add information on ambiguous snippets, files and packages.
12.1.3 Examples
EXAMPLE 1 Tag: Annotator:
Annotator: Person: Jane Doe ()
EXAMPLE 2 RDF: Property spdx:annotator
in class spdx:Annotation
<Annotation>
<annotator> Person: Jane Doe () </annotator>
</Annotation>
12.2 Annotation date field
12.2.1 Description
Identify when the comment was made. This shall be specified according to the combined date and time in the UTC format, as specified in the ISO 8601 standard. The metadata for the annotation date field is shown in Table 72.
Table 72 — Metadata for the annotation date field
Attribute | Value |
---|---|
Required | Conditional |
Cardinality | 0..1 conditional (Mandatory, one), if there is an Annotation. |
Format | YYYY-MM-DDThh:mm:ssZ where:
|
12.2.2 Intent
Here, the Annotation Date can serve as a verification as to when the actual review was done.
12.2.3 Examples
EXAMPLE 1 Tag: AnnotationDate:
AnnotationDate: 2010-01-29T18:30:22Z
EXAMPLE 2 RDF: Property spdx:annotationDate
in class spdx:Annotation
</Annotation>
<annotationDate> 2010-01-29T18:30:22Z </annotation Date>
</Annotation>
12.3 Annotation type field
12.3.1 Description
This field describes the type of annotation. Annotations are usually created when someone reviews the SPDX document, and if this is the case the annotation type should be REVIEW
. If the author wants to store extra information about one of the elements during creation, it is recommended to use the type of OTHER
. The metadata for the annotation type field is shown in Table 73.
Table 73 — Metadata for the annotation type field
Attribute | Value |
---|---|
Required | Conditional |
Cardinality | 0..1 conditional (Mandatory, one), if there is an Annotation. |
Format | REVIEW | OTHER |
12.3.2 Intent
This allows the type of annotation to be recorded.
12.3.3 Examples
EXAMPLE 1 Tag: AnnotationType:
AnnotationType: REVIEW
EXAMPLE 2 RDF: Property spdx:annotationType
in class spdx:Annotation
<Annotation>
<annotationType rdf:resource
="http://spdx.org/rdf/terms#annotationType_other"/>
</Annotation>
12.4 SPDX identifier reference field
12.4.1 Description
Uniquely identify the element in an SPDX document which is being referenced. These may be referenced internally and externally with the addition of the SPDX document identifier. The metadata for the SPDX identifier reference field is shown in Table 74.
Table 74 — Metadata for the SPDX identifier reference field
Attribute | Value |
---|---|
Required | Conditional |
Cardinality | 0..1 conditional (Mandatory, one), if there is an Annotation. |
Format | [DocumentRef-[idstring]:]SPDXID where: ["DocumentRef-"[idstring]":"] is an optional reference to an external SPDX document as described in 6.6SPDXID is a unique string containing letters, numbers, . and/or - as described in 6.3, 7.2 and 8.2. |
12.4.2 Intent
There may be several versions of the same snippet, package or file within an SPDX document. Each element needs to be able to be referred to uniquely so that relationships between elements can be clearly articulated.
12.4.3 Examples
EXAMPLE 1 Tag: SPDXREF:
SPDXREF: SPDXRef-45
SPDXREF: DocumentRef-spdx-tool-1.2:SPDXRef-5
EXAMPLE 2 RDF:
For RDF, the annotations are a property of the SPDX document, package, file, or snippet they are annotating.
<File rdf:about="#SPDXRef-45">
<annotation>
<Annotation>
...
</Annotation>
</annotation>
</File>
12.5 Annotation comment field
12.5.1 Description
This required free form text field permits the annotator to provide commentary on the analysis. The metadata for the annotation comment field is shown in Table 75.
Table 75 — Metadata for the annotation comment field
Attribute | Value |
---|---|
Required | Conditional |
Cardinality | 0..1 conditional (Mandatory, one), if there is an Annotation. |
Format | Free form text that may span multiple lines. |
12.5.2 Intent
This allows the annotator to provide independent assessment and note any points where there is disagreement with the analysis.
12.5.3 Examples
EXAMPLE 1 Tag: AnnotationComment:
In tag:value
format multiple lines are delimited by <text> .. </text>
.
AnnotationComment: <text>All of the licenses seen in the file, are
matching what was seen during manual inspection. There are some
terms that can influence the concluded license, and some
alternatives may be possible, but the concluded license is one of
the options.</text>
EXAMPLE 2 RDF: Property rdfs:comment
in class spdx:Annotation
<Annotation>
<rdfs:comment>All of the licenses seen in the file, are
matching what was seen during manual inspection. There
are some terms that can influence the concluded license,
and some alternatives may be possible, but the concluded
license is one of the options.
</rdfs:comment>
</Annotation>