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*?). 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. Any thoughts about only supporting *reading* here? Thanks, -Keith On Tue, Feb 21, 2023 at 5:51 PM Adolfo <[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 <lumb= > [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]> >> 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] <[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 <lumb= >>> [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]> >>> 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] <[email protected]> *On Behalf >>> Of *Brandon Lum via lists.spdx.org >>> *Sent:* Wednesday, January 4, 2023 1:13 AM >>> *To:* SPDX Technical Mailing List <[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 (#4993): https://lists.spdx.org/g/Spdx-tech/message/4993 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]] -=-=-=-=-=-=-=-=-=-=-=-
