Skip to content

About

oold-python brings the semantic web into your Python type system. It is the Python implementation of OO-LD (Object Oriented Linked Data) - an open community framework that combines JSON Schema and JSON-LD so you can define data structure and semantics in a single source, then reuse that source for validation, RDF generation, code generation, UI generation, and API definitions.

Define schemas once, generate fully typed Pydantic models, resolve objects across knowledge graphs by IRI, and serialize back to JSON-LD - all without leaving familiar Python patterns.

DOI PyPI Build Coverage License

Why oold-python?

Knowledge graph tools typically force you to choose between semantic richness and developer ergonomics. oold-python bridges that gap:

  • Typed models from schemas - generate Pydantic dataclasses directly from OO-LD / JSON Schema definitions
  • IRI-transparent references - fields can hold either a Python object or an IRI string; the library resolves them on demand
  • Pluggable backends - swap between in-memory dicts, SQLite, local RDF graphs, or live SPARQL endpoints without changing model code
  • Lossless JSON-LD - serialize any model instance to JSON-LD, preserving the full semantic context
  • Controller pattern - add runtime behavior (connections, state, archiving) as a mixin without polluting the data model

Quick install

uv is the recommended way to install oold-python:

uv add oold

pip install oold

First steps

from oold.model import LinkedBaseModel
from pydantic import ConfigDict

class Person(LinkedBaseModel):
    model_config = ConfigDict(
        json_schema_extra={
            "@context": {"name": "https://schema.org/name"},
            "$id": "https://example.com/Person",
        }
    )
    name: str

alice = Person(name="Alice")
print(alice.to_jsonld())

{
  "@context": {"name": "https://schema.org/name"},
  "@type": "https://example.com/Person",
  "name": "Alice"
}

Where to go next

  • Get Started

    Install oold-python and run your first end-to-end example in minutes.

  • How to Use

    Step-by-step guides for code generation, backends, RDF export, and more.

  • Architecture

    Understand how the layers fit together - from schemas to SPARQL.

  • Contributing

    Fork, fix, and submit - everything you need to contribute.

Citation

If you use oold-python in your research, please cite it:

@software{oold_python,
  author  = {OO-LD Contributors},
  title   = {oold-python: Object Oriented Linked Data for Python},
  url     = {https://github.com/OO-LD/oold-python},
  doi     = {10.5281/zenodo.8374237},
}

A CITATION.cff file is included in the repository - GitHub uses it to populate the Cite this repository button on the repo page.

Library Notes
RDFLib RDF management; no schema validation or type safety. Used as a backend by oold-python.
SuRF ORM-like RDF; dynamically generated classes, no static type checking.
Owlready2 OWL-aligned classes with native reasoning; no remote SPARQL support.
twa Pydantic-based OGM; tightly couples RDF properties and type annotations.
COLD Generates static classes from OWL; no object-to-graph mapping.

See also: Bai et al. https://doi.org/10.1039/D5DD00069F