git.stella-ops.org/docs/modules/sbom-service/spdx3-profile-support.md

SPDX 3.0.1 Profile Support

Version: Draft Status: Planned Sprint: SPRINT_20260107_004

This document describes StellaOps support for SPDX 3.0.1 and its profile-based model.

---

Overview

SPDX 3.0.1 introduces a profile-based model that extends the Core specification with domain-specific metadata. StellaOps implements the following profiles:

Profile	Status	Description	Integration
Core	Planned	Foundation for all elements	Required
Software	Planned	Packages, files, snippets	Scanner
Lite	Planned	Minimal CI/CD SBOMs	Scanner
Build	Planned	Build provenance	Attestor
Security	Planned	Vulnerability assessments	VexLens
Licensing	Future	License expressions	Policy
AI	Future	AI model artifacts	AdvisoryAI
Dataset	Future	Dataset metadata	Future

---

Current Support

SPDX 2.x (Current)

StellaOps currently supports SPDX 2.2 and 2.3:

• Parsing: Full support via SpdxParser
• Generation: SPDX 2.3 JSON format
• Integration: AirGap importer, Scanner output

SPDX 3.0.1 (Planned)

Full SPDX 3.0.1 support is planned with:

• Parsing: JSON-LD format with profile detection
• Generation: Profile-conformant output
• Integration: Attestor (Build), VexLens (Security)

---

Profile Details

Core Profile

The Core profile is the foundation for all SPDX 3.0.1 documents.

Key Elements:

• Element - Base for all typed elements
• Relationship - Links between elements
• CreationInfo - Document metadata
• ExternalRef - References to external resources
• ExternalIdentifier - PURL, CPE, SWID identifiers
• IntegrityMethod - Hash verification

Required Fields:

• spdxId - Unique IRI identifier
• creationInfo - With specVersion: "3.0.1"

Software Profile

The Software profile describes software components.

Key Elements:

• Package - Software package
• File - Individual file
• Snippet - Code snippet
• SpdxDocument - Document root

Common Properties:

• packageVersion - Version string
• packageUrl - PURL (via ExternalIdentifier)
• downloadLocation - Source URL
• homePage - Project homepage

Example:

{
  "@type": "software_Package",
  "spdxId": "urn:stellaops:spdx:sha256-abc:Package:xyz",
  "name": "example-package",
  "software_packageVersion": "1.0.0",
  "externalIdentifier": [
    {
      "@type": "ExternalIdentifier",
      "externalIdentifierType": "packageUrl",
      "identifier": "pkg:npm/example-package@1.0.0"
    }
  ]
}

Lite Profile

The Lite profile provides minimal SBOMs for CI/CD pipelines.

Minimal Required Fields:

• spdxId
• creationInfo (created, createdBy, specVersion)
• name
• packageVersion (for packages)
• downloadLocation OR packageUrl

Use Cases:

• CI/CD pipeline artifacts
• Quick compliance checks
• Lightweight transmission

Build Profile

The Build profile captures build provenance.

Key Element:

• Build - Build process information

Properties:

• buildType - Build system URI
• buildId - Unique build identifier
• buildStartTime / buildEndTime - Timing
• configSourceUri - Build configuration sources
• environment - Build environment
• parameter - Build parameters

Integration with Attestor:

in-toto/SLSA             SPDX 3.0.1 Build
-----------              ----------------
buildType           -->  build_buildType
builder.id          -->  createdBy (Agent)
invocation.config   -->  build_configSourceUri
materials           -->  Relationships (GENERATED_FROM)

Security Profile

The Security profile describes vulnerability assessments.

Key Elements:

• Vulnerability - CVE/vulnerability reference
• VexAffectedVulnAssessmentRelationship
• VexNotAffectedVulnAssessmentRelationship
• VexFixedVulnAssessmentRelationship
• VexUnderInvestigationVulnAssessmentRelationship
• CvssV3VulnAssessmentRelationship
• EpssVulnAssessmentRelationship

Integration with VexLens:

OpenVEX                  SPDX 3.0.1 Security
-------                  -------------------
status: affected    -->  VexAffectedVulnAssessmentRelationship
status: not_affected --> VexNotAffectedVulnAssessmentRelationship
status: fixed       -->  VexFixedVulnAssessmentRelationship
justification       -->  statusNotes
action_statement    -->  actionStatement

---

JSON-LD Structure

SPDX 3.0.1 uses JSON-LD format:

{
  "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld",
  "@graph": [
    {
      "@type": "SpdxDocument",
      "spdxId": "urn:example:doc",
      "creationInfo": {
        "@type": "CreationInfo",
        "specVersion": "3.0.1",
        "created": "2026-01-07T12:00:00Z",
        "createdBy": ["urn:example:tool:stellaops"],
        "profile": [
          "https://spdx.org/rdf/3.0.1/terms/Core/ProfileIdentifierType/core",
          "https://spdx.org/rdf/3.0.1/terms/Software/ProfileIdentifierType/software"
        ]
      },
      "rootElement": ["urn:example:pkg:root"],
      "element": [
        "urn:example:pkg:root",
        "urn:example:pkg:dep1"
      ]
    },
    {
      "@type": "software_Package",
      "spdxId": "urn:example:pkg:root",
      "name": "my-application",
      "software_packageVersion": "2.0.0"
    }
  ]
}

---

API Usage

Scanner SBOM Generation

GET /api/v1/scan/{id}/sbom?format=spdx3&profile=software

Parameters:

Parameter	Values	Default
format	spdx3, spdx2, cyclonedx	spdx2
profile	software, lite	software

Attestor Build Profile

GET /api/v1/attestation/{id}?format=spdx3

VexLens Security Profile

GET /api/v1/vex/consensus/{artifact}?format=spdx3

---

Profile Conformance

Documents declare profile conformance in CreationInfo.profile:

{
  "profile": [
    "https://spdx.org/rdf/3.0.1/terms/Core/ProfileIdentifierType/core",
    "https://spdx.org/rdf/3.0.1/terms/Software/ProfileIdentifierType/software",
    "https://spdx.org/rdf/3.0.1/terms/Security/ProfileIdentifierType/security"
  ]
}

StellaOps validates documents against declared profiles when:

• Parsing external documents (opt-in validation)
• Generating documents (automatic conformance)

---

Migration from SPDX 2.x

Parallel Support

During transition, StellaOps supports both formats:

1. SPDX 2.x - Default for backward compatibility
2. SPDX 3.0.1 - Opt-in via format=spdx3

Key Differences

Aspect	SPDX 2.x	SPDX 3.0.1
Format	Flat JSON	JSON-LD
Version field	spdxVersion	specVersion in CreationInfo
Packages	packages[] array	@graph with @type
Relationships	relationships[]	Relationship elements in @graph
Checksums	checksums[]	verifiedUsing IntegrityMethod
PURL	externalRefs	externalIdentifier

Version Detection

StellaOps auto-detects SPDX version:

// 2.x: Has spdxVersion property
if (root.TryGetProperty("spdxVersion", out _))
    return SpdxVersion.V2;

// 3.x: Has @context property
if (root.TryGetProperty("@context", out _))
    return SpdxVersion.V3;

---

Air-Gap Considerations

For air-gapped deployments:

1. Bundle contexts locally - SPDX JSON-LD contexts must be available offline
2. Configure local context URIs - Point to local context files
3. Validate offline - Use bundled schemas for validation

# etc/spdx3.yaml
Spdx3:
  ContextResolution:
    Mode: Local  # or Remote, Cached
    LocalContextPath: /etc/stellaops/spdx3-contexts/

---

References

• SPDX 3.0.1 Specification
• SPDX 3.0.1 Model Repository
• Sprint: SPDX 3.0.1 Profile Support