Hello J

I am currently working on an issue in the Oss-Review-Toolkit  [1] to support referring to external SPDX files from a `project.spdx.yml` [2].

I am currently checking out the spdx-specs [3] and the spdx schema [4] to create a working example of an ´project.spdx.yml` which has a package referencing an external SPDX document for  its metadata.

In the example file provided in [5]  I could not find a reference of that sort.

I have tried using `externalRefs` parameter of a package in the spdx document, but didn’t achieve actually referencing an external spdx document.

In the last paragraph of the spdx/tools repository [6] I have found a mention of “ExternalSpdxElement” that is not in the 2.0 model anymore. Has this been replaced in some way?

I wondered if there was an actual example in one of the documentations or repositories that shows:

A project.spdx.yml listing a package

and in that package metadata refer to

additional metadata in the form of a package.spdx.yml (or something similar)

Here is a slightly changed project.spdx.yml (originally from [7]) that shows how I would imagine the mechanisms working:

SPDXID: "SPDXRef-DOCUMENT"

spdxVersion: "SPDX-2.2"

creationInfo:

  created: "2020-07-23T18:30:22Z"

  creators:

  - "Organization: Example Inc."

  - "Person: Thomas Steenbergen"

  licenseListVersion: "3.9"

name: "xyz-0.1.0"

dataLicense: "CC0-1.0"

documentNamespace: "http://spdx.org/spdxdocs/spdx-document-xyz"

documentDescribes:

- "SPDXRef-Package-xyz"

packages:

- SPDXID: "SPDXRef-Package-xyz"

  description: "Awesome product created by Example Inc."

  copyrightText: "Copyright (C) 2020 Example Inc."

  downloadLocation: "git+ssh://gitlab.example.com:3389/products/xyz.git@b2c358080011af6a366d2512a25a379fbe7b1f78"

  filesAnalyzed: false

  homepage: "https://example.com/products/xyz"

  licenseConcluded:  "NOASSERTION"

  licenseDeclared: "Apache-2.0 AND curl AND LicenseRef-Proprietary-ExampleInc"

  name: "xyz"

  versionInfo: "0.1.0"

- SPDXID: "SPDXRef-Package-curl"

  externalRefs:

    referenceCategory: "OTHER"

    referenceLocator: "curl:7.70.0" (or similar way of giving an identifier)

    referenceType: https://github.com/oss-review-toolkit/ort/blob/master/analyzer/src/funTest/assets/projects/synthetic/spdx/package/libs/curl/package.spdx.yml (alternatively a relative path to the same file locally could be given here)

OR:       - SPDXID: "SPDXRef-Package-curl"

  externalSpdxDocument:

    documentUri: https://github.com/oss-review-toolkit/ort/blob/master/analyzer/src/funTest/assets/projects/synthetic/spdx/package/libs/curl/package.spdx.yml (alternatively a relative path to the same file locally could be given here)

    id: SPDXDocumentRef-curl

relationships:

- spdxElementId: "SPDXRef-Package-xyz"

  relatedSpdxElement: "SPDXRef-Package-curl"

  relationshipType: "DEPENDS_ON"

[1] https://github.com/oss-review-toolkit/ort

[2] https://github.com/oss-review-toolkit/ort/issues/3402

[3] https://spdx.github.io/spdx-spec/3-package-information/#321-external-reference

[4] https://github.com/spdx/spdx-spec/blob/development/v2.2.1/schemas/spdx-schema.json

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

[6] https://github.com/spdx/tools#upgrading-to-spdx-20

[7] https://github.com/oss-review-toolkit/ort/blob/master/analyzer/src/funTest/assets/projects/synthetic/spdx/project/project.spdx.yml

Mit freundlichen Grüßen / Best regards

Stephanie Neubauer

Project Delivery Stuttgart (IOC/PDL4)
Robert Bosch GmbH | Postfach 11 27 | 71301 Waiblingen | GERMANY | www.bosch.com
Tel. +49 711 811-92528 | Mobil +49 172 3620267 | Telefax +49 711 811-58200 | Threema / Threema Work: PHCV2F36 | Stephanie.Neubauer@...

Sitz: Stuttgart, Registergericht: Amtsgericht Stuttgart, HRB 14000;
Aufsichtsratsvorsitzender: Franz Fehrenbach; Geschäftsführung: Dr. Volkmar Denner,
Prof. Dr. Stefan Asenkerschbaumer, Filiz Albrecht, Dr. Michael Bolle, Dr. Christian Fischer,
Dr. Stefan Hartung, Dr. Markus Heyn, Harald Kröger, Rolf Najork, Uwe Raschke
​

Moving this from spdx general list to spdx-tech list.

Greetings Stephanie,

If you are referring to an external SPDX document, you will want to use the ExternalSpdxDocument rather than ExternalRef.

The serialization format for the ExternalSpdxDocument varies quite a bit between the different file formats.

For YAML, the top level document will have a field externalDocumentRefs which lists all documents which are referenced.  For example:

…

externalDocumentRefs:

- externalDocumentId: "DocumentRef-spdx-tool-1.2"

  checksum:

    algorithm: "SHA1"

    checksumValue: "d6a770ba38583ed4bb4525bd96e50461655d2759"

  spdxDocument: "http://spdx.org/spdxdocs/spdx-tools-v1.2-3F2504E0-4F89-41D3-9A0C-0305E82C3301"

…

When there an element in the external document referenced, the syntax is externalDocumentId:SPDXRef-XXX where the SPDXRef-XXX is the SPDX reference in the external document.

For example:

…

relationships:

- spdxElementId: "SPDXRef-DOCUMENT"

  relatedSpdxElement: "DocumentRef-spdx-tool-1.2:SPDXRef-ToolsElement"

  relationshipType: "COPY_OF"

…

This is a similar approach to how the Tag/Value fields are parsed.

Note that this is an area of active discussion for the 3.0 Spec.  We all are finding the ExternalDocumentRef’s confusing and we will be renaming the fields at a minimum.  There is also some discussion on changing the model related to external document ref’s.  We will probably be discussing this on upcoming SPDX tech calls.  It has been proposed that we reintroduce the ExternalSpdxElement in the model for 3.0.

The SPDX YAML example includes an external document reference.

Best regards,
Gary