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] <[email protected]> On Behalf Of Brandon Lum via lists.spdx.org Sent: Thursday, February 16, 2023 12:07 PM To: [email protected] Cc: Gary O'Neall <[email protected]>; SPDX Technical Mailing List <[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 (#4969): https://lists.spdx.org/g/Spdx-tech/message/4969 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]] -=-=-=-=-=-=-=-=-=-=-=-
