{"id":7580,"library":"pyld","title":"pyld (JSON-LD API for Python)","description":"PyLD is a Python implementation of a JSON-LD processor, providing tools for working with Linked Data in JSON. It offers core JSON-LD operations such as compaction, expansion, flattening, and framing, adhering to the JSON-LD 1.1 specification. The library is actively maintained, with its current version 3.0.0 released in February 2024. While there isn't a fixed public release cadence, the project shows ongoing development and significant updates.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/digitalbazaar/pyld","tags":["json-ld","linked-data","semantic-web","rdf","json"],"install":[{"cmd":"pip install pyld","lang":"bash","label":"Basic installation"},{"cmd":"pip install pyld[requests]","lang":"bash","label":"With Requests for HTTP document loading"},{"cmd":"pip install pyld[aiohttp]","lang":"bash","label":"With aiohttp for asynchronous HTTP document loading"}],"dependencies":[{"reason":"PyLD 3.x requires Python 3.10 or later.","package":"python","optional":false},{"reason":"Required for the default synchronous document loader if fetching remote contexts/documents.","package":"requests","optional":true},{"reason":"Required for the asynchronous document loader if fetching remote contexts/documents.","package":"aiohttp","optional":true}],"imports":[{"symbol":"jsonld","correct":"from pyld import jsonld"}],"quickstart":{"code":"import json\nfrom pyld import jsonld\n\ndoc = {\n    \"http://schema.org/name\": \"Manu Sporny\",\n    \"http://schema.org/url\": {\"@id\": \"http://manu.sporny.org/\"},\n    \"http://schema.org/image\": {\"@id\": \"http://manu.sporny.org/images/manu.png\"}\n}\n\ncontext = {\n    \"name\": \"http://schema.org/name\",\n    \"homepage\": {\"@id\": \"http://schema.org/url\", \"@type\": \"@id\"},\n    \"image\": {\"@id\": \"http://schema.org/image\", \"@type\": \"@id\"}\n}\n\n# Compact a document according to a particular context\ncompacted = jsonld.compact(doc, context)\nprint(\"Compacted document:\")\nprint(json.dumps(compacted, indent=2))\n\n# Expand a document, removing its context\nexpanded = jsonld.expand(compacted)\nprint(\"\\nExpanded document:\")\nprint(json.dumps(expanded, indent=2))\n\n# Flatten a document\nflattened = jsonld.flatten(doc)\nprint(\"\\nFlattened document:\")\nprint(json.dumps(flattened, indent=2))","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your Python environment is version 3.10 or newer. Upgrade Python if necessary.","message":"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.","severity":"breaking","affected_versions":"3.0.0 and later"},{"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`.","message":"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`.","severity":"breaking","affected_versions":"3.0.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `requests` explicitly using `pip install requests` or `pip install pyld[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.","error":"ModuleNotFoundError: No module named 'requests'"},{"fix":"Upgrade your Python environment to version 3.10 or higher.","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.","error":"SyntaxError: 'return' outside function (or similar Python version incompatibility errors)"},{"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.","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.","error":"jsonld.compact() (or expand, frame) produces unexpected output (e.g., @context not applied, terms not shortened)"}]}