Python CBOR-LD Processor

A Python CBOR-LD processor for encoding and decoding JSON-LD documents.

Table of Contents

• Background
• Install
• Usage
• API
• Migrating from 0.1.x
• Contribute
• License

Background

This library provides a CBOR-LD 1.0 processor for Python applications, ported from @digitalbazaar/cborld.

CBOR-LD is a compact binary serialization of JSON-LD that uses semantic compression to achieve significantly better compression ratios than general-purpose algorithms.

Features

• Encode JSON-LD documents to compact CBOR-LD binary format
• Decode CBOR-LD bytes back to JSON-LD
• CBOR-LD 1.0 tag support (0xCB1D / 51997)
• Legacy format support (legacy-range, legacy-singleton)
• Built-in codecs: HTTP URLs, UUID URNs, DID URLs, data URLs, multibase, XSD dates/datetimes, cryptosuite strings
• Custom type table / registry entry support

Requirements

Python 3.12+

Install

PyPI

pip install cborld

With optional PyLD support for remote context resolution:

pip install cborld[context]

Development

To install locally (for development):

git clone https://github.com/subfile-llc/cborld.git
cd cborld
pip install -e ".[dev]"

Usage

Encode

from cborld import encode

cborld_bytes = encode(
    jsonld_document={
        "@context": "https://www.w3.org/ns/activitystreams",
        "type": "Note",
        "summary": "CBOR-LD",
        "content": "CBOR-LD is awesome!",
    },
    document_loader=my_loader,
    registry_entry_id=1,
)

Decode

from cborld import decode

jsonld_document = decode(
    cborld_bytes=cborld_bytes,
    document_loader=my_loader,
)

Document Loader

Both encode and decode accept an optional document_loader — a sync callable that resolves JSON-LD context URLs. If you have PyLD installed, you can use the built-in adapter:

from cborld import pyld_document_loader

loader = pyld_document_loader(extra_documents={
    "https://example.org/v1": {"@context": {...}},
})

cborld_bytes = encode(
    jsonld_document=doc,
    document_loader=loader,
    registry_entry_id=1,
)

Using in Async Apps

encode and decode are synchronous. When called from an async application (FastAPI, Starlette, etc.) and the document loader performs blocking network I/O, run them in a thread pool:

import asyncio
from cborld import encode

cborld_bytes = await asyncio.to_thread(
    encode,
    jsonld_document=doc,
    document_loader=loader,
    registry_entry_id=1,
)

Custom Type Tables

For registry entry IDs other than 0 (uncompressed) and 1 (default table), supply a type_table_loader:

def my_type_table_loader(*, registry_entry_id: int) -> dict:
    return {
        "context": {"https://example.org/v1": 0x8000},
        "url": {"https://example.org/v1": 0x8000},
        "none": {"https://example.org/v1": 0x8000},
    }

cborld_bytes = encode(
    jsonld_document=doc,
    document_loader=loader,
    registry_entry_id=100,
    type_table_loader=my_type_table_loader,
)

Error Handling

All CBOR-LD processing errors raise CborldError, which carries a machine-readable .code attribute:

from cborld import CborldError

try:
    doc = decode(cborld_bytes=data, document_loader=loader)
except CborldError as e:
    print(f"Error [{e.code}]: {e}")

API

encode(**kwargs) -> bytes

Encodes a given JSON-LD document into CBOR-LD bytes.

decode(**kwargs) -> dict

Decodes CBOR-LD bytes into a JSON-LD document.

Migrating from 0.1.x

Version 1.0.0 makes the public API synchronous. Drop await on encode / decode, and pass sync document_loader / type_table_loader callables. See CHANGELOG.md for the full migration notes.

Contribute

Please follow the existing code style.

pip install -e ".[dev]"
pytest
ruff check src tests

Specifications

• CBOR-LD 1.0

License

BSD-3-Clause © Digital Bazaar / Subfile