pyld (JSON-LD API for Python)

Common errors

• ModuleNotFoundError: No module named 'requests'

  cause The default synchronous document loader in PyLD relies on the `requests` library, but `requests` is no longer a direct dependency of the `pyld` package as of version 3.0.0.
  fix Install `requests` explicitly using `pip install requests` or `pip install pyld[requests]`.

• SyntaxError: 'return' outside function (or similar Python version incompatibility errors)

  cause PyLD 3.x requires Python 3.10 or newer. Running it on an older Python version will lead to syntax or runtime errors due to incompatible language features.
  fix Upgrade your Python environment to version 3.10 or higher.

• jsonld.compact() (or expand, frame) produces unexpected output (e.g., @context not applied, terms not shortened)

  cause Misunderstanding of how JSON-LD contexts work, or an incorrect/incomplete context being provided to the PyLD processor functions. The JSON-LD specification defines complex algorithms for these operations.
  fix Consult the JSON-LD 1.1 specification (linked from PyLD's documentation) for detailed explanations of compaction, expansion, and framing algorithms. Experiment with simpler contexts and gradually build up to complex ones, verifying each step. Ensure your `@context` definitions are accurate and cover the terms in your document.

Warnings

• breaking PyLD 3.x has increased its Python version requirement. Version 2.x supported Python 3.6+, but 3.x explicitly requires Python 3.10 or later.
  Fix: Ensure your Python environment is version 3.10 or newer. Upgrade Python if necessary.
• breaking The `requests` library, previously a default dependency for remote document loading, is no longer automatically installed with `pip install pyld`. If you use PyLD's document loader for fetching remote JSON-LD, you must explicitly install `requests` or `aiohttp`.
  Fix: Install `pyld` with the `requests` or `aiohttp` extra: `pip install pyld[requests]` or `pip install pyld[aiohttp]`. Alternatively, install `requests` or `aiohttp` directly: `pip install requests`.
• gotcha PyLD uses its own native JSON-LD data structures, which can make direct interoperability with `rdflib` (a common Python RDF library) non-trivial without serialization/re-parsing. A compatibility layer (`rdflib_pyld_compat.py`) exists but is not part of `pyld` itself.
  Fix: If combining PyLD with `rdflib`, consider using the `rdflib_pyld_compat.py` utility or explicitly convert between data structures by serializing and then re-parsing (e.g., to N-Quads) if a direct bridge is not suitable.

Install

• pip install pyld Basic installation
• pip install pyld[requests] With Requests for HTTP document loading
• pip install pyld[aiohttp] With aiohttp for asynchronous HTTP document loading

Imports

• jsonld

  from pyld import jsonld

Quickstart

This quickstart demonstrates the core functionalities of `pyld` including `compact`, `expand`, and `flatten` operations using a sample JSON-LD document and context. It processes the document to show its compacted, expanded, and flattened forms.

import json
from pyld import jsonld

doc = {
    "http://schema.org/name": "Manu Sporny",
    "http://schema.org/url": {"@id": "http://manu.sporny.org/"},
    "http://schema.org/image": {"@id": "http://manu.sporny.org/images/manu.png"}
}

context = {
    "name": "http://schema.org/name",
    "homepage": {"@id": "http://schema.org/url", "@type": "@id"},
    "image": {"@id": "http://schema.org/image", "@type": "@id"}
}

# Compact a document according to a particular context
compacted = jsonld.compact(doc, context)
print("Compacted document:")
print(json.dumps(compacted, indent=2))

# Expand a document, removing its context
expanded = jsonld.expand(compacted)
print("\nExpanded document:")
print(json.dumps(expanded, indent=2))

# Flatten a document
flattened = jsonld.flatten(doc)
print("\nFlattened document:")
print(json.dumps(flattened, indent=2))