Python CBOR-LD Processor

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

Table of Contents

• Background
• Install
• Usage
• API
• 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 = await 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 = await decode(
    cborld_bytes=cborld_bytes,
    document_loader=my_loader,
)

Document Loader

Both encode and decode require a document_loader -- an async 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 = await 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:

async 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 = await 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 = await 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.

Parameter	Type	Description
jsonld_document	dict	The JSON-LD document to encode.
document_loader	async (str) -> dict	Resolves context URLs.
format	str	"cbor-ld-1.0" (default), "legacy-range", or "legacy-singleton".
registry_entry_id	int	Registry entry ID (0 = uncompressed, 1 = default table).
type_table_loader	async (registry_entry_id=int) -> dict	Resolves registry IDs to type tables. Required when registry_entry_id > 1.
diagnose	(str) -> None	Optional diagnostic callback.

decode(**kwargs) -> dict

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

Parameter	Type	Description
cborld_bytes	bytes	The CBOR-LD bytes to decode.
document_loader	async (str) -> dict	Resolves context URLs.
type_table_loader	async (registry_entry_id=int) -> dict	Resolves registry IDs to type tables.
diagnose	(str) -> None	Optional diagnostic callback.

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