Let’s add an agenda item for next Tuesday’s call to discuss how we want to document the JSON fields in general for the spec.
I added a couple of comments to Keith’s specific questions below. Gary From: [email protected] <[email protected]> On Behalf Of Keith Zantow via lists.spdx.org Sent: Thursday, February 23, 2023 2:09 PM To: SPDX Technical Mailing List <[email protected]> Subject: Re: [spdx-tech] clarification around "documentDescribes" field Hi All, Sorry I missed this discussion earlier, and apologies for bringing this back up, but just had a bit of a talk with Brandon and wanted to chime in on a couple thoughts here. As Gary noted, there are at least 2 "shortcut" fields (documentDescribes and hasFiles), which are completely equivalent to analogous relationships, as far as I can tell. In order to support these fields in the tools-golang project, does it make sense to only output relationships but support parsing these fields from existing SBOMs and translating them into relationships? Is there a reason to push the decision of how to construct the SPDX document from a common model to the user of the library? It seems like this is not something a library consumer should be concerned with (do I put this data here or here?). [G.O.] I think it’s important to support reading the shortcut for compatibility with libraries that use the shortcut, but I personally think it would be OK to always output relationships. It does make the output more verbose which really only impacts human readers of the JSON file. Also, these fields are not defined in the SPDX spec as far as I can tell (aside from RDF somehow, which I don't quite grok), and despite being defined in the JSON schema should probably be modeled as relationships when working with data models within tools, I think. [G.O.] True – also noted in the thread below. Any thoughts about only supporting reading here? Thanks, -Keith On Tue, Feb 21, 2023 at 5:51 PM Adolfo <[email protected] <mailto:[email protected]> > wrote: The second sounds good to me too, I think we also need to draft some guidance somewhere in the spec on how both are valid and are additive when the first level elements are defined in both via relationships and documentDescribes to define how consumption tools should behave when finding both. On Tue, Feb 21, 2023 at 4:13 PM Brandon Lum via lists.spdx.org <http://lists.spdx.org> <[email protected] <mailto:[email protected]> > wrote: Agreed with both options, either are good to me, probably favoring the later if it means a faster turn-around to standardization. On Thu, Feb 16, 2023 at 4:50 PM Gary O'Neall <[email protected] <mailto:[email protected]> > wrote: Hi Brandon and SPDX tech team, I just checked and it looks like “documentDescribed” is already optional in the JSON Schema, which should relieve some of the pressure on this issue. My interpretation of the “documentDescribes” is that it is really a “shortcut” for the DESCRIBES relationships on the SpdxDocument. In the Java tools, I treat it as 100% equivalent to a DESCRIBES relationship between the SpdxDocument and the SPDX element represented by the SPDX ID’s in the list of “documentDescribes”. I basically translate on deserialization to relationships and translate back on serialization. Note: this is very similar to the “hasFile” property on the SpdxPackage which is equivalent to the CONTAINS relationship from the package to the file. We may want to include the “hasFiles” in the same discussion and resolution since they are treated similarly. In terms of resolution for the spec, my first choice would be to document the JSON serialization to the same level we document the tag/value. Unfortunately, we were not able to get anyone to volunteer and/or follow-through on documenting JSON in the text. We have more volunteers for the 3.0 spec, so I’m hopeful we’ll have this resolved once 3.0 releases. My second choice would be to include the JSON schema in the spec itself. It would be good to have a semi-formal review of the schema since we’ve missed things in the past and some of the descriptions could be clearer. This would be feasible in the 2.X timeframe since we already have a Schema to start with. I would be nervous about removing the fields. It would simplify tooling, but it would create compatibility issues for anyone already using those fields. Thanks, Gary From: [email protected] <mailto:[email protected]> <[email protected] <mailto:[email protected]> > On Behalf Of Brandon Lum via lists.spdx.org <http://lists.spdx.org> Sent: Thursday, February 16, 2023 12:07 PM To: [email protected] <mailto:[email protected]> Cc: Gary O'Neall <[email protected] <mailto:[email protected]> >; SPDX Technical Mailing List <[email protected] <mailto:[email protected]> > Subject: Re: [spdx-tech] clarification around "documentDescribes" field Reviving this thread again since there is a little bit of ambiguity where these fields are part of the schema but their behavior is not technically described in the upstream specification. i.e. "documentDescribes" isn't in the ISO spec definition. Would the resolution be to push for the JSON schema to be incorporated into the spec via its serialization specification or to remove these fields or make them optional in the JSON schema? Please help correct my understanding if i've missed something! Thanks Brandon On Wed, Jan 4, 2023 at 11:16 PM Brandon Lum via lists.spdx.org <http://lists.spdx.org> <[email protected] <mailto:[email protected]> > wrote: Awesome! Thanks for the context and clarification Gary! On Thu, Jan 5, 2023 at 8:09 AM Gary O'Neall <[email protected] <mailto:[email protected]> > wrote: Hi Brandon, I believe it is safe to ignore the v2.2.0 JSON schema. The “describesPackages” was deprecated on release 2.0 of the spec and is only used for compatibility with pre 2.0 spec version using the RDF format. There is an open issue to remove this property <https://github.com/spdx/spdx-spec/issues/534> . It was probably in the 2.2.0 JSON schema due to it being generated from the RDF schema which still has the deprecated property. It looks like PR #528 <https://github.com/spdx/spdx-spec/pull/528/files> is where the property was replaced with the more appropriate “documentDescribes”. In the past, we’ve used the JSON examples as the primary documentation for the JSON format. With the fixes from PR 528, we should be able to use both the JSON Schema and the examples. The documentation for the JSON format should be dramatically improved in the 3.0 spec. Cheers, Gary From: [email protected] <mailto:[email protected]> <[email protected] <mailto:[email protected]> > On Behalf Of Brandon Lum via lists.spdx.org <http://lists.spdx.org> Sent: Wednesday, January 4, 2023 1:13 AM To: SPDX Technical Mailing List <[email protected] <mailto:[email protected]> > Subject: [spdx-tech] clarification around "documentDescribes" field Hi! An issue <https://github.com/spdx/tools-golang/issues/166> was opened in tools-golang around the missing "documentDescribes" field, which is part of the JSON schema. For v2.2.1 and above, the field is present, however, in v2.2.0 of the spec <https://github.com/spdx/spdx-spec/blob/v2.2/schemas/spdx-schema.json> , it looks like the field is called "describesPackages", however, in the same tag, the v2.2.0 example <https://github.com/spdx/spdx-spec/blob/v2.2/examples/SPDXJSONExample-v2.2.spdx.json#L58> uses "documentDescribes". Based on some of the wording from Gary's Java library around 2020, and looking through the v2.2.0 docs, i'm guessing that the JSON spec was still not fully approved then... So it should be safe to ignore the v2.2.0 JSON schema spec? Cheers Brandon -=-=-=-=-=-=-=-=-=-=-=- Links: You receive all messages sent to this group. View/Reply Online (#4994): https://lists.spdx.org/g/Spdx-tech/message/4994 Mute This Topic: https://lists.spdx.org/mt/96047024/21656 Group Owner: [email protected] Unsubscribe: https://lists.spdx.org/g/Spdx-tech/unsub [[email protected]] -=-=-=-=-=-=-=-=-=-=-=-
