# SPDX 3.0.1 Profile Support

> **Version:** Draft
> **Status:** Planned
> **Sprint:** [SPRINT_20260107_004](../../implplan/SPRINT_20260107_004_000_INDEX_spdx3_profile_support.md)

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:**
```json
{
  "@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:

```json
{
  "@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

```http
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

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

### VexLens Security Profile

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

---

## Profile Conformance

Documents declare profile conformance in `CreationInfo.profile`:

```json
{
  "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:

```csharp
// 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

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

---

## References

- [SPDX 3.0.1 Specification](https://spdx.github.io/spdx-spec/v3.0.1/)
- [SPDX 3.0.1 Model Repository](https://github.com/spdx/spdx-3-model)
- [Sprint: SPDX 3.0.1 Profile Support](../../implplan/SPRINT_20260107_004_000_INDEX_spdx3_profile_support.md)