spdx-format

spdx-format

Overview

SPDX is the Linux Foundation's SBOM standard, originally focused on license compliance. Per spdx.org/specifications:

Two active major versions:

Version	Status	Notable
SPDX 2.3	Stable; broadly tooled	Tag-Value / JSON / YAML / RDF / Spreadsheet; ISO/IEC 5962:2021
SPDX 3.0	Recent (2024); growing tooling	Profile-based: core + software + AI + dataset + build + security; JSON-LD primary

This is a reference skill - defines the schema + tooling landscape; doesn't run scans. Pair with syft-generation to generate SPDX-format SBOMs.

When to use

• US Federal procurement context (NIST SP 800-218 + EO 14028 guidance favor SPDX).
• Linux Foundation member organization workflow.
• License-compliance focused use case (SPDX has the richest license-expression vocabulary).
• A consumer (regulator, customer) requires SPDX format specifically.

For security-focused use cases, cyclonedx-format has richer first-class vuln support.

Step 1 - SPDX 2.3 top-level structure (JSON)

{
  "spdxVersion": "SPDX-2.3",
  "dataLicense": "CC0-1.0",
  "SPDXID": "SPDXRef-DOCUMENT",
  "name": "my-app-1.0.0-sbom",
  "documentNamespace": "https://example.com/spdx/my-app/1.0.0",
  "creationInfo": {
    "created": "2026-05-06T12:00:00Z",
    "creators": ["Tool: syft-1.16.0", "Organization: Acme Corp"]
  },
  "packages": [
    {
      "SPDXID": "SPDXRef-Package-myapp",
      "name": "my-app",
      "versionInfo": "1.0.0",
      "downloadLocation": "NOASSERTION",
      "filesAnalyzed": false,
      "licenseConcluded": "Apache-2.0",
      "licenseDeclared": "Apache-2.0"
    },
    {
      "SPDXID": "SPDXRef-Package-lodash",
      "name": "lodash",
      "versionInfo": "4.17.20",
      "downloadLocation": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz",
      "filesAnalyzed": false,
      "licenseConcluded": "MIT",
      "licenseDeclared": "MIT"
    }
  ],
  "relationships": [
    {
      "spdxElementId": "SPDXRef-DOCUMENT",
      "relationshipType": "DESCRIBES",
      "relatedSpdxElement": "SPDXRef-Package-myapp"
    },
    {
      "spdxElementId": "SPDXRef-Package-myapp",
      "relationshipType": "DEPENDS_ON",
      "relatedSpdxElement": "SPDXRef-Package-lodash"
    }
  ]
}

Step 2 - Required fields per SPDX 2.3

Per spdx-spec:

Field	Required?	Use
spdxVersion	yes	Must be "SPDX-2.3"
dataLicense	yes	"CC0-1.0" (CC0 - the SBOM data itself)
SPDXID	yes	"SPDXRef-DOCUMENT"
name	yes	Human-readable doc name
documentNamespace	yes	Unique URI per BOM revision
creationInfo.created	yes	ISO 8601 timestamp
creationInfo.creators	yes	Tool / org / person who created
packages[]	required for non-empty BOM	Inventory
relationships[]	required (at least DESCRIBES)	Dep graph

Step 3 - License expressions

SPDX is the canonical source for license identifiers (cross-format standard - even CycloneDX uses SPDX license IDs).

"licenseConcluded": "Apache-2.0",
"licenseConcluded": "MIT OR Apache-2.0",
"licenseConcluded": "(MIT AND BSD-3-Clause) OR GPL-2.0-only WITH Classpath-exception-2.0"

Full list: spdx.org/licenses (current count ~600+).

The LicenseRef- prefix declares custom licenses:

"hasExtractedLicensingInfos": [{
  "licenseId": "LicenseRef-AcmeProprietary",
  "extractedText": "Acme Proprietary License Text..."
}],
"licenseConcluded": "LicenseRef-AcmeProprietary"

Step 4 - Relationships

The relationships[] block is the dep-graph (SPDX equivalent of CycloneDX's dependencies[]):

RelationshipType	Use
DESCRIBES / DESCRIBED_BY	Document ↔ top-level package
DEPENDS_ON / DEPENDENCY_OF	Compile-time / runtime dep
BUILD_DEPENDENCY_OF	Build-only dep
DEV_DEPENDENCY_OF	Test/dev-only dep
RUNTIME_DEPENDENCY_OF	Runtime-only dep
OPTIONAL_DEPENDENCY_OF	Optional dep
CONTAINS / CONTAINED_BY	Container ↔ contained file/package
GENERATED_FROM	Source-of-build
STATIC_LINK / DYNAMIC_LINK	Linkage type

Step 5 - Tag-Value format (SPDX-native)

Some toolchains use the SPDX Tag-Value format (older but well-tooled):

SPDXVersion: SPDX-2.3
DataLicense: CC0-1.0
SPDXID: SPDXRef-DOCUMENT
DocumentName: my-app-1.0.0-sbom
DocumentNamespace: https://example.com/spdx/my-app/1.0.0
Creator: Tool: syft-1.16.0
Creator: Organization: Acme Corp
Created: 2026-05-06T12:00:00Z

PackageName: my-app
SPDXID: SPDXRef-Package-myapp
PackageVersion: 1.0.0
PackageDownloadLocation: NOASSERTION
FilesAnalyzed: false
PackageLicenseConcluded: Apache-2.0
PackageLicenseDeclared: Apache-2.0

Relationship: SPDXRef-DOCUMENT DESCRIBES SPDXRef-Package-myapp

JSON is preferred for new toolchains; Tag-Value persists for legacy integrations.

Step 6 - SPDX 3.0 profiles

SPDX 3.0 (2024 release) restructures into composable profiles:

Profile	Use
core	Minimum BOM model
software	Software-specific extensions (≈ SPDX 2.3 packages)
licensing	License identification + expressions
security	Vulnerability + VEX statements
ai	AI/ML models, datasets, hyperparameters
dataset	Dataset-specific metadata
build	Build provenance (similar to in-toto attestations)

JSON-LD is the primary encoding; tooling support is growing but less mature than 2.3 as of 2026.

For most teams, stay on SPDX 2.3 unless 3.0 features are required - 2.3 has broader tooling.

Step 7 - Tooling

Tool	Use
syft	Generates SPDX 2.3 (JSON / Tag-Value); cross-source
spdx-tools	Reference impl (Python); validation + conversion
spdx-tools-java	Java reference impl
ORT (OSS Review Toolkit)	License compliance scanning + SPDX reporting
spdx-sbom-generator	Per-language native generation
tern	Container image SPDX generation
Trivy	Cross-purpose scanner with SPDX output

Step 8 - Validation

# Python spdx-tools
pip install spdx-tools
pyspdxtools --infile sbom.spdx.json --version SPDX-2.3
# Validates structural conformance + license-expression syntax

# Validation via spdx online tool
# Upload to https://tools.spdx.org/app/

Step 9 - CI integration

jobs:
  spdx:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: anchore/sbom-action@v0
        with:
          format: spdx-json
          output-file: sbom.spdx.json
      - run: |
          pip install spdx-tools
          pyspdxtools --infile sbom.spdx.json --version SPDX-2.3
      - uses: actions/upload-artifact@v4
        with:
          name: spdx-sbom
          path: sbom.spdx.json

Anti-patterns

Anti-pattern	Why it fails	Fix
Skip documentNamespace	Can't deduplicate across BOM revisions	Generate unique URI per BOM
Use SPDX 3.0 with consumer expecting 2.3	Tooling incompat	Stick to SPDX 2.3 unless 3.0 required (Step 6)
Manual license assignment without LicenseRef- for custom	License-expression validation fails	Use proper SPDX license ID or LicenseRef- (Step 3)
Skip relationships[] (just packages)	No dep-graph; downstream tools degrade	Always include DESCRIBES + DEPENDS_ON (Step 4)
Mix Tag-Value + JSON in same workflow	Toolchain confusion	Pick one format per workflow (Step 5)

Limitations

• SPDX 2.3 vuln support is weaker than CycloneDX 1.6 (no first-class vulnerabilities block - relies on companion VEX docs).
• License-expression validation is strict; non-standard licenses require LicenseRef- boilerplate.
• SPDX 3.0 tooling is still maturing; many tools still produce 2.3.
• Tag-Value parsing is whitespace-sensitive; subtle formatting bugs.

References

• spdx-spec - official specification
• spdx.dev - landing
• spdx.org/licenses - license ID list
• iso.org/standard/81870.html - ISO/IEC 5962:2021 (SPDX 2.2.1 ISO publication)
• tools.spdx.org - online validator
• github.com/spdx/tools-python - Python reference impl
• syft-generation, grype-scanning, cyclonedx-format, trivy-image - sister tools
• vuln-prioritizer - unifier agent