0
# Data Models
1
2
Comprehensive object model representing all SPDX specification elements including documents, packages, files, relationships, and metadata with full type safety and validation support.
3
4
## Capabilities
5
6
### Document Structure
7
8
Main SPDX document containing all elements and metadata.
9
10
```python { .api }
11
class Document:
12
"""
13
Main SPDX document containing all elements.
14
15
Represents a complete SPDX document with creation info,
16
packages, files, snippets, licensing info, relationships, and annotations.
17
"""
18
creation_info: CreationInfo
19
packages: List[Package]
20
files: List[File]
21
snippets: List[Snippet]
22
extracted_licensing_infos: List[ExtractedLicensingInfo]
23
relationships: List[Relationship]
24
annotations: List[Annotation]
25
26
class CreationInfo:
27
"""
28
Document creation metadata.
29
30
Contains information about how, when, and by whom the SPDX document was created.
31
"""
32
spdx_version: str # SPDX specification version
33
spdx_id: str # Document SPDX identifier
34
name: str # Document name
35
document_namespace: str # Unique document namespace URI
36
creators: List[Actor] # Document creators
37
created: datetime # Creation timestamp
38
creator_comment: Optional[str] = None # Creator comments
39
data_license: str = "CC0-1.0" # Data license (default CC0-1.0)
40
external_document_refs: List[ExternalDocumentRef] = [] # References to external documents
41
license_list_version: Optional[Version] = None # SPDX license list version
42
document_comment: Optional[str] = None # General document comments
43
```
44
45
### Package Information
46
47
Software package representation with comprehensive metadata.
48
49
```python { .api }
50
class Package:
51
"""
52
Software package information.
53
54
Represents a software package with metadata including licensing,
55
verification, download location, and relationships.
56
"""
57
spdx_id: str # Package SPDX identifier
58
name: str # Package name
59
download_location: str # Download location URI or NOASSERTION/NONE
60
files_analyzed: bool # Whether files were analyzed
61
verification_code: Optional[PackageVerificationCode] = None # Package verification code
62
checksums: List[Checksum] = [] # Package checksums
63
homepage: Optional[str] = None # Package homepage URI
64
source_info: Optional[str] = None # Source information
65
license_concluded: Union[str, SpdxNoAssertion, SpdxNone] = None # Concluded license
66
license_info_from_files: List[str] = [] # Licenses found in files
67
license_declared: Union[str, SpdxNoAssertion, SpdxNone] = None # Declared license
68
license_comment: Optional[str] = None # License comments
69
copyright_text: Union[str, SpdxNoAssertion, SpdxNone] = None # Copyright text
70
summary: Optional[str] = None # Package summary
71
description: Optional[str] = None # Package description
72
comment: Optional[str] = None # General comments
73
external_package_refs: List[ExternalPackageRef] = [] # External package references
74
attribution_texts: List[str] = [] # Attribution texts
75
primary_package_purpose: Optional[PackagePurpose] = None # Primary purpose
76
built_date: Optional[datetime] = None # Build date
77
release_date: Optional[datetime] = None # Release date
78
valid_until_date: Optional[datetime] = None # Valid until date
79
version: Optional[str] = None # Package version
80
originator: Optional[Actor] = None # Package originator
81
supplier: Optional[Actor] = None # Package supplier
82
83
class PackageVerificationCode:
84
"""Package verification code for integrity checking."""
85
value: str # Verification code value
86
excluded_files: List[str] = [] # Files excluded from verification
87
88
class ExternalPackageRef:
89
"""Reference to external package information."""
90
category: ExternalPackageRefCategory # Reference category
91
package_ref_type: str # Reference type
92
locator: str # Package locator
93
comment: Optional[str] = None # Reference comment
94
```
95
96
### File Information
97
98
File metadata and licensing information.
99
100
```python { .api }
101
class File:
102
"""
103
File information and metadata.
104
105
Represents a file with checksums, licensing, copyright,
106
and other metadata information.
107
"""
108
name: str # File path/name
109
spdx_id: str # File SPDX identifier
110
checksums: List[Checksum] # File checksums
111
file_types: List[FileType] = [] # File types
112
license_concluded: Union[str, SpdxNoAssertion, SpdxNone] = None # Concluded license
113
license_info_in_file: List[str] = [] # Licenses found in file
114
license_comment: Optional[str] = None # License comments
115
copyright_text: Union[str, SpdxNoAssertion, SpdxNone] = None # Copyright text
116
comment: Optional[str] = None # General comments
117
notice: Optional[str] = None # Notice text
118
contributors: List[str] = [] # File contributors
119
attribution_texts: List[str] = [] # Attribution texts
120
```
121
122
### Code Snippets
123
124
Code snippet information for partial file analysis.
125
126
```python { .api }
127
class Snippet:
128
"""
129
Code snippet information.
130
131
Represents a portion of a file with its own licensing
132
and copyright information.
133
"""
134
spdx_id: str # Snippet SPDX identifier
135
file_spdx_id: str # Parent file SPDX ID
136
ranges: List[Range] # Snippet byte/line ranges
137
license_concluded: Union[str, SpdxNoAssertion, SpdxNone] = None # Concluded license
138
license_info_in_snippets: List[str] = [] # Licenses found in snippet
139
license_comment: Optional[str] = None # License comments
140
copyright_text: Union[str, SpdxNoAssertion, SpdxNone] = None # Copyright text
141
comment: Optional[str] = None # General comments
142
name: Optional[str] = None # Snippet name
143
attribution_texts: List[str] = [] # Attribution texts
144
```
145
146
### Relationships
147
148
Relationships between SPDX elements.
149
150
```python { .api }
151
class Relationship:
152
"""
153
Relationship between SPDX elements.
154
155
Defines semantic relationships between packages, files,
156
and other SPDX elements.
157
"""
158
spdx_element_id: str # Source element SPDX ID
159
relationship_type: RelationshipType # Type of relationship
160
related_spdx_element: Optional[str] # Target element SPDX ID
161
comment: Optional[str] = None # Relationship comment
162
```
163
164
### Licensing Information
165
166
Extracted and declared licensing information.
167
168
```python { .api }
169
class ExtractedLicensingInfo:
170
"""
171
License information extracted from files.
172
173
Represents license text found in files that is not
174
in the SPDX license list.
175
"""
176
license_id: str # License identifier
177
extracted_text: str # License text
178
license_name: Optional[str] = None # License name
179
cross_references: List[str] = [] # Cross references
180
license_comment: Optional[str] = None # License comments
181
```
182
183
### Annotations
184
185
Comments and annotations on SPDX elements.
186
187
```python { .api }
188
class Annotation:
189
"""
190
Annotation on SPDX elements.
191
192
Represents comments, reviews, or other annotations
193
on SPDX elements.
194
"""
195
spdx_id: str # Annotated element SPDX ID
196
annotation_type: AnnotationType # Annotation type
197
annotator: Actor # Who made the annotation
198
annotation_date: datetime # Annotation timestamp
199
annotation_comment: str # Annotation text
200
```
201
202
### Supporting Types
203
204
Actor information and other supporting data types.
205
206
```python { .api }
207
class Actor:
208
"""
209
Actor (person, organization, or tool) information.
210
211
Represents an entity that can create SPDX documents
212
or be involved in package/file creation.
213
"""
214
actor_type: ActorType # Type of actor
215
name: str # Actor name
216
email: Optional[str] = None # Actor email
217
218
class Checksum:
219
"""
220
Cryptographic checksum information.
221
222
Represents file or package integrity checksums
223
using various algorithms.
224
"""
225
algorithm: ChecksumAlgorithm # Checksum algorithm
226
value: str # Checksum value
227
228
class ExternalDocumentRef:
229
"""
230
Reference to external SPDX document.
231
232
Represents a reference to another SPDX document
233
with verification checksum.
234
"""
235
document_ref_id: str # Reference identifier
236
document_uri: str # Document URI
237
checksum: Checksum # Document checksum
238
239
class Version:
240
"""
241
Version information for SPDX specifications.
242
243
Represents version numbers in semantic versioning format.
244
"""
245
major: int # Major version
246
minor: int # Minor version
247
micro: int # Micro version
248
249
class SpdxNoAssertion:
250
"""Represents 'no assertion' value in SPDX."""
251
pass
252
253
class SpdxNone:
254
"""Represents 'none' value in SPDX."""
255
pass
256
```
257
258
## Enumerations
259
260
### Core Enums
261
262
```python { .api }
263
class ActorType(Enum):
264
"""Types of actors/creators."""
265
PERSON = "Person"
266
ORGANIZATION = "Organization"
267
TOOL = "Tool"
268
269
class AnnotationType(Enum):
270
"""Types of annotations."""
271
REVIEW = "REVIEW"
272
OTHER = "OTHER"
273
274
class ChecksumAlgorithm(Enum):
275
"""Supported checksum algorithms."""
276
SHA1 = "SHA1"
277
SHA224 = "SHA224"
278
SHA256 = "SHA256"
279
SHA384 = "SHA384"
280
SHA512 = "SHA512"
281
MD2 = "MD2"
282
MD4 = "MD4"
283
MD5 = "MD5"
284
MD6 = "MD6"
285
SHA3_256 = "SHA3-256"
286
SHA3_384 = "SHA3-384"
287
SHA3_512 = "SHA3-512"
288
BLAKE2B_256 = "BLAKE2b-256"
289
BLAKE2B_384 = "BLAKE2b-384"
290
BLAKE2B_512 = "BLAKE2b-512"
291
BLAKE3 = "BLAKE3"
292
ADLER32 = "ADLER32"
293
294
class FileType(Enum):
295
"""Types of files."""
296
SOURCE = "SOURCE"
297
BINARY = "BINARY"
298
ARCHIVE = "ARCHIVE"
299
APPLICATION = "APPLICATION"
300
AUDIO = "AUDIO"
301
IMAGE = "IMAGE"
302
TEXT = "TEXT"
303
VIDEO = "VIDEO"
304
DOCUMENTATION = "DOCUMENTATION"
305
SPDX = "SPDX"
306
OTHER = "OTHER"
307
308
class PackagePurpose(Enum):
309
"""Primary purposes of packages."""
310
APPLICATION = "APPLICATION"
311
FRAMEWORK = "FRAMEWORK"
312
LIBRARY = "LIBRARY"
313
CONTAINER = "CONTAINER"
314
OPERATING_SYSTEM = "OPERATING-SYSTEM"
315
DEVICE = "DEVICE"
316
FIRMWARE = "FIRMWARE"
317
SOURCE = "SOURCE"
318
ARCHIVE = "ARCHIVE"
319
FILE = "FILE"
320
INSTALL = "INSTALL"
321
OTHER = "OTHER"
322
323
class ExternalPackageRefCategory(Enum):
324
"""Categories of external package references."""
325
SECURITY = "SECURITY"
326
PACKAGE_MANAGER = "PACKAGE-MANAGER"
327
PERSISTENT_ID = "PERSISTENT-ID"
328
OTHER = "OTHER"
329
```
330
331
### Relationship Types
332
333
```python { .api }
334
class RelationshipType(Enum):
335
"""Types of relationships between SPDX elements."""
336
# Core relationships
337
DESCRIBES = "DESCRIBES"
338
DESCRIBED_BY = "DESCRIBED_BY"
339
CONTAINS = "CONTAINS"
340
CONTAINED_BY = "CONTAINED_BY"
341
342
# Dependency relationships
343
DEPENDS_ON = "DEPENDS_ON"
344
DEPENDENCY_OF = "DEPENDENCY_OF"
345
BUILD_DEPENDENCY_OF = "BUILD_DEPENDENCY_OF"
346
DEV_DEPENDENCY_OF = "DEV_DEPENDENCY_OF"
347
OPTIONAL_DEPENDENCY_OF = "OPTIONAL_DEPENDENCY_OF"
348
PROVIDED_DEPENDENCY_OF = "PROVIDED_DEPENDENCY_OF"
349
TEST_DEPENDENCY_OF = "TEST_DEPENDENCY_OF"
350
RUNTIME_DEPENDENCY_OF = "RUNTIME_DEPENDENCY_OF"
351
352
# Generation relationships
353
EXAMPLE_OF = "EXAMPLE_OF"
354
GENERATES = "GENERATES"
355
GENERATED_FROM = "GENERATED_FROM"
356
357
# Hierarchical relationships
358
ANCESTOR_OF = "ANCESTOR_OF"
359
DESCENDANT_OF = "DESCENDANT_OF"
360
VARIANT_OF = "VARIANT_OF"
361
362
# Distribution relationships
363
DISTRIBUTION_ARTIFACT = "DISTRIBUTION_ARTIFACT"
364
PATCH_FOR = "PATCH_FOR"
365
PATCH_APPLIED = "PATCH_APPLIED"
366
COPY_OF = "COPY_OF"
367
368
# File relationships
369
FILE_ADDED = "FILE_ADDED"
370
FILE_DELETED = "FILE_DELETED"
371
FILE_MODIFIED = "FILE_MODIFIED"
372
EXPANDED_FROM_ARCHIVE = "EXPANDED_FROM_ARCHIVE"
373
374
# Linking relationships
375
DYNAMIC_LINK = "DYNAMIC_LINK"
376
STATIC_LINK = "STATIC_LINK"
377
378
# Metadata relationships
379
DATA_FILE_OF = "DATA_FILE_OF"
380
TEST_CASE_OF = "TEST_CASE_OF"
381
BUILD_TOOL_OF = "BUILD_TOOL_OF"
382
DEV_TOOL_OF = "DEV_TOOL_OF"
383
TEST_OF = "TEST_OF"
384
TEST_TOOL_OF = "TEST_TOOL_OF"
385
METAFILE_OF = "METAFILE_OF"
386
PACKAGE_OF = "PACKAGE_OF"
387
388
# Amendment relationships
389
AMENDS = "AMENDS"
390
PREREQUISITE_FOR = "PREREQUISITE_FOR"
391
HAS_PREREQUISITE = "HAS_PREREQUISITE"
392
REQUIREMENT_DESCRIPTION_FOR = "REQUIREMENT_DESCRIPTION_FOR"
393
SPECIFICATION_FOR = "SPECIFICATION_FOR"
394
395
# Generic
396
OTHER = "OTHER"
397
```
398
399
## Usage Examples
400
401
### Creating Documents
402
403
```python
404
from datetime import datetime
405
from spdx_tools.spdx.model import (
406
Document, CreationInfo, Package, File, Relationship, Actor, ActorType,
407
ChecksumAlgorithm, Checksum, RelationshipType
408
)
409
410
# Create document creation info
411
creation_info = CreationInfo(
412
spdx_version="SPDX-2.3",
413
spdx_id="SPDXRef-DOCUMENT",
414
name="Example Document",
415
document_namespace="https://example.com/spdx/example-doc",
416
creators=[Actor(ActorType.TOOL, name="spdx-tools")],
417
created=datetime.now()
418
)
419
420
# Create a package
421
package = Package(
422
spdx_id="SPDXRef-Package",
423
name="example-package",
424
download_location="https://github.com/example/package",
425
files_analyzed=True,
426
checksums=[Checksum(ChecksumAlgorithm.SHA256, "abc123...")]
427
)
428
429
# Create a file
430
file = File(
431
spdx_id="SPDXRef-File",
432
name="./src/main.py",
433
checksums=[Checksum(ChecksumAlgorithm.SHA1, "def456...")]
434
)
435
436
# Create relationship
437
relationship = Relationship(
438
spdx_element_id="SPDXRef-Package",
439
relationship_type=RelationshipType.CONTAINS,
440
related_spdx_element="SPDXRef-File"
441
)
442
443
# Create complete document
444
document = Document(
445
creation_info=creation_info,
446
packages=[package],
447
files=[file],
448
relationships=[relationship],
449
snippets=[],
450
extracted_licensing_infos=[],
451
annotations=[]
452
)
453
```
454
455
### Working with Models
456
457
```python
458
# Access document information
459
print(f"Document: {document.creation_info.name}")
460
print(f"Namespace: {document.creation_info.document_namespace}")
461
print(f"Created: {document.creation_info.created}")
462
463
# Iterate through packages
464
for package in document.packages:
465
print(f"Package: {package.name} ({package.spdx_id})")
466
print(f" Download: {package.download_location}")
467
if package.checksums:
468
for checksum in package.checksums:
469
print(f" Checksum: {checksum.algorithm.value} = {checksum.value}")
470
471
# Find relationships
472
for rel in document.relationships:
473
print(f"Relationship: {rel.spdx_element_id} {rel.relationship_type.value} {rel.related_spdx_element}")
474
```
475
476
### Model Validation
477
478
```python
479
from spdx_tools.spdx.validation.document_validator import validate_full_spdx_document
480
481
# Models are validated when used with validation functions
482
validation_messages = validate_full_spdx_document(document)
483
if validation_messages:
484
print("Model validation errors:")
485
for msg in validation_messages:
486
print(f" - {msg.validation_message}")
487
```