0
# PyLD
1

2
Python implementation of the JSON-LD API for processing Linked Data in JSON format. PyLD enables developers to work with semantic web technologies by providing comprehensive tools to expand, compact, flatten, frame, and normalize JSON-LD documents according to W3C standards.
3

4
## Package Information
5

6
- **Package Name**: PyLD
7
- **Language**: Python
8
- **Installation**: `pip install PyLD`
9
- **Optional Dependencies**: `pip install PyLD[requests]` or `pip install PyLD[aiohttp]`
10

11
## Core Imports
12

13
```python
14
from pyld import jsonld
15
```
16

17
For context resolution:
18

19
```python
20
from pyld import ContextResolver
21
```
22

23
For JSON canonicalization:
24

25
```python
26
from c14n import canonicalize
27
```
28

29
## Basic Usage
30

31
```python
32
from pyld import jsonld
33
import json
34

35
# Sample JSON-LD document
36
doc = {
37
    "http://schema.org/name": "Manu Sporny",
38
    "http://schema.org/url": {"@id": "http://manu.sporny.org/"},
39
    "http://schema.org/image": {"@id": "http://manu.sporny.org/images/manu.png"}
40
}
41

42
# Define a context for compaction
43
context = {
44
    "name": "http://schema.org/name",
45
    "homepage": {"@id": "http://schema.org/url", "@type": "@id"},
46
    "image": {"@id": "http://schema.org/image", "@type": "@id"}
47
}
48

49
# Compact a document according to a particular context
50
compacted = jsonld.compact(doc, context)
51
print(json.dumps(compacted, indent=2))
52

53
# Expand a document, removing its context
54
expanded = jsonld.expand(compacted)
55
print(json.dumps(expanded, indent=2))
56

57
# Flatten a document to a single-level structure
58
flattened = jsonld.flatten(doc)
59

60
# Normalize a document using RDF Dataset Normalization Algorithm
61
normalized = jsonld.normalize(doc, {
62
    'algorithm': 'URDNA2015', 
63
    'format': 'application/n-quads'
64
})
65
```
66

67
## Architecture
68

69
PyLD provides a comprehensive JSON-LD processing pipeline with these key components:
70

71
- **JsonLdProcessor**: Core processing engine that handles all JSON-LD transformations
72
- **ContextResolver**: Manages and caches remote contexts for efficient processing
73
- **Document Loaders**: Pluggable HTTP clients (requests, aiohttp) for fetching remote documents
74
- **Normalization Algorithms**: URDNA2015 and URGNA2012 implementations for canonical RDF representation
75

76
The library is designed for maximum compatibility with existing JSON workflows while adding semantic meaning through linked data principles.
77

78
## Capabilities
79

80
### Core JSON-LD Processing
81

82
Primary JSON-LD transformation operations including compaction, expansion, flattening, framing, and RDF conversion. These functions form the foundation of JSON-LD document processing.
83

84
```python { .api }
85
def compact(input_, ctx, options=None):
86
    """
87
    Performs JSON-LD compaction.
88
    
89
    Args:
90
        input_: The JSON-LD document to compact
91
        ctx: The context to use for compaction  
92
        options: Optional compaction options
93
        
94
    Returns:
95
        dict: The compacted JSON-LD document
96
    """
97

98
def expand(input_, options=None):
99
    """
100
    Performs JSON-LD expansion.
101
    
102
    Args:
103
        input_: The JSON-LD document to expand
104
        options: Optional expansion options
105
        
106
    Returns:
107
        list: The expanded JSON-LD document
108
    """
109

110
def flatten(input_, ctx=None, options=None):
111
    """
112
    Performs JSON-LD flattening.
113
    
114
    Args:
115
        input_: The JSON-LD document to flatten
116
        ctx: Optional context for the flattened document
117
        options: Optional flattening options
118
        
119
    Returns:
120
        dict: The flattened JSON-LD document
121
    """
122

123
def frame(input_, frame, options=None):
124
    """
125
    Performs JSON-LD framing.
126
    
127
    Args:
128
        input_: The JSON-LD document to frame
129
        frame: The frame to use
130
        options: Optional framing options
131
        
132
    Returns:
133
        dict: The framed JSON-LD document
134
    """
135

136
def normalize(input_, options=None):
137
    """
138
    Normalizes a JSON-LD document using RDF Dataset Normalization.
139
    
140
    Args:
141
        input_: The JSON-LD document to normalize
142
        options: Normalization options (algorithm, format)
143
        
144
    Returns:
145
        str: The normalized representation
146
    """
147

148
def link(input_, ctx, options=None):
149
    """
150
    **Experimental**
151
    
152
    Links a JSON-LD document's nodes in memory.
153
    
154
    Args:
155
        input_: The JSON-LD document to link
156
        ctx: The JSON-LD context to apply or None
157
        options: Optional linking options
158
        
159
    Returns:
160
        dict: The linked JSON-LD output
161
    """
162
```
163

164
[Core Processing](./core-processing.md)
165

166
### RDF Conversion
167

168
Conversion between JSON-LD and RDF dataset formats, enabling interoperability with RDF triple stores and semantic web applications.
169

170
```python { .api }
171
def to_rdf(input_, options=None):
172
    """
173
    Converts JSON-LD document to RDF dataset.
174
    
175
    Args:
176
        input_: The JSON-LD document to convert
177
        options: Conversion options
178
        
179
    Returns:
180
        dict: RDF dataset representation
181
    """
182

183
def from_rdf(input_, options=None):
184
    """
185
    Converts RDF dataset to JSON-LD document.
186
    
187
    Args:
188
        input_: The RDF dataset to convert
189
        options: Conversion options
190
        
191
    Returns:
192
        list: JSON-LD document representation
193
    """
194
```
195

196
[RDF Conversion](./rdf-conversion.md)
197

198
### Document Loading
199

200
Configurable document loaders for fetching remote contexts and documents via HTTP, supporting both synchronous (requests) and asynchronous (aiohttp) operations.
201

202
```python { .api }
203
def set_document_loader(loader):
204
    """
205
    Sets the global document loader.
206
    
207
    Args:
208
        loader: Document loader function
209
    """
210

211
def get_document_loader():
212
    """
213
    Gets the current document loader.
214
    
215
    Returns:
216
        function: Current document loader function
217
    """
218

219
def requests_document_loader(**kwargs):
220
    """
221
    Creates a requests-based document loader.
222
    
223
    Args:
224
        **kwargs: Options passed to requests (timeout, verify, etc.)
225
        
226
    Returns:
227
        function: Document loader function
228
    """
229

230
def aiohttp_document_loader(**kwargs):
231
    """
232
    Creates an aiohttp-based document loader.
233
    
234
    Args:
235
        **kwargs: Options passed to aiohttp (timeout, connector, etc.)
236
        
237
    Returns:
238
        function: Async document loader function
239
    """
240
```
241

242
[Document Loading](./document-loading.md)
243

244
### URL and IRI Utilities
245

246
Utility functions for URL parsing, IRI manipulation, and base URL resolution following RFC 3986 standards.
247

248
```python { .api }
249
def prepend_base(base, iri):
250
    """
251
    Prepends a base IRI to a relative IRI.
252
    
253
    Args:
254
        base: The base IRI
255
        iri: The relative IRI
256
        
257
    Returns:
258
        str: The absolute IRI
259
    """
260

261
def remove_base(base, iri):
262
    """
263
    Removes a base IRI from an absolute IRI.
264
    
265
    Args:
266
        base: The base IRI
267
        iri: The absolute IRI
268
        
269
    Returns:
270
        str: The relative IRI
271
    """
272

273
def parse_url(url):
274
    """
275
    Parses a URL into its components.
276
    
277
    Args:
278
        url: The URL to parse
279
        
280
    Returns:
281
        dict: URL components (scheme, authority, path, query, fragment)
282
    """
283

284
def unparse_url(parsed):
285
    """
286
    Reconstructs a URL from its parsed components.
287
    
288
    Args:
289
        parsed: Parsed URL components (dict, list, tuple, or ParsedUrl object)
290
        
291
    Returns:
292
        str: The reconstructed URL
293
    """
294

295
def remove_dot_segments(path):
296
    """
297
    Removes dot segments from a URL path according to RFC 3986.
298
    
299
    Args:
300
        path (str): The path to normalize
301
        
302
    Returns:
303
        str: Path with normalized dot segments
304
    """
305
```
306

307
[URL Utilities](./url-utilities.md)
308

309
### JSON Canonicalization
310

311
RFC 8785 compliant JSON canonicalization for consistent JSON serialization and hashing.
312

313
```python { .api }
314
def canonicalize(obj):
315
    """
316
    Canonicalizes a JSON object according to RFC 8785.
317
    
318
    Args:
319
        obj: The JSON object to canonicalize
320
        
321
    Returns:
322
        str: Canonical JSON string representation
323
    """
324
```
325

326
[JSON Canonicalization](./json-canonicalization.md)
327

328
### RDF Parser Management
329

330
Registration and management of custom RDF parsers for handling different RDF formats in `from_rdf()` operations.
331

332
```python { .api }
333
def register_rdf_parser(content_type, parser):
334
    """
335
    Registers a global RDF parser by content-type for use with from_rdf.
336
    
337
    Args:
338
        content_type (str): The content-type for the parser
339
        parser (function): Parser function that takes a string and returns RDF dataset
340
    """
341

342
def unregister_rdf_parser(content_type):
343
    """
344
    Unregisters a global RDF parser by content-type.
345
    
346
    Args:
347
        content_type (str): The content-type to unregister
348
    """
349
```
350

351
## Core Classes
352

353
### JsonLdError
354

355
Base exception class for all JSON-LD processing errors.
356

357
```python { .api }
358
class JsonLdError(Exception):
359
    """Base exception for JSON-LD errors."""
360
    
361
    def __init__(self, msg, error_type=None, details=None, code=None, cause=None):
362
        """
363
        Initialize JsonLdError.
364
        
365
        Args:
366
            msg: Error message
367
            error_type: Type of error
368
            details: Additional error details
369
            code: Error code
370
            cause: Underlying cause exception
371
        """
372
```
373

374
### JsonLdProcessor
375

376
Main processor class that provides instance-based JSON-LD processing with custom RDF parser support.
377

378
```python { .api }
379
class JsonLdProcessor:
380
    """
381
    A JSON-LD processor with customizable RDF parsers.
382
    
383
    Provides the same processing methods as the module-level functions
384
    but allows for processor-specific RDF parser registration.
385
    """
386
    
387
    def __init__(self):
388
        """Initialize the JSON-LD processor."""
389
    
390
    def compact(self, input_, ctx, options):
391
        """Performs JSON-LD compaction (same as module-level compact)."""
392
    
393
    def expand(self, input_, options):
394
        """Performs JSON-LD expansion (same as module-level expand)."""
395
    
396
    def flatten(self, input_, ctx, options):
397
        """Performs JSON-LD flattening (same as module-level flatten)."""
398
    
399
    def frame(self, input_, frame, options):
400
        """Performs JSON-LD framing (same as module-level frame)."""
401
    
402
    def normalize(self, input_, options):
403
        """Performs RDF dataset normalization (same as module-level normalize)."""
404
    
405
    def from_rdf(self, dataset, options):
406
        """Converts RDF dataset to JSON-LD (same as module-level from_rdf)."""
407
    
408
    def to_rdf(self, input_, options):
409
        """Outputs RDF dataset from JSON-LD (same as module-level to_rdf)."""
410
```
411

412
### ContextResolver
413

414
Manages resolution and caching of JSON-LD contexts.
415

416
```python { .api }
417
class ContextResolver:
418
    """Resolves and caches JSON-LD contexts."""
419
    
420
    def resolve(self, active_ctx, context, base, cycles=None):
421
        """
422
        Resolve a context.
423
        
424
        Args:
425
            active_ctx: The active context
426
            context: The context to resolve
427
            base: The base IRI
428
            cycles: Context resolution cycle detection
429
            
430
        Returns:
431
            ResolvedContext: The resolved context
432
        """
433
```
434

435
### Normalization Algorithm Classes
436

437
Classes that implement RDF dataset normalization algorithms.
438

439
```python { .api }
440
class URDNA2015:
441
    """
442
    Implements the URDNA2015 RDF Dataset Normalization Algorithm.
443
    
444
    The recommended normalization algorithm providing deterministic 
445
    canonical ordering of RDF datasets.
446
    """
447

448
class URGNA2012(URDNA2015):
449
    """
450
    Implements the URGNA2012 RDF Graph Normalization Algorithm.
451
    
452
    Legacy normalization algorithm, inherits from URDNA2015.
453
    URDNA2015 is recommended for new applications.
454
    """
455

456
class IdentifierIssuer:
457
    """
458
    Issues unique identifiers for blank nodes during normalization.
459
    
460
    Keeps track of previously issued identifiers to ensure uniqueness
461
    and consistency during the normalization process.
462
    """
463
```
464

465
## Constants
466

467
### JSON-LD Keywords
468

469
```python { .api }
470
KEYWORDS = [
471
    '@base', '@container', '@context', '@default', '@direction',
472
    '@embed', '@explicit', '@first', '@graph', '@id', '@import',
473
    '@included', '@index', '@json', '@language', '@list', '@nest',
474
    '@none', '@omitDefault', '@propagate', '@protected', '@preserve',
475
    '@requireAll', '@reverse', '@set', '@type', '@value', '@version', '@vocab'
476
]
477
```
478

479
### XML Schema Types
480

481
```python { .api }
482
XSD_BOOLEAN = 'http://www.w3.org/2001/XMLSchema#boolean'
483
XSD_DOUBLE = 'http://www.w3.org/2001/XMLSchema#double'  
484
XSD_INTEGER = 'http://www.w3.org/2001/XMLSchema#integer'
485
XSD_STRING = 'http://www.w3.org/2001/XMLSchema#string'
486
```
487

488
### RDF Vocabulary
489

490
```python { .api }
491
RDF = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'
492
RDF_LIST = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#List'
493
RDF_FIRST = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#first'
494
RDF_REST = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#rest'
495
RDF_NIL = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#nil'
496
RDF_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type'
497
RDF_LANGSTRING = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#langString'
498
RDF_JSON_LITERAL = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#JSON'
499
```
500

501
### Other Constants
502

503
```python { .api }
504
JSON_LD_NS = 'http://www.w3.org/ns/json-ld#'
505
LINK_HEADER_REL = 'http://www.w3.org/ns/json-ld#context'
506
MAX_CONTEXT_URLS = 10
507
```
508

509
## Utility Functions
510

511
### Data Freezing
512

513
Utility for creating immutable copies of data structures.
514

515
```python { .api }
516
def freeze(value):
517
    """
518
    Creates an immutable (frozen) copy of a value.
519
    
520
    Args:
521
        value: The value to freeze (dict, list, or primitive)
522
        
523
    Returns:
524
        Immutable version of the value (frozendict for dicts, original for others)
525
    """
526
```
527

528
## Package Metadata
529

530
```python { .api }
531
__version__ = '2.0.5-dev'
532
__copyright__ = 'Copyright (c) 2011-2024 Digital Bazaar, Inc.'
533
__license__ = 'New BSD license'
534
```