Mandatory DESCRIBES relationship

[armintaenzertng]

During handling of SPDXLite documents, @meretp encountered a problem that led me to reread the specification on the DESCRIBES relationship. The part I'm referring to is this (link):

[a DESCRIBES relationship] is mandatory if more than one package or set of files (not in a package) is present.

This raises several questions:

1. What is a "set of files"? How do I determine if there are "more than one set of files"?
2. The specification does not specify which item the mandatory DESCRIBES relationship should point to. I could have a DESCRIBES relationship to some random file within some package and adhere to the above requirement. Is that the intended behavior?
3. As SPDXLite does not support relationships, this means that an SPDXLite document can't have more than one package. Is that the intended behavior?
4. Is it implied that an SPDX document with only a single package automatically DESCRIBES this package?

[maxhbr]

Just went through git history, and that formulation was there in the initial conversation from 2.1 to markdown.

[goneall]

Although it has been a while, I do recall when we created the DESCRIBES requirement.

I think the description in the DESCRIBES is not very accurate based on my (perhaps faulty) recollection.

The relationship description is accurate for tag/value, but DESCRIBES relationship from the package to one or more "Elements" (where an element is a Package, File, or Snippet) is required for RDF to build a complete graph from the SPDX document.

For Tag/Value, we were trying to be compatible with the previous version and essentially create an implicit DESCRIBES relationship to the first package described in a Tag/Value file.

To be safe, I would suggest always creating a DESCRIBES relationship even if it isn't technically required.

I think we should change the description to something like:

An SPDX document `WildFly.spdx` describes package ‘WildFly’. 
Note this is a necessary logical relationship to help organize related items within an SPDX document.  In Tag/Value format an 
implicit DESCRIBES relationship is created to the package or set of files if only one package or set of files is present.

@kestewart - Am I way off on my recollection? It has been a while since this was discussed.

Note that the DESCRIBES relationship has been a source of other reported issues in the spec (e.g. where we tried to use a property rather than a relationships). This should all be cleaned up in 3.0.

[goneall]

I just re-read the issue.

Since this is tag/value, I would allow no DESCRIBES relationship if there is a single package. You would create an implicit DESCRIBES relationship when deserializing.

I really don't recall the "set of file" exception discussion. I don't implement that in the Java tools. I think you can safely ignore that part.

[Moullisha]

@goneall Is it possible to have more than one DESCRIBES relationships in an SPDX document?

[goneall]

Is it possible to have more than one DESCRIBES relationships in an SPDX document?

@Moullisha - Yes - the cardinality is one or more.

[Moullisha]

@goneall Can an SPDXRef-DOCUMENT describe multiple packages? For instance, considering the below relationship array, is it possible to have multiple DESCRIBES relationship with packages? "relationships": [ { "spdxElementId": "SPDXRef-Pkg-467877y78y8y1.1-3862772", "relationshipType": "CONTAINS", "relatedSpdxElement": "SPDXRef-File-46555494-s" }, { "spdxElementId": "SPDXRef-DOCUMENT", "relationshipType": "DESCRIBES", "relatedSpdxElement": "SPDXRef-Pkg-467877y78y8y1.1-3862772" }, { "spdxElementId": "SPDXRef-Pkg-673682989-1.6.7-3862764", "relationshipType": "CONTAINS", "relatedSpdxElement": "SPDXRef-File-46555494-s" }, { "spdxElementId": "SPDXRef-DOCUMENT", "relationshipType": "DESCRIBES", "relatedSpdxElement": "SPDXRef-Pkg-673682989-1.6.7-3862764" } ]

[goneall]

Can an SPDXRef-DOCUMENT describe multiple packages?

@Moullisha Yes - the above is syntactically valid.

The semantics of the above example is stating the the SPDX document is "about" or "describing" both SPDXRef-Pkg-467877y78y8y1.1-3862772 and SPDXRef-Pkg-673682989-1.6.7-3862764.

For a typical SBOM scenario, you would only describe the "top level" package and only have one reference. This would let the consumer know what the SPDX document is actually about. If you included references to the top level packages and all of the contained packages, the consumer wouldn't really know where to start.

There are practical situations where you may have more than one package being described. For example, you could have more than one SBOM contained in the same SPDX document. I'm not sure that would be a very good practice, but it is allowed.

[Moullisha]

@goneall Is it safe to say that there should be only one DESCRIBES relationship b/w SPDXRef-DOCUMENT and a top-level package, if the SPDX doc contains only packages/modules contained in a product ? But there can be multiple DESCRIBES relationships with files or SBOMs if present in the same SPDX document.

[goneall]

Is it safe to say that there should be only one DESCRIBES relationship b/w SPDXRef-DOCUMENT and a top-level package, if the SPDX doc contains only packages/modules contained in a product ?

Yes - that would be the preferred approach

But there can be multiple DESCRIBES relationships with files or SBOMs if present in the same SPDX document.

Yes - Most of the time the SPDX documents describe a single SBOM with one top level package, but there are use cases where you have multiple packages and/or files which are not part of a single SBOM described in a single SPDX document. For example, you may want to run a bunch of packages through a security vulnerability checker which takes SPDX documents as an input. Each of the top level packages would have a DESCRIBES relationship to the SPDX document.

[goneall]

I believe this is now resolved. If you disagree, feel free to reopen