SPDX 2.3.0 schema conflicts with documentation for Annotations

[mmorin-netrise]

Clause 12 (Annotations) Section 4 of the SPDX documentation calls for an "SPDX identifier reference field".

However, the JSON schema does not specify this field. See the snippet below:

spdx-spec/schemas/spdx-schema.json

Lines 15 to 42 in 62f3e7c

	"annotations" : {
	"description" : "Provide additional information about an SpdxElement.",
	"type" : "array",
	"items" : {
	"type" : "object",
	"properties" : {
	"annotationDate" : {
	"description" : "Identify when the comment was made. This is to be specified according to the combined date and time in the UTC format, as specified in the ISO 8601 standard.",
	"type" : "string"
	},
	"annotationType" : {
	"description" : "Type of the annotation.",
	"type" : "string",
	"enum" : [ "OTHER", "REVIEW" ]
	},
	"annotator" : {
	"description" : "This field identifies the person, organization, or tool that has commented on a file, package, snippet, or the entire document.",
	"type" : "string"
	},
	"comment" : {
	"type" : "string"
	}
	},
	"required" : [ "annotationDate", "annotationType", "annotator", "comment" ],
	"additionalProperties" : false,
	"description" : "An Annotation is a comment on an SpdxItem by an agent."
	}
	},

It would be helpful to have SPDXREF (which is used in the SPDX Tag specification) or spdxElementId (which is used in Clause 11 (Relationships)) as a defined field in the JSON schema.

Without this field defined, it is not possible to link Annotations to an element in an SPDX 2.3.0 JSON BOM.

[mmorin-netrise]

I did just notice that the JSON schema does allow for annotations within different objects (e.g. files.annotations, packages.annotations). See the snippet below:

spdx-spec/schemas/spdx-schema.json

Lines 234 to 271 in 62f3e7c

	"packages" : {
	"description" : "Packages referenced in the SPDX document",
	"type" : "array",
	"items" : {
	"type" : "object",
	"properties" : {
	"SPDXID" : {
	"type" : "string",
	"description" : "Uniquely identify any element in an SPDX document which may be referenced by other elements."
	},
	"annotations" : {
	"description" : "Provide additional information about an SpdxElement.",
	"type" : "array",
	"items" : {
	"type" : "object",
	"properties" : {
	"annotationDate" : {
	"description" : "Identify when the comment was made. This is to be specified according to the combined date and time in the UTC format, as specified in the ISO 8601 standard.",
	"type" : "string"
	},
	"annotationType" : {
	"description" : "Type of the annotation.",
	"type" : "string",
	"enum" : [ "OTHER", "REVIEW" ]
	},
	"annotator" : {
	"description" : "This field identifies the person, organization, or tool that has commented on a file, package, snippet, or the entire document.",
	"type" : "string"
	},
	"comment" : {
	"type" : "string"
	}
	},
	"required" : [ "annotationDate", "annotationType", "annotator", "comment" ],
	"additionalProperties" : false,
	"description" : "An Annotation is a comment on an SpdxItem by an agent."
	}
	},

This style feels like the best (most natural?) way to use Annotations but unfortunately, it doesn't match up with any of the documentation. For example, there is no "annotation" subsection in Clause 4 (Packages).

It also feels less "SPDX"-y and more "CycloneDX"-y but that may not really matter.