Add documentation for `documentDescribes`

[tsteenbe]

In SPDX 2.2. we introduced documentDescribes but apart form the examples [1] this field is not documented anywhere. Should be something like documentDescribes contains the SPDX IDs for the "root" package/file that the SPDX document describes.

[1] https://github.com/spdx/spdx-spec/blob/development/v2.2.1/examples/SPDXYAMLExample-2.2.spdx.yaml#L144

[swinslow]

one reference point might be the RDF terms, I think this may also be present in some form in RDF documents (including pre-2.2) -- see https://spdx.org/rdf/terms/#d4e232. But I'll defer to @goneall since I know very little about RDF specifics :)

[goneall]

In the tag/value and RDF, the documentDescribes is a relationship and not called out as a separate field. I'm wondering if we should make these consistent and change the JSON and YAML to use the relationship instead of introducing a new term.

In 2.2 - was there an issue or discussion that led to the introduction of this field or did I just introduce that in the examples? If the latter, I would suggest removing it and call it a bug.

[tsteenbe]

I remember that documentDescribes came from NTIA discussion - maybe @kestewart clarify? One of my devs found this any I struggle to find the discussions related to this field - it useful relation to have to indicate the "root" package or file within the SpdxDocument.

[tardyp]

FWIW, I came today into looking how I should use this documentDescribes field.
This issue helps, but I encourage documenting an official position in 2.2.2.

ORT documents it should reference all ids found in packages and files, I am not sure it is really the purpose.

[goneall]

My interpretation of the documentDescribes property is that it is a short-cut way of providing a DESCRIBES relationship between the SPDX Document and the elements.

Here's a cut/paste from the spec for the DESCRIBES relationship:

Relationship	Description	Example
DESCRIBES	Is to be used when SPDXRef-DOCUMENT describes SPDXRef-A.	An SPDX document WildFly.spdx describes package ‘WildFly’. Note this is a

@tsteenbe @kestewart - does this match you understanding?

[kestewart]

@goneall - yes, this matches my understanding that it's a shortcut for the relationship that was introduced in some of the serializations.

If we're going to add a new field, it probably should go in 2.3 at this point.