spdx
SPDX 2.3.0 schema conflicts with documentation for Annotations
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:
https://github.com/spdx/spdx-spec/blob/62f3e7cbd448a19f0099fdbd707d8b9b4fbddfdd/schemas/spdx-schema.json#L15-L42
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.
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:
https://github.com/spdx/spdx-spec/blob/62f3e7cbd448a19f0099fdbd707d8b9b4fbddfdd/schemas/spdx-schema.json#L234-L271
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.
@bact, is there any update? Do you plan to revisit this issue in the near future?
@slimreaper35 It would be great if you can put your use case here. What is fall short in the documentation or what do you think it should look like to accommodate your use case?
We also have a weekly meeting every Tuesdays at 12:00 US Eastern Time. Would be nice if you can join and explain further.
See meeting link here: https://github.com/spdx/meetings/?tab=readme-ov-file#tech-team Meeting agenda: https://docs.google.com/document/d/1NdHYU_VZtLacD4bEmf2GiUVRTbrcev1beaJpq8s8-pU/edit?tab=t.t8f4t082ttml
What is fall short in the documentation or what do you think it should look like to accommodate your use case?
Not documentation, but specifically this part mentioned in the issue description: It would be helpful to have SPDXREF or spdxElementId 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.
The use case is that we want to link components to the document annotations. The project I work on is used to enable hermetic builds for container images. We prefetch all the content that is supposed to be used in a build, and we record that in the SBOM (CycloneDX or SPDX).
To make the SBOM as accurate as possible, we have certain requirements that, however, can be bypassed with a CLI flag. As a result of that, the SBOM may not be accurate, as usual -> we want to record this information in the SBOM along with affected packages/components.
I think I now understand the issue.
The written spec is primarily targeted for the tag/value format with additional comments for RDF/XML. We use the JSON schema to document the JSON format.
In JSON, the annotations are treated as properties of the element. To translate to the tag/value style serializations you can capture the SPDX ID from the enclosing element (element being a Package, Snippet, or File). Let me know if this approach will work for you.
Updating the JSON schema to have Annotations outside the element would be a breaking change.
This has been addressed in SPDX 3.0 where Annotations are treated in a more consistent fashion.
Updating the JSON schema to have Annotations outside the element would be a breaking change. This has been addressed in SPDX 3.0 where Annotations are treated in a more consistent fashion.
I understand. I was confused because I saw the issue as part of the milestone for 2.3.1.
In JSON, the annotations are treated as properties of the element. To translate to the tag/value style serializations you can capture the SPDX ID from the enclosing element (element being a Package, Snippet, or File). Let me know if this approach will work for you.
Well, we could still use annotations directly inside packages.