or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-processing.mddocument-loading.mdindex.mdjson-canonicalization.mdrdf-conversion.mdurl-utilities.md
tile.json

tessl/pypi-pyld

Python implementation of the JSON-LD API for processing Linked Data in JSON format

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pyld@2.0.x

To install, run

npx @tessl/cli install tessl/pypi-pyld@2.0.0

index.mddocs/

PyLD

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.

Package Information

  • Package Name: PyLD
  • Language: Python
  • Installation: pip install PyLD
  • Optional Dependencies: pip install PyLD[requests] or pip install PyLD[aiohttp]

Core Imports

from pyld import jsonld

For context resolution:

from pyld import ContextResolver

For JSON canonicalization:

from c14n import canonicalize

Basic Usage

from pyld import jsonld
import json

# Sample JSON-LD document
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"}
}

# Define a context for compaction
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(json.dumps(compacted, indent=2))

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

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

# Normalize a document using RDF Dataset Normalization Algorithm
normalized = jsonld.normalize(doc, {
    'algorithm': 'URDNA2015', 
    'format': 'application/n-quads'
})

Architecture

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

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

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

Capabilities

Core JSON-LD Processing

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

def compact(input_, ctx, options=None):
    """
    Performs JSON-LD compaction.
    
    Args:
        input_: The JSON-LD document to compact
        ctx: The context to use for compaction  
        options: Optional compaction options
        
    Returns:
        dict: The compacted JSON-LD document
    """

def expand(input_, options=None):
    """
    Performs JSON-LD expansion.
    
    Args:
        input_: The JSON-LD document to expand
        options: Optional expansion options
        
    Returns:
        list: The expanded JSON-LD document
    """

def flatten(input_, ctx=None, options=None):
    """
    Performs JSON-LD flattening.
    
    Args:
        input_: The JSON-LD document to flatten
        ctx: Optional context for the flattened document
        options: Optional flattening options
        
    Returns:
        dict: The flattened JSON-LD document
    """

def frame(input_, frame, options=None):
    """
    Performs JSON-LD framing.
    
    Args:
        input_: The JSON-LD document to frame
        frame: The frame to use
        options: Optional framing options
        
    Returns:
        dict: The framed JSON-LD document
    """

def normalize(input_, options=None):
    """
    Normalizes a JSON-LD document using RDF Dataset Normalization.
    
    Args:
        input_: The JSON-LD document to normalize
        options: Normalization options (algorithm, format)
        
    Returns:
        str: The normalized representation
    """

def link(input_, ctx, options=None):
    """
    **Experimental**
    
    Links a JSON-LD document's nodes in memory.
    
    Args:
        input_: The JSON-LD document to link
        ctx: The JSON-LD context to apply or None
        options: Optional linking options
        
    Returns:
        dict: The linked JSON-LD output
    """

Core Processing

RDF Conversion

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

def to_rdf(input_, options=None):
    """
    Converts JSON-LD document to RDF dataset.
    
    Args:
        input_: The JSON-LD document to convert
        options: Conversion options
        
    Returns:
        dict: RDF dataset representation
    """

def from_rdf(input_, options=None):
    """
    Converts RDF dataset to JSON-LD document.
    
    Args:
        input_: The RDF dataset to convert
        options: Conversion options
        
    Returns:
        list: JSON-LD document representation
    """

RDF Conversion

Document Loading

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

def set_document_loader(loader):
    """
    Sets the global document loader.
    
    Args:
        loader: Document loader function
    """

def get_document_loader():
    """
    Gets the current document loader.
    
    Returns:
        function: Current document loader function
    """

def requests_document_loader(**kwargs):
    """
    Creates a requests-based document loader.
    
    Args:
        **kwargs: Options passed to requests (timeout, verify, etc.)
        
    Returns:
        function: Document loader function
    """

def aiohttp_document_loader(**kwargs):
    """
    Creates an aiohttp-based document loader.
    
    Args:
        **kwargs: Options passed to aiohttp (timeout, connector, etc.)
        
    Returns:
        function: Async document loader function
    """

Document Loading

URL and IRI Utilities

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

def prepend_base(base, iri):
    """
    Prepends a base IRI to a relative IRI.
    
    Args:
        base: The base IRI
        iri: The relative IRI
        
    Returns:
        str: The absolute IRI
    """

def remove_base(base, iri):
    """
    Removes a base IRI from an absolute IRI.
    
    Args:
        base: The base IRI
        iri: The absolute IRI
        
    Returns:
        str: The relative IRI
    """

def parse_url(url):
    """
    Parses a URL into its components.
    
    Args:
        url: The URL to parse
        
    Returns:
        dict: URL components (scheme, authority, path, query, fragment)
    """

def unparse_url(parsed):
    """
    Reconstructs a URL from its parsed components.
    
    Args:
        parsed: Parsed URL components (dict, list, tuple, or ParsedUrl object)
        
    Returns:
        str: The reconstructed URL
    """

def remove_dot_segments(path):
    """
    Removes dot segments from a URL path according to RFC 3986.
    
    Args:
        path (str): The path to normalize
        
    Returns:
        str: Path with normalized dot segments
    """

URL Utilities

JSON Canonicalization

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

def canonicalize(obj):
    """
    Canonicalizes a JSON object according to RFC 8785.
    
    Args:
        obj: The JSON object to canonicalize
        
    Returns:
        str: Canonical JSON string representation
    """

JSON Canonicalization

RDF Parser Management

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

def register_rdf_parser(content_type, parser):
    """
    Registers a global RDF parser by content-type for use with from_rdf.
    
    Args:
        content_type (str): The content-type for the parser
        parser (function): Parser function that takes a string and returns RDF dataset
    """

def unregister_rdf_parser(content_type):
    """
    Unregisters a global RDF parser by content-type.
    
    Args:
        content_type (str): The content-type to unregister
    """

Core Classes

JsonLdError

Base exception class for all JSON-LD processing errors.

class JsonLdError(Exception):
    """Base exception for JSON-LD errors."""
    
    def __init__(self, msg, error_type=None, details=None, code=None, cause=None):
        """
        Initialize JsonLdError.
        
        Args:
            msg: Error message
            error_type: Type of error
            details: Additional error details
            code: Error code
            cause: Underlying cause exception
        """

JsonLdProcessor

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

class JsonLdProcessor:
    """
    A JSON-LD processor with customizable RDF parsers.
    
    Provides the same processing methods as the module-level functions
    but allows for processor-specific RDF parser registration.
    """
    
    def __init__(self):
        """Initialize the JSON-LD processor."""
    
    def compact(self, input_, ctx, options):
        """Performs JSON-LD compaction (same as module-level compact)."""
    
    def expand(self, input_, options):
        """Performs JSON-LD expansion (same as module-level expand)."""
    
    def flatten(self, input_, ctx, options):
        """Performs JSON-LD flattening (same as module-level flatten)."""
    
    def frame(self, input_, frame, options):
        """Performs JSON-LD framing (same as module-level frame)."""
    
    def normalize(self, input_, options):
        """Performs RDF dataset normalization (same as module-level normalize)."""
    
    def from_rdf(self, dataset, options):
        """Converts RDF dataset to JSON-LD (same as module-level from_rdf)."""
    
    def to_rdf(self, input_, options):
        """Outputs RDF dataset from JSON-LD (same as module-level to_rdf)."""

ContextResolver

Manages resolution and caching of JSON-LD contexts.

class ContextResolver:
    """Resolves and caches JSON-LD contexts."""
    
    def resolve(self, active_ctx, context, base, cycles=None):
        """
        Resolve a context.
        
        Args:
            active_ctx: The active context
            context: The context to resolve
            base: The base IRI
            cycles: Context resolution cycle detection
            
        Returns:
            ResolvedContext: The resolved context
        """

Normalization Algorithm Classes

Classes that implement RDF dataset normalization algorithms.

class URDNA2015:
    """
    Implements the URDNA2015 RDF Dataset Normalization Algorithm.
    
    The recommended normalization algorithm providing deterministic 
    canonical ordering of RDF datasets.
    """

class URGNA2012(URDNA2015):
    """
    Implements the URGNA2012 RDF Graph Normalization Algorithm.
    
    Legacy normalization algorithm, inherits from URDNA2015.
    URDNA2015 is recommended for new applications.
    """

class IdentifierIssuer:
    """
    Issues unique identifiers for blank nodes during normalization.
    
    Keeps track of previously issued identifiers to ensure uniqueness
    and consistency during the normalization process.
    """

Constants

JSON-LD Keywords

KEYWORDS = [
    '@base', '@container', '@context', '@default', '@direction',
    '@embed', '@explicit', '@first', '@graph', '@id', '@import',
    '@included', '@index', '@json', '@language', '@list', '@nest',
    '@none', '@omitDefault', '@propagate', '@protected', '@preserve',
    '@requireAll', '@reverse', '@set', '@type', '@value', '@version', '@vocab'
]

XML Schema Types

XSD_BOOLEAN = 'http://www.w3.org/2001/XMLSchema#boolean'
XSD_DOUBLE = 'http://www.w3.org/2001/XMLSchema#double'  
XSD_INTEGER = 'http://www.w3.org/2001/XMLSchema#integer'
XSD_STRING = 'http://www.w3.org/2001/XMLSchema#string'

RDF Vocabulary

RDF = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'
RDF_LIST = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#List'
RDF_FIRST = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#first'
RDF_REST = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#rest'
RDF_NIL = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#nil'
RDF_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type'
RDF_LANGSTRING = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#langString'
RDF_JSON_LITERAL = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#JSON'

Other Constants

JSON_LD_NS = 'http://www.w3.org/ns/json-ld#'
LINK_HEADER_REL = 'http://www.w3.org/ns/json-ld#context'
MAX_CONTEXT_URLS = 10

Utility Functions

Data Freezing

Utility for creating immutable copies of data structures.

def freeze(value):
    """
    Creates an immutable (frozen) copy of a value.
    
    Args:
        value: The value to freeze (dict, list, or primitive)
        
    Returns:
        Immutable version of the value (frozendict for dicts, original for others)
    """

Package Metadata

__version__ = '2.0.5-dev'
__copyright__ = 'Copyright (c) 2011-2024 Digital Bazaar, Inc.'
__license__ = 'New BSD license'