11 Relationships between SPDX elements information section

11.1 Relationship field

11.1.1 Description

This field provides information about the relationship between two SPDX elements. For example, you can represent a relationship between two different Files, between a Package and a File, between two Packages, or between one SPDXDocument and another SPDXDocument.

In cases where there are "known unknowns", the use of the keyword NOASSERTION can be used on the right hand side of a relationship to indicate that the author is not asserting whether there are other SPDX elements (package/file/snippet) that are connected by relationships or not. That is, there could be some, but the author is not asserting one way or another.

Similarly, the use of the keyword NONE can be used to indicate that an SPDX element (package/file/snippet) has no other elements connected by some relationship to it.

The use of NOASSERTIONor NONE is not mandatory for any relationship. If no relationship of a particular type is specified, then the document author is not presumed to be asserting whether or not there are relationships of that type. If some relationships of a particular type are specified, then the document author is not presumed to be asserting whether there are more possible relationships of that type.

The relationships between two SPDX elements that are supported are shown in Table 68.

Table 68 — Relationships between two SPDX elements that are supported

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 logical relationship to help organize related items within an SPDX document that is mandatory if more than one package or set of files (not in a package) is present.
DESCRIBED_BY Is to be used when SPDXRef-A is described by SPDXREF-Document. The package ‘WildFly’ is described by SPDX document WildFly.spdx.
CONTAINS Is to be used when SPDXRef-A contains SPDXRef-B. An ARCHIVE file bar.tgz contains a SOURCE file foo.c.
CONTAINED_BY Is to be used when SPDXRef-A is contained by SPDXRef-B. A SOURCE file foo.c is contained by ARCHIVE file bar.tgz
DEPENDS_ON Is to be used when SPDXRef-A depends on SPDXRef-B. Package A depends on the presence of package B in order to build and run
DEPENDENCY_OF Is to be used when SPDXRef-A is dependency of SPDXRef-B. A is explicitly stated as a dependency of B in a machine-readable file. Use when a package manager does not define scopes.
DEPENDENCY_MANIFEST_OF Is to be used when SPDXRef-A is a manifest file that lists a set of dependencies for SPDXRef-B. A file package.json is the dependency manifest of a package foo. Note that only one manifest should be used to define the same dependency graph.
BUILD_DEPENDENCY_OF Is to be used when SPDXRef-A is a build dependency of SPDXRef-B. A is in the compile scope of B in a Maven project.
DEV_DEPENDENCY_OF Is to be used when SPDXRef-A is a development dependency of SPDXRef-B. A is in the devDependencies scope of B in a Maven project.
OPTIONAL_DEPENDENCY_OF Is to be used when SPDXRef-A is an optional dependency of SPDXRef-B. Use when building the code will proceed even if a dependency cannot be found, fails to install, or is only installed on a specific platform. For example, A is in the optionalDependencies scope of npm project B.
PROVIDED_DEPENDENCY_OF Is to be used when SPDXRef-A is a to be provided dependency of SPDXRef-B. A is in the provided scope of B in a Maven project, indicating that the project expects it to be provided, for instance, by the container or JDK.
TEST_DEPENDENCY_OF Is to be used when SPDXRef-A is a test dependency of SPDXRef-B. A is in the test scope of B in a Maven project.
RUNTIME_DEPENDENCY_OF Is to be used when SPDXRef-A is a dependency required for the execution of SPDXRef-B. A is in the runtime scope of B in a Maven project.
EXAMPLE_OF Is to be used when SPDXRef-A is an example of SPDXRef-B. The file or snippet that illustrates how to use an application or library.
GENERATES Is to be used when SPDXRef-A generates SPDXRef-B. A SOURCE file makefile.mk generates a BINARY file a.out
GENERATED_FROM Is to be used when SPDXRef-A was generated from SPDXRef-B. A BINARY file a.out has been generated from a SOURCE file makefile.mk. A BINARY file foolib.a is generated from a SOURCE file bar.c.
ANCESTOR_OF Is to be used when SPDXRef-A is an ancestor (same lineage but pre-dates) SPDXRef-B. A SOURCE file makefile.mk is a version of the original ancestor SOURCE file ‘makefile2.mk’
DESCENDANT_OF Is to be used when SPDXRef-A is a descendant of (same lineage but postdates) SPDXRef-B. A SOURCE file makefile2.mk is a descendant of the original SOURCE file ‘makefile.mk’
VARIANT_OF Is to be used when SPDXRef-A is a variant of (same lineage but not clear which came first) SPDXRef-B. A SOURCE file makefile2.mk is a variant of SOURCE file makefile.mk if they differ by some edit, but there is no way to tell which came first (no reliable date information).
DISTRIBUTION_ARTIFACT Is to be used when distributing SPDXRef-A requires that SPDXRef-B also be distributed. A BINARY file foo.o requires that the ARCHIVE file bar-sources.tgz be made available on distribution.
PATCH_FOR Is to be used when SPDXRef-A is a patch file for (to be applied to) SPDXRef-B. A SOURCE file foo.diff is a patch file for SOURCE file foo.c.
PATCH_APPLIED Is to be used when SPDXRef-A is a patch file that has been applied to SPDXRef-B. A SOURCE file foo.diff is a patch file that has been applied to SOURCE file ‘foo-patched.c’.
COPY_OF Is to be used when SPDXRef-A is an exact copy of SPDXRef-B. A BINARY file alib.a is an exact copy of BINARY file a2lib.a.
FILE_ADDED Is to be used when SPDXRef-A is a file that was added to SPDXRef-B. A SOURCE file foo.c has been added to package ARCHIVE bar.tgz.
FILE_DELETED Is to be used when SPDXRef-A is a file that was deleted from SPDXRef-B. A SOURCE file foo.diff has been deleted from package ARCHIVE bar.tgz.
FILE_MODIFIED Is to be used when SPDXRef-A is a file that was modified from SPDXRef-B. A SOURCE file foo.c has been modified from SOURCE file foo.orig.c.
EXPANDED_FROM_ARCHIVE Is to be used when SPDXRef-A is expanded from the archive SPDXRef-B. A SOURCE file foo.c, has been expanded from the archive ARCHIVE file xyz.tgz.
DYNAMIC_LINK Is to be used when SPDXRef-A dynamically links to SPDXRef-B. An APPLICATION file ‘myapp’ dynamically links to BINARY file zlib.so.
STATIC_LINK Is to be used when SPDXRef-A statically links to SPDXRef-B. An APPLICATION file ‘myapp’ statically links to BINARY zlib.a.
DATA_FILE_OF Is to be used when SPDXRef-A is a data file used in SPDXRef-B. An IMAGE file ‘kitty.jpg’ is a data file of an APPLICATION ‘hellokitty’.
TEST_CASE_OF Is to be used when SPDXRef-A is a test case used in testing SPDXRef-B. A SOURCE file testMyCode.java is a unit test file used to test an APPLICATION MyPackage.
BUILD_TOOL_OF Is to be used when SPDXRef-A is used to build SPDXRef-B. A SOURCE file makefile.mk is used to build an APPLICATION ‘zlib’.
DEV_TOOL_OF Is to be used when SPDXRef-A is used as a development tool for SPDXRef-B. Any tool used for development such as a code debugger.
TEST_OF Is to be used when SPDXRef-A is used for testing SPDXRef-B. Generic relationship for cases where it's clear that something is used for testing but unclear whether it's TEST_CASE_OF or TEST_TOOL_OF.
TEST_TOOL_OF Is to be used when SPDXRef-A is used as a test tool for SPDXRef-B. Any tool used to test the code such as ESlint.
DOCUMENTATION_OF Is to be used when SPDXRef-A provides documentation of SPDXRef-B. A DOCUMENTATION file readme.txt documents the APPLICATION ‘zlib’.
OPTIONAL_COMPONENT_OF Is to be used when SPDXRef-A is an optional component of SPDXRef-B. A SOURCE file fool.c (which is in the contributors directory) may or may not be included in the build of APPLICATION ‘atthebar’.
METAFILE_OF Is to be used when SPDXRef-A is a metafile of SPDXRef-B. A SOURCE file pom.xml is a metafile of the APPLICATION ‘Apache Xerces’.
PACKAGE_OF Is to be used when SPDXRef-A is used as a package as part of SPDXRef-B. A Linux distribution contains an APPLICATION package gawk as part of the distribution MyLinuxDistro.
AMENDS Is to be used when (current) SPDXRef-DOCUMENT amends the SPDX information in SPDXRef-B. (Current) SPDX document A version 2 contains a correction to a previous version of the SPDX document A version 1. Note the reserved identifier SPDXRef-DOCUMENT for the current document is required.
PREREQUISITE_FOR Is to be used when SPDXRef-A is a prerequisite for SPDXRef-B. A library bar.dll is a prerequisite or dependency for APPLICATION foo.exe
HAS_PREREQUISITE Is to be used when SPDXRef-A has as a prerequisite SPDXRef-B. An APPLICATION foo.exe has prerequisite or dependency on bar.dll
REQUIREMENT_DESCRIPTION_FOR Is to be used when SPDXRef-A describes, illustrates, or specifies a requirement statement for SPDXRef-B. A PDF document that describes a list of disallowed licences to inherit in certain build-subtrees.
SPECIFICATION_FOR Is to be used when SPDXRef-A describes, illustrates, or defines a design specification for SPDXRef-B. A UML diagram illustrating a directed requirement graph for a discernible set of software components in a software package.
OTHER Is to be used for a relationship which has not been defined in the formal SPDX specification. A description of the relationship should be included in the Relationship comments field.

The metadata for the relationship field is shown in Table 69.

Table 69 — Metadata for the relationship field

Attribute Value
Required No
Cardinality 0..* see DESCRIBES relationship for one mandatory case.
Format ["DocumentRef-"[idstring]":"]SPDXID \<relationship> ["DocumentRef-"[idstring]":"]SPDXID | NONE | NOASSERTION
where "DocumentRef-"[idstring]":" is an optional reference to an external SPDX document as described in 6.6
where SPDXID is a string containing letters, numbers, . and/or -. as described in 6.3, 7.2, 8.2.
where <relationship> is one of the documented relationship types in Table 68.
where NONE can be used to explicitly indicate there are NO other relationships.
where NOASSERTION can be used to explicitly indicate it is not clear if there are relationships that may apply or not.

11.1.2 Intent

Here, this field is a reasonable estimation of the relation between two identified elements (i.e. files or packages, or documents), from a developer perspective.

11.1.3 Examples

EXAMPLE 1 Tag: Relationship:

Relationship: SPDXRef-grep CONTAINS SPDXRef-make
RelationshipComment: Package grep contains file make
Relationship: SPDXRef-DOCUMENT AMENDS DocumentRef-SPDXA:SPDXRef-DOCUMENT
RelationshipComment: This current document is an amendment of the SPDXA document.
Relationship: SPDXRef-CarolCompression DEPENDS_ON NONE
RelationshipComment: The package CarolCompression can be considered as a root with no dependencies.
Relationship: SPDXRef-BobBrowser CONTAINS NOASSERTION
RelationshipComment: The package BobBrowser may have other packages embedded in it, but the author has insufficient information to treat this as other than unknown at this point in time.

EXAMPLE 2 RDF: Property spdx:relationship in any spdx:SpdxDocument, spdx:Package, spdx:File or spdx:Snippet

<File rdf:about="#SPDXRef-45">
  <relationship>
    <Relationship>
      <relatedSpdxElement>
        <File rdf:about="http://spdx.org/spdxdocs/spdx-tools-v1.2-3F2504E0-4F89-41D3-9A0C-0305E82..."/>
      </relatedSpdxElement>
      <relationshipType>http://spdx.org/rdf/terms#relationshipType_contains
      </relationshipType>
    </Relationship>
  </relationship>
  ...
</File>

11.2 Relationship comment field

11.2.1 Description

This field provides a place for the SPDX document creator to record any general comments about the relationship. The metadata for the relationship comment field is shown in Table 70.

Table 70 — Metadata for the relationship comment field

Attribute Value
Required No
Cardinality 0..1
Format Free form text that may span multiple lines, refers only to the immediately preceding relationship.

11.2.2 Intent

Here, the intent is to provide the recipient of the SPDX document with more information determined after careful analysis of the relationship between two elements in an SPDX document.

11.2.3 Examples

EXAMPLE 1 Tag: RelationshipComment:

In tag:value format multiple lines are delimited by <text> .. </text>.

A RelationshipComment: shall be the line immediately after a “Relationship:”

RelationshipComment: <text>The package foo.tgz is a pre-requisite for building executable bar.</text>

EXAMPLE 2 RDF: Property rdfs:comment in class spdx:Relationship

<Relationship rdf:about="...">
  <rdfs:comment>
    The package foo.tgz is a pre-requisite for building executable bar.
  </rdfs:comment>

  ...

</Relationship>