Clarification on FileName Field in SPDX 2.3

[nishanthsankaran]

I need some clarification on how to correctly mention the file name in the SPDX 2.3 document. Specifically, I want to understand how to represent the file path within the codebase and the file's location inside the package.

Details

I have a file test.java located in ./local/src/test/test.java. This file has been taken from a third-party package "dummy" where the original filename is abc.java present in the path ./src/abc.java within the package. I want to ensure that I am correctly representing all these file path details in the SPDX document.

Example

Here is how I currently understand it:

• Local file which I scanned: ./local/src/test/test.java
• Where the code was taken from third-party package information:
  • Package: dummy
  • File path from package: ./src/abc.java

Question

I have represented both files under the package section and in the relationships section as follows:

{
  "spdxElementId": "SPDXRef-File-test.java",
  "relationshipType": "DESCENDANT_OF",
  "relatedSpdxElement": "SPDXRef-File-abc.java"
},
{
  "spdxElementId": "SPDXRef-Package-dummy",
  "relationshipType": "CONTAINS",
  "relatedSpdxElement": "SPDXRef-File-abc.java"
},
{
  "spdxElementId": "SPDXRef-DOCUMENT",
  "relationshipType": "DESCRIBES",
  "relatedSpdxElement": "SPDXRef-File-test.java"
}

Is this the correct way to represent the file paths in the SPDX document? If not, could you please provide the correct format and any additional details that I should include? Should the local file path be mentioned inside the package or outside the package? According to section 5.2.3 of the SPDX specification 2.3, if a file is not part of any package, it should precede any package information section reference in the SPDX document.

Please find the full SPDX document for reference :

{
  "SPDXID": "SPDXRef-DOCUMENT",
  "spdxVersion": "SPDX-2.3",
  "creationInfo": {
    "created": "2025-01-24T11:38:57Z",
    "creators": [
      "Tool: SPDX-Tools-2.3"
    ],
    "licenseListVersion": "3.18"
  },
  "name": "Example-SPDX-Document",
  "dataLicense": "CC0-1.0",
  "documentNamespace": "http://spdx.org/spdxdocs/example-spdx-document",
  "packages": [
    {
      "SPDXID": "SPDXRef-Package-dummy",
      "name": "dummy",
      "versionInfo": "1.0",
      "supplier": "Organization: ExampleSupplier",
      "downloadLocation": "NOASSERTION",
      "originator": "NOASSERTION",
      "licenseDeclared": "NOASSERTION",
      "licenseConcluded": "NOASSERTION",
      "copyrightText": "NOASSERTION",
      "filesAnalyzed": true,
      "hasFiles": [
        "SPDXRef-File-abc.java"
      ],
      "packageVerificationCode": {
        "packageVerificationCodeValue": "1234567890abcdef1234567890abcdef12345678"
      }
    }
  ],
  "files": [
    {
      "SPDXID": "SPDXRef-File-abc.java",
      "fileName": "./src/abc.java",
      "checksums": [
        {
          "algorithm": "SHA256",
          "checksumValue": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        },
        {
          "algorithm": "SHA1",
          "checksumValue": "1234567890abcdef1234567890abcdef12345678"
        }
      ],
      "fileTypes": [
        "SOURCE"
      ],
      "licenseConcluded": "NOASSERTION",
      "copyrightText": "NOASSERTION"
    },
    {
      "SPDXID": "SPDXRef-File-test.java",
      "fileName": "./local/src/test/test.java",
      "checksums": [
        {
          "algorithm": "SHA256",
          "checksumValue": "0987654321fedcba0987654321fedcba0987654321fedcba0987654321fedcba"
        },
        {
          "algorithm": "SHA1",
          "checksumValue": "fedcba0987654321fedcba0987654321fedcba09"
        }
      ],
      "fileTypes": [
        "SOURCE"
      ],
      "licenseConcluded": "NOASSERTION",
      "copyrightText": "NOASSERTION",
      "comment": "This file is part of the local codebase and was taken from the dummy package."
    }
  ],
  "relationships": [
    {
      "spdxElementId": "SPDXRef-File-test.java",
      "relationshipType": "DESCENDANT_OF",
      "relatedSpdxElement": "SPDXRef-File-abc.java"
    },
    {
      "spdxElementId": "SPDXRef-Package-dummy",
      "relationshipType": "CONTAINS",
      "relatedSpdxElement": "SPDXRef-File-abc.java"
    },
    {
      "spdxElementId": "SPDXRef-DOCUMENT",
      "relationshipType": "DESCRIBES",
      "relatedSpdxElement": "SPDXRef-File-test.java"
    }
  ]
}

Thanks in advance!

[goneall]

Looks good to me with one consideration:

• If the file was not modified and is not intended to be modified (e.g. a straight copy), the relationship COPY_OF may be more accurate. Otherwise, DESCENDANT_OF is fine.

All other relationships are what I would expect if the intent of the SPDX document is to describe the the "copied" file.

[nishanthsankaran]

Thank you, @goneall , for the feedback and additional information.

Let’s assume that the local file SPDXRef-File-test.java is a modified version and not an exact copy of SPDXRef-File-abc.java from the dummy package.

I’m encountering some confusion regarding the placement of the file element: SPDXRef-File-test.java.

As per section 5.2.3, specifically the 4th bullet point, if a file is not part of any package, it must appear before any package information section in the SPDX document.

In this scenario, since local file SPDXRef-File-test.java is a modified version and not part of the dummy package, should it be arranged as follows:

{
  "Files": [
    "SPDXRef-File-test.java"
  ],
  "Package": {
    "name": "dummy",
    "files": [
      "SPDXRef-File-abc.java"
    ]
  }
}

Instead of:

{
  "Package": {
    "name": "dummy"
  },
  "files": [
    "SPDXRef-File-abc.java",
    "SPDXRef-File-test.java"
  ]
}

Please let me know if I have misunderstood section 5.2.3.

[goneall]

As per section 5.2.3, specifically the 4th bullet point, if a file is not part of any package, it must appear before any package information section in the SPDX document.

@jacknishanth07 - My interpretation is the position of the file is only relevant in the tag/value document and does not apply to the JSON format - although in re-reading the spec, this isn't made clear.

@armintaenzertng - do you agree with my interpretation?

[nishanthsankaran]

My interpretation is the position of the file is only relevant in the tag/value document and does not apply to the JSON format - although in re-reading the spec, this isn't made clear.

Thank you @goneall for clarifying that the position of the file does not apply to the JSON format. To validate this, I converted the JSON to tag/value format using the SPDX tool and observed the following: individual files are placed immediately before the package, and files associated with a package are placed just after the respective package. Placing below for reference.

SPDXVersion: SPDX-2.3
DataLicense: CC0-1.0
DocumentNamespace: http://spdx.org/spdxdocs/example-spdx-document
DocumentName: Example-SPDX-Document
SPDXID: SPDXRef-DOCUMENT

## Creation Information
Creator: Tool: SPDX-Tools-2.3
Created: 2025-01-24T11:38:57Z
LicenseListVersion: 3.18
## Relationships
Relationship: SPDXRef-DOCUMENT DESCRIBES SPDXRef-File-test.java

FileName: ./local/src/test/test.java
SPDXID: SPDXRef-File-test.java
FileComment: <text>This file is part of the local codebase and was taken from the dummy package.</text>
FileType: SOURCE
FileChecksum: SHA1: fedcba0987654321fedcba0987654321fedcba09
FileChecksum: SHA256: 0987654321fedcba0987654321fedcba0987654321fedcba0987654321fedcba
LicenseConcluded: NOASSERTION
FileCopyrightText: NOASSERTION
## Relationships
Relationship: SPDXRef-File-test.java DESCENDANT_OF SPDXRef-File-abc.java

## Package Information
PackageName: dummy
SPDXID: SPDXRef-Package-dummy
PackageVersion: 1.0
PackageSupplier: Organization: ExampleSupplier
PackageOriginator: NOASSERTION
PackageDownloadLocation: NOASSERTION
PackageVerificationCode: 1234567890abcdef1234567890abcdef12345678
PackageLicenseConcluded: NOASSERTION
PackageLicenseDeclared: NOASSERTION
PackageCopyrightText: NOASSERTION
## Relationships
Relationship: SPDXRef-Package-dummy CONTAINS SPDXRef-File-abc.java

## File Information
FileName: ./src/abc.java
SPDXID: SPDXRef-File-abc.java
FileType: SOURCE
FileChecksum: SHA1: 1234567890abcdef1234567890abcdef12345678
FileChecksum: SHA256: abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
LicenseConcluded: NOASSERTION
FileCopyrightText: NOASSERTION

As a suggestion, we could enhance Section 5.2.3 by explicitly stating that the positional requirement is specific to the tag:value format and does not apply to other SPDX data formats. While the specification mentions that "when implementing the tag:value format, the positioning of file elements is syntactically significant," it would be helpful to clarify that this does not extend to formats like JSON or YAML.

Once again, thank you @goneall for your clarification. Please feel free to close this GitHub issue.