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