0
# SPDX 3.0 Support
1

2
Experimental support for the upcoming SPDX 3.0 specification including new data models, profile support, and enhanced capabilities. This functionality is under active development and subject to change.
3

4
## Capabilities
5

6
### SPDX 3.0 Document Structure  
7

8
New document model for SPDX 3.0 with enhanced element-based architecture.
9

10
```python { .api }
11
class SpdxDocument:
12
    """
13
    SPDX 3.0 document root.
14
    
15
    Represents the main container for SPDX 3.0 elements with
16
    creation information and element collections.
17
    """
18
    creation_info: CreationInfo
19
    elements: List[Element]
20

21
class CreationInfo:
22
    """
23
    SPDX 3.0 document creation information.
24
    
25
    Enhanced creation info with additional metadata support
26
    and profile identification.
27
    """
28
    spec_version: str                           # SPDX 3.0 specification version
29
    spdx_id: str                               # Document SPDX identifier  
30
    name: str                                  # Document name
31
    document_namespace: str                    # Unique document namespace
32
    creators: List[Agent]                      # Document creators (enhanced)
33
    created: datetime                          # Creation timestamp
34
    profile: List[ProfileIdentifierType]      # Supported profiles
35
    data_license: str                          # Data license
36
    imports: List[str] = []                    # Imported namespace URIs
37
    extension_map: List[NamespaceMap] = []     # Extension mappings
38
    external_map: List[ExternalMap] = []       # External references
39
    verify_using: List[IntegrityMethod] = []   # Verification methods
40
```
41

42
### Base Element Model
43

44
Foundation classes for all SPDX 3.0 elements.
45

46
```python { .api }
47
class Element:
48
    """
49
    Base class for all SPDX 3.0 elements.
50
    
51
    Provides common properties for packages, files, and other
52
    SPDX elements in the 3.0 specification.
53
    """
54
    spdx_id: str                               # Element SPDX identifier
55
    name: Optional[str] = None                 # Element name
56
    summary: Optional[str] = None              # Element summary
57
    description: Optional[str] = None          # Element description
58
    comment: Optional[str] = None              # Element comment
59
    verification_info: List[IntegrityMethod] = []  # Verification methods
60
    external_references: List[ExternalReference] = []  # External references
61
    external_identifiers: List[ExternalIdentifier] = []  # External identifiers
62
    extension_map: List[NamespaceMap] = []     # Extension mappings
63

64
class Artifact(Element):
65
    """
66
    Base class for artifacts (files, packages, etc.).
67
    
68
    Represents downloadable or distributable software artifacts
69
    with integrity and origin information.
70
    """
71
    originated_by: List[Agent] = []            # Artifact originators
72
    supplied_by: List[Agent] = []              # Artifact suppliers
73
    built_time: Optional[datetime] = None      # Build timestamp
74
    release_time: Optional[datetime] = None    # Release timestamp  
75
    valid_until_time: Optional[datetime] = None  # Validity period
76
```
77

78
### Agent System
79

80
Enhanced agent/actor model for SPDX 3.0.
81

82
```python { .api }
83
class Agent(Element):
84
    """Base agent/actor class for SPDX 3.0."""
85
    pass
86

87
class Person(Agent):
88
    """
89
    Person agent representing an individual.
90
    
91
    Represents a human individual involved in software
92
    development or distribution.
93
    """
94
    pass
95

96
class Organization(Agent):
97
    """
98
    Organization agent representing a company or group.
99
    
100
    Represents an organizational entity involved in software
101
    development or distribution.
102
    """
103
    pass
104

105
class SoftwareAgent(Agent):
106
    """
107
    Software agent representing automated systems.
108
    
109
    Represents software systems, scripts, or automated
110
    processes involved in software creation.
111
    """
112
    pass
113

114
class Tool(SoftwareAgent):
115
    """
116
    Tool agent representing development/build tools.
117
    
118
    Represents specific tools used in software development,
119
    building, or analysis processes.
120
    """
121
    pass
122
```
123

124
### Collections and Bundles
125

126
Organizational structures for grouping SPDX 3.0 elements.
127

128
```python { .api }
129
class ElementCollection(Element):
130
    """
131
    Collection of SPDX elements.
132
    
133
    Provides grouping mechanism for organizing related
134
    SPDX elements together.
135
    """
136
    elements: List[str] = []                   # Element SPDX IDs in collection
137
    root_elements: List[str] = []              # Root element SPDX IDs
138

139
class Bundle(ElementCollection):
140
    """
141
    Bundle of related SPDX elements.
142
    
143
    Represents a logical grouping of elements that
144
    are distributed or processed together.
145
    """
146
    pass
147

148
class Bom(ElementCollection):
149
    """
150
    Bill of Materials (BOM).
151
    
152
    Represents a structured inventory of software
153
    components and their relationships.
154
    """
155
    pass
156
```
157

158
### Relationships and Annotations
159

160
Enhanced relationship and annotation system for SPDX 3.0.
161

162
```python { .api }
163
class Relationship(Element):
164
    """
165
    Relationship between SPDX 3.0 elements.
166
    
167
    Enhanced relationship model with lifecycle scoping
168
    and improved semantics.
169
    """
170
    from_element: str                          # Source element SPDX ID
171
    relationship_type: RelationshipType        # Type of relationship
172
    to_elements: List[str] = []                # Target element SPDX IDs
173
    completeness: Optional[RelationshipCompleteness] = None  # Completeness indicator
174

175
class LifecycleScopedRelationship(Relationship):
176
    """
177
    Lifecycle-scoped relationship.
178
    
179
    Represents relationships that are valid only during
180
    specific lifecycle phases.
181
    """
182
    scope: Optional[LifecycleScopeType] = None  # Lifecycle scope
183

184
class Annotation(Element):
185
    """
186
    Annotation on SPDX 3.0 elements.
187
    
188
    Enhanced annotation system with improved
189
    metadata and categorization.
190
    """
191
    subject: str                               # Annotated element SPDX ID
192
    annotation_type: AnnotationType            # Annotation type
193
    annotator: Agent                           # Annotation creator
194
    annotation_date: datetime                  # Annotation timestamp
195
    statement: str                             # Annotation content
196
```
197

198
### Profile-Specific Models
199

200
Specialized models for different SPDX 3.0 profiles.
201

202
```python { .api }
203
# Software Profile
204
class SoftwareArtifact(Artifact):
205
    """Software artifact in software profile."""
206
    pass
207

208
class Package(SoftwareArtifact):
209
    """Software package with enhanced metadata."""
210
    package_url: Optional[str] = None          # Package URL (purl)
211
    download_location: Optional[str] = None    # Download location
212
    files_analyzed: Optional[bool] = None      # Whether files were analyzed
213
    package_verification_code: Optional[str] = None  # Verification code
214

215
class File(SoftwareArtifact):
216
    """Software file with enhanced metadata."""
217
    content_type: Optional[str] = None         # MIME content type
218

219
class Directory(SoftwareArtifact):
220
    """Directory containing software files."""
221
    pass
222

223
class Snippet(SoftwareArtifact):
224
    """Code snippet within a file."""
225
    byte_range: Optional[Range] = None         # Byte range in file
226
    line_range: Optional[Range] = None         # Line range in file
227

228
# AI Profile  
229
class AIPackage(Package):
230
    """AI/ML package with specialized metadata."""
231
    pass
232

233
# Build Profile
234
class Build(Element):
235
    """Build process information."""
236
    pass
237

238
# Dataset Profile
239
class Dataset(Element):
240
    """Dataset information for data packages."""
241
    pass
242

243
# Licensing Profile
244
class LicenseExpression(Element):
245
    """License expression evaluation."""
246
    pass
247

248
class License(Element):
249
    """License information."""
250
    pass
251

252
class LicenseAddition(Element):
253
    """License exception or addition."""
254
    pass
255

256
class CustomLicense(License):
257
    """Custom license not in SPDX list."""
258
    pass
259

260
class CustomLicenseAddition(LicenseAddition):
261
    """Custom license addition."""
262
    pass
263
```
264

265
### Security Profile
266

267
Security-related models for vulnerability assessment.
268

269
```python { .api }
270
class VulnAssessmentRelationship(Relationship):
271
    """Base vulnerability assessment relationship."""
272
    assessed_element: str                      # Element being assessed
273
    supplier: Optional[Agent] = None           # Assessment supplier
274
    published_time: Optional[datetime] = None  # Publication timestamp
275

276
class VexAffectedVulnAssessmentRelationship(VulnAssessmentRelationship):
277
    """VEX affected vulnerability assessment."""
278
    action_statement: Optional[str] = None     # Recommended action
279
    action_statement_time: Optional[datetime] = None  # Action timestamp
280
    justification_type: Optional[str] = None   # Justification type
281
    impact_statement: Optional[str] = None     # Impact description
282
    impact_statement_time: Optional[datetime] = None  # Impact timestamp
283

284
class VexFixedVulnAssessmentRelationship(VulnAssessmentRelationship):  
285
    """VEX fixed vulnerability assessment."""
286
    pass
287

288
class VexNotAffectedVulnAssessmentRelationship(VulnAssessmentRelationship):
289
    """VEX not affected vulnerability assessment."""
290
    impact_statement: Optional[str] = None     # Impact description
291
    impact_statement_time: Optional[datetime] = None  # Impact timestamp
292
    justification_type: Optional[str] = None   # Justification type
293

294
class VexUnderInvestigationVulnAssessmentRelationship(VulnAssessmentRelationship):
295
    """VEX under investigation vulnerability assessment."""
296
    pass
297
```
298

299
### Supporting Types
300

301
Enhanced supporting types for SPDX 3.0.
302

303
```python { .api }
304
class Hash(IntegrityMethod):
305
    """
306
    Cryptographic hash for integrity verification.
307
    
308
    Enhanced hash support with additional algorithms
309
    and metadata.
310
    """
311
    algorithm: HashAlgorithm                   # Hash algorithm
312
    hash_value: str                           # Hash value
313

314
class ExternalReference:
315
    """
316
    Reference to external resource.
317
    
318
    Enhanced external reference system with
319
    categorization and verification.
320
    """
321
    external_reference_type: ExternalReferenceType  # Reference type
322
    locator: str                              # Resource locator
323
    content_type: Optional[str] = None        # MIME content type
324
    comment: Optional[str] = None             # Reference comment
325

326
class ExternalIdentifier:
327
    """
328
    External identifier for elements.
329
    
330
    Links SPDX elements to external identification
331
    systems and registries.
332
    """
333
    external_identifier_type: ExternalIdentifierType  # Identifier type
334
    identifier: str                           # Identifier value
335
    issuing_authority: Optional[str] = None   # Authority that issued ID
336
    comment: Optional[str] = None             # Identifier comment
337

338
class ExternalMap:
339
    """External namespace mapping."""
340
    external_spdx_id: str                     # External SPDX ID
341
    verification_info: IntegrityMethod        # Verification method
342

343
class NamespaceMap:
344
    """Namespace mapping for extensions."""
345
    prefix: str                               # Namespace prefix
346
    namespace: str                            # Namespace URI
347
```
348

349
### CLI Tools
350

351
Command-line interface for SPDX 3.0 operations.
352

353
```python { .api }
354
def main() -> None:
355
    """
356
    CLI entry point for pyspdxtools3 command.
357
    
358
    Experimental CLI for SPDX 3.0 document processing.
359
    Provides parsing, validation, and conversion capabilities
360
    for SPDX 3.0 documents.
361
    
362
    Note: API and functionality subject to change as
363
    SPDX 3.0 specification evolves.
364
    """
365
```
366

367
## Enumerations
368

369
### SPDX 3.0 Specific Enums
370

371
```python { .api }
372
class ProfileIdentifierType(Enum):
373
    """SPDX 3.0 profile identifiers."""
374
    CORE = "core"
375
    SOFTWARE = "software"
376
    AI = "ai"
377
    BUILD = "build"
378
    DATASET = "dataset"
379
    LICENSING = "licensing"
380
    SECURITY = "security"
381

382
class HashAlgorithm(Enum):
383
    """Hash algorithms for SPDX 3.0."""
384
    SHA1 = "sha1"
385
    SHA224 = "sha224"
386
    SHA256 = "sha256"
387
    SHA384 = "sha384"
388
    SHA512 = "sha512"
389
    SHA3_256 = "sha3-256"
390
    SHA3_384 = "sha3-384"
391
    SHA3_512 = "sha3-512"
392
    BLAKE2B_256 = "blake2b-256"
393
    BLAKE2B_384 = "blake2b-384"
394
    BLAKE2B_512 = "blake2b-512"
395
    BLAKE3 = "blake3"
396
    MD5 = "md5"
397

398
class ExternalReferenceType(Enum):
399
    """Types of external references."""
400
    WEBSITE = "website"
401
    VCS = "vcs"
402
    DOWNLOAD = "download"
403
    ISSUE_TRACKER = "issueTracker"
404
    MAILING_LIST = "mailingList"
405
    SOCIAL = "social"
406
    CHAT = "chat"
407
    DOCUMENTATION = "documentation"
408
    SUPPORT = "support"
409
    DISTRIBUTION = "distribution"
410
    SECURITY = "security"
411
    OTHER = "other"
412

413
class ExternalIdentifierType(Enum):
414
    """Types of external identifiers."""
415
    CPE22 = "cpe22"
416
    CPE23 = "cpe23"
417
    CVE = "cve"
418
    SWID = "swid"
419
    PURL = "purl"
420
    GITOID = "gitoid"
421
    OTHER = "other"
422

423
class RelationshipCompleteness(Enum):
424
    """Completeness of relationships."""
425
    COMPLETE = "complete"
426
    INCOMPLETE = "incomplete"
427
    NO_ASSERTION = "noAssertion"
428

429
class LifecycleScopeType(Enum):
430
    """Lifecycle scope types."""
431
    DESIGN = "design"
432
    BUILD = "build"
433
    TEST = "test"
434
    RUNTIME = "runtime"
435
    OTHER = "other"
436
```
437

438
## Usage Examples
439

440
### Creating SPDX 3.0 Documents
441

442
```python
443
from datetime import datetime
444
from spdx_tools.spdx3.model import (
445
    SpdxDocument, CreationInfo, Package, Person, Hash, HashAlgorithm,
446
    ProfileIdentifierType
447
)
448

449
# Create SPDX 3.0 document
450
creation_info = CreationInfo(
451
    spec_version="3.0",
452
    spdx_id="https://example.com/doc#",
453
    name="Example SPDX 3.0 Document",
454
    document_namespace="https://example.com/doc",
455
    creators=[Person(spdx_id="https://example.com/person#alice", name="Alice")],
456
    created=datetime.now(),
457
    profile=[ProfileIdentifierType.CORE, ProfileIdentifierType.SOFTWARE]
458
)
459

460
# Create software package
461
package = Package(
462
    spdx_id="https://example.com/package#main",
463
    name="example-package",
464
    download_location="https://github.com/example/package"
465
)
466

467
# Create document
468
document = SpdxDocument(
469
    creation_info=creation_info,
470
    elements=[package]
471
)
472
```
473

474
### Working with Profiles
475

476
```python
477
# Check document profiles
478
if ProfileIdentifierType.SOFTWARE in document.creation_info.profile:
479
    print("Document supports software profile")
480

481
if ProfileIdentifierType.SECURITY in document.creation_info.profile:
482
    print("Document supports security profile")
483
```
484

485
### Enhanced Relationships
486

487
```python
488
from spdx_tools.spdx3.model import LifecycleScopedRelationship, LifecycleScopeType
489

490
# Create lifecycle-scoped relationship
491
relationship = LifecycleScopedRelationship(
492
    spdx_id="https://example.com/rel#1",
493
    from_element="https://example.com/package#main",
494
    relationship_type=RelationshipType.DEPENDS_ON,
495
    to_elements=["https://example.com/package#dep"],
496
    scope=LifecycleScopeType.BUILD
497
)
498
```
499

500
## Migration Notes
501

502
Key differences when migrating from SPDX 2.x to 3.0:
503

504
- **Element-based architecture**: All components are now Elements with SPDX IDs
505
- **Profile system**: Documents can support multiple profiles (software, AI, security, etc.)
506
- **Enhanced agents**: More sophisticated agent/actor model
507
- **Improved relationships**: Lifecycle scoping and completeness indicators
508
- **Namespace changes**: URIs instead of simple SPDX IDs
509
- **Extended metadata**: More comprehensive metadata support
510

511
**Note**: SPDX 3.0 support is experimental and subject to change as the specification evolves.