Core JSON-LD Processing

def compact(input_, ctx, options=None):
    """
    Performs JSON-LD compaction.
    
    Args:
        input_: The JSON-LD document to compact (dict, list, or str)
        ctx: The JSON-LD context to compact with (dict or str)
        options: Optional compaction settings (dict)
    
    Options:
        base (str): The base IRI to use
        compactArrays (bool): True to compact arrays to single values when 
                             appropriate (default: True)
        graph (bool): True to always output a top-level graph (default: False)
        skipExpansion (bool): True to skip expansion during compaction
        documentLoader (function): Custom document loader function
        expandContext (dict): Context to use during expansion
        processingMode (str): JSON-LD processing mode
        
    Returns:
        dict: The compacted JSON-LD document
        
    Raises:
        JsonLdError: If compaction fails due to invalid input or context
    """

from pyld import jsonld

doc = {
    "http://schema.org/name": "Jane Doe",
    "http://schema.org/jobTitle": "Software Engineer"
}

context = {
    "name": "http://schema.org/name",
    "jobTitle": "http://schema.org/jobTitle"
}

compacted = jsonld.compact(doc, context)
# Result: {"@context": {...}, "name": "Jane Doe", "jobTitle": "Software Engineer"}

def expand(input_, options=None):
    """
    Performs JSON-LD expansion.
    
    Args:
        input_: The JSON-LD document to expand (dict, list, or str)
        options: Optional expansion settings (dict)
    
    Options:
        base (str): The base IRI to use
        expandContext (dict): Context to use during expansion
        extractAllScripts (bool): True to extract all JSON-LD script elements
                                 from HTML (default: False)
        documentLoader (function): Custom document loader function
        processingMode (str): JSON-LD processing mode
        
    Returns:
        list: The expanded JSON-LD document as an array
        
    Raises:
        JsonLdError: If expansion fails due to invalid input
    """

from pyld import jsonld

doc = {
    "@context": {"name": "http://schema.org/name"},
    "name": "John Smith"
}

expanded = jsonld.expand(doc)
# Result: [{"http://schema.org/name": [{"@value": "John Smith"}]}]

def flatten(input_, ctx=None, options=None):
    """
    Performs JSON-LD flattening.
    
    Args:
        input_: The JSON-LD document to flatten (dict, list, or str)
        ctx: Optional context to apply to flattened document (dict or str)
        options: Optional flattening settings (dict)
    
    Options:
        base (str): The base IRI to use
        expandContext (dict): Context to use during expansion
        extractAllScripts (bool): True to extract all JSON-LD script elements
                                 from HTML (default: False)
        documentLoader (function): Custom document loader function
        processingMode (str): JSON-LD processing mode
        
    Returns:
        dict: The flattened JSON-LD document
        
    Raises:
        JsonLdError: If flattening fails due to invalid input
    """

from pyld import jsonld

doc = {
    "@context": {"name": "http://schema.org/name"},
    "name": "Alice",
    "knows": {
        "name": "Bob"
    }
}

flattened = jsonld.flatten(doc)
# Result: Flat structure with separate nodes and @id references

def frame(input_, frame, options=None):
    """
    Performs JSON-LD framing.
    
    Args:
        input_: The JSON-LD document to frame (dict, list, or str)
        frame: The JSON-LD frame template (dict)
        options: Optional framing settings (dict)
    
    Options:
        base (str): The base IRI to use
        expandContext (dict): Context to use during expansion
        extractAllScripts (bool): True to extract all JSON-LD script elements
                                 from HTML (default: False)
        documentLoader (function): Custom document loader function
        embed (str): How to embed matched objects ('@always', '@once', '@never')
        explicit (bool): True to only include explicitly framed properties
        omitDefault (bool): True to omit default values
        pruneBlankNodeIdentifiers (bool): True to prune blank node identifiers
        requireAll (bool): True to require all frame properties to match
        
    Returns:
        dict: The framed JSON-LD document
        
    Raises:
        JsonLdError: If framing fails due to invalid input or frame
    """

from pyld import jsonld

doc = [
    {"@id": "http://example.org/person/1", "@type": "Person", "name": "Alice"},
    {"@id": "http://example.org/person/2", "@type": "Person", "name": "Bob"}
]

frame = {
    "@context": {"name": "http://schema.org/name"},
    "@type": "Person",
    "name": {}
}

framed = jsonld.frame(doc, frame)
# Result: Document reshaped according to frame structure

def normalize(input_, options=None):
    """
    Performs RDF dataset normalization on JSON-LD input.
    
    Args:
        input_: The JSON-LD document to normalize (dict, list, or str)
        options: Optional normalization settings (dict)
    
    Options:
        algorithm (str): Normalization algorithm ('URDNA2015' or 'URGNA2012', 
                        default: 'URGNA2012')
        base (str): The base IRI to use
        expandContext (dict): Context to use during expansion
        format (str): Output format ('application/n-quads' for string output)
        inputFormat (str): Input format if not JSON-LD
        documentLoader (function): Custom document loader function
        
    Returns:
        str or dict: Normalized representation (string if format specified, 
                    otherwise RDF dataset dict)
        
    Raises:
        JsonLdError: If normalization fails due to invalid input
    """

from pyld import jsonld

doc = {
    "@context": {"name": "http://schema.org/name"},
    "name": "Charlie"
}

normalized = jsonld.normalize(doc, {
    'algorithm': 'URDNA2015',
    'format': 'application/n-quads'
})
# Result: Canonical N-Quads string representation

def link(input_, ctx=None, options=None):
    """
    Links a JSON-LD document's nodes in memory (EXPERIMENTAL).
    
    This experimental function creates bidirectional links between JSON-LD 
    objects that reference each other, enabling in-memory graph traversal.
    
    Args:
        input_: The JSON-LD document to link (dict, list, or str)
        ctx: Optional context to apply during linking (dict or str)
        options: Optional linking settings (dict)
        
    Options:
        base (str): The base IRI to use
        expandContext (dict): Context to use during expansion
        
    Returns:
        dict: The linked JSON-LD document with bidirectional references
        
    Raises:
        JsonLdError: If linking fails due to invalid input
        
    Note:
        This is an experimental feature and may change in future versions.
    """