+
+- :material-rocket-launch:{ .lg .middle } **[Get Started](get-started.md)**
+
+ ---
+
+ Install oold-python and run your first end-to-end example in minutes.
+
+- :material-book-open-variant:{ .lg .middle } **[How to Use](how-to/index.md)**
+
+ ---
+
+ Step-by-step guides for code generation, backends, RDF export, and more.
+
+- :material-layers:{ .lg .middle } **[Architecture](architecture.md)**
+
+ ---
+
+ Understand how the layers fit together - from schemas to SPARQL.
+
+- :material-source-pull:{ .lg .middle } **[Contributing](contributing.md)**
+
+ ---
+
+ Fork, fix, and submit - everything you need to contribute.
+
+
+
+---
+
+## Citation
+
+If you use oold-python in your research, please cite it:
+
+```bibtex
+@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.
+
+---
+
+## Related work
+
+| Library | Notes |
+|---|---|
+| [RDFLib](https://github.com/RDFLib/rdflib) | RDF management; no schema validation or type safety. Used as a backend by oold-python. |
+| [SuRF](https://github.com/cosminbasca/surfrdf) | ORM-like RDF; dynamically generated classes, no static type checking. |
+| [Owlready2](https://github.com/pwin/owlready2) | OWL-aligned classes with native reasoning; no remote SPARQL support. |
+| [twa](https://github.com/TheWorldAvatar/baselib/tree/main/python_wrapper) | Pydantic-based OGM; tightly couples RDF properties and type annotations. |
+| [COLD](https://github.com/DigiBatt/cold/) | Generates static classes from OWL; no object-to-graph mapping. |
+
+See also: Bai et al. [https://doi.org/10.1039/D5DD00069F](https://doi.org/10.1039/D5DD00069F)
diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..7a72351
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,51 @@
+# API Reference
+
+Auto-generated from source docstrings via [mkdocstrings](https://mkdocstrings.github.io/).
+
+---
+
+## GenericLinkedBaseModel
+
+Base class for all linked data models. Provides JSON-LD serialization, type registry, and the `to_jsonld()` / `to_json()` methods.
+
+::: oold.static.GenericLinkedBaseModel
+
+---
+
+## LinkedBaseModel (v2)
+
+Pydantic v2 implementation. Adds IRI-transparent field resolution, lazy loading, `cast()`, and the `[]` subscript operator.
+
+::: oold.model.LinkedBaseModel
+
+---
+
+## BaseController
+
+Mixin for adding runtime behavior to a `LinkedBaseModel` subclass without polluting the data model or the type registry.
+
+::: oold.model.BaseController
+
+---
+
+## LinkedBaseModel (v1 - legacy)
+
+Pydantic v1 implementation. Use `oold.model.LinkedBaseModel` for new projects.
+
+::: oold.model.v1.LinkedBaseModel
+
+---
+
+## Backend interface
+
+Abstract interface implemented by all backends.
+
+::: oold.backend.interface.Backend
+
+---
+
+## Generator
+
+Code generation from OO-LD / JSON Schema definitions.
+
+::: oold.generator.Generator
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..9c7c2a6
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,152 @@
+# Architecture
+
+oold-python is organized into four cooperating layers: the **model core**, the **code generator**, the **backend system**, and an optional **UI layer**. This page explains how they fit together.
+
+---
+
+## Component overview
+
+```mermaid
+graph TD
+ subgraph Schema["Schema Layer"]
+ JS["JSON Schema / OO-LD"]
+ end
+
+ subgraph Gen["Code Generator"]
+ G["Generator\n(generator.py)"]
+ DCG["datamodel-code-generator"]
+ G --> DCG
+ JS --> G
+ DCG -->|"writes .py"| PM["Generated Pydantic models\n(model/model.py)"]
+ end
+
+ subgraph Core["Model Core"]
+ GLBM["GenericLinkedBaseModel\n(static.py)"]
+ LBM["LinkedBaseModel\n(model/__init__.py)"]
+ BC["BaseController\n(model/__init__.py)"]
+ PM --> LBM
+ LBM -.->|inherits| GLBM
+ BC -.->|mixin| LBM
+ end
+
+ subgraph Backends["Backend Layer"]
+ BI["Backend interface\n(backend/interface.py)"]
+ DS["SimpleDictDocumentStore\n/ SqliteDocumentStore"]
+ SP["LocalSparqlBackend\n(backend/sparql.py)"]
+ EXT["Custom backends"]
+ BI --> DS
+ BI --> SP
+ BI --> EXT
+ end
+
+ subgraph Serialization["Serialization"]
+ JSONLD["to_jsonld()\nJSON-LD document"]
+ RDFLIB["RDFLib Graph\n(rdflib)"]
+ JSONLD --> RDFLIB
+ end
+
+ subgraph UI["UI Layer (optional)"]
+ PANEL["Panel widgets"]
+ NICEGUI["NiceGUI components"]
+ WIDGET["anywidget (Jupyter)"]
+ end
+
+ LBM -->|"resolve IRI"| BI
+ LBM -->|"store_jsonld()"| BI
+ LBM --> JSONLD
+ LBM --> UI
+```
+
+---
+
+## Layer descriptions
+
+### Schema Layer
+
+OO-LD schemas are standard JSON Schema documents extended with a `range` keyword that marks string fields as IRI references to other schemas. Schemas can compose via `allOf` and reference each other via `$ref`.
+
+### Code Generator (`generator.py`)
+
+`Generator.generate()` accepts a list of schema dicts and writes a `.py` file containing Pydantic classes. It delegates to [`datamodel-code-generator`](https://github.com/koxudaxi/datamodel-code-generator) for the actual Python source generation, then post-processes the output to wire up oold-python's IRI-resolution machinery.
+
+### Model Core
+
+**`GenericLinkedBaseModel`** (`static.py`) is the base class. It adds:
+
+- JSON-LD context injection via `json_schema_extra`
+- `to_jsonld()` / `to_json()` serialization that replaces Python object references with IRIs
+- A `_types` registry mapping IRI type strings to Python classes
+
+**`LinkedBaseModel`** (`model/__init__.py`) extends the generic base with:
+
+- IRI-transparent field validation: fields annotated with `range` accept both objects and IRI strings
+- Lazy resolution via `__get__` descriptors - IRIs are resolved on first attribute access
+- Class-level `[]` subscript operator for direct IRI lookup
+- `cast()` for cross-model conversion
+
+**`BaseController`** is a mixin for adding runtime state. See [BaseController](how-to/controller.md).
+
+### Backend Layer
+
+All backends implement the `Backend` interface from `backend/interface.py`:
+
+| Backend | Storage | SPARQL |
+|---|---|---|
+| `SimpleDictDocumentStore` | In-memory dict, optional JSON file | No |
+| `SqliteDocumentStore` | SQLite database | No |
+| `LocalSparqlBackend` | In-memory RDFLib graph | Yes |
+
+Backends are registered per IRI prefix via `set_resolver` / `set_backend`, so multiple backends can coexist in one application.
+
+### Serialization
+
+`to_jsonld()` produces a self-describing JSON-LD document. Object references are serialized as IRI strings, not as embedded objects - keeping the graph flat and enabling partial loading. The output can be fed directly into RDFLib or any JSON-LD aware triple store.
+
+### UI Layer (optional)
+
+`oold.ui` contains optional integrations for [Panel](https://panel.holoviz.org/), [NiceGUI](https://nicegui.io/), and [Jupyter anywidget](https://anywidget.dev/). These are not installed by default.
+
+---
+
+## Data flow
+
+```mermaid
+sequenceDiagram
+ participant Dev as Developer
+ participant Gen as Generator
+ participant Model as LinkedBaseModel
+ participant Backend as Backend
+ participant RDF as RDFLib
+
+ Dev->>Gen: provide JSON schemas
+ Gen-->>Dev: generated model.py
+
+ Dev->>Model: instantiate(id="ex:foo", ...)
+ Dev->>Backend: store(nodes={"ex:foo": foo})
+
+ Dev->>Model: foo.bar (IRI reference)
+ Model->>Backend: resolve_iris(["ex:bar"])
+ Backend-->>Model: Bar instance
+
+ Dev->>Model: foo.to_jsonld()
+ Model-->>RDF: JSON-LD document
+ RDF-->>Dev: SPARQL results
+```
+
+1. **Schema → model**: `Generator` converts JSON schemas into typed Pydantic classes
+2. **Instantiation**: models are created like any Pydantic class; IRI-valued fields are stored as strings
+3. **Persistence**: `store()` serializes instances and writes to the backend
+4. **Resolution**: accessing an IRI-valued attribute triggers a backend lookup; the result is cached on the instance
+5. **Serialization**: `to_jsonld()` replaces all resolved objects with their IRIs, producing a flat JSON-LD graph
+
+---
+
+## Key design decisions
+
+**IRI transparency** - the same field can hold either an object or an IRI. This means you can work with partial graphs (load only what you need) and still produce correct JSON-LD.
+
+**Schema-first** - all semantic meaning lives in the JSON schema, not in Python class annotations. This makes schemas portable across languages and tools.
+
+**Pluggable backends** - no single storage technology is assumed. Swapping backends requires only re-registering the prefix; model code is unchanged.
+
+**Controller separation** - runtime behavior is kept out of data models entirely, so serialization is always deterministic and backend-independent.
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 0000000..e9623ed
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,100 @@
+# Contributing
+
+Contributions are welcome! You can help by reporting bugs, implementing features, or improving documentation. File issues and PRs at [github.com/OO-LD/oold-python](https://github.com/OO-LD/oold-python).
+
+---
+
+## Development Setup
+
+Requires `uv` and `git`.
+
+=== "SSH"
+
+ ```bash
+ git clone git@github.com:YOUR_NAME/oold-python.git
+ cd oold-python
+ ```
+
+=== "HTTPS"
+
+ ```bash
+ git clone https://github.com/YOUR_NAME/oold-python.git
+ cd oold-python
+ ```
+
+### Install the environment and hooks
+
+=== "make"
+
+ ```bash
+ make install
+ ```
+
+=== "without make"
+
+ ```bash
+ uv sync
+ uv run pre-commit install
+ ```
+
+---
+
+## Making Changes
+
+1. Create a branch: `git checkout -b name-of-your-fix`
+2. Make your changes and add tests in `tests/`
+3. Run checks and tests (see below)
+4. Commit and push, then open a pull request
+
+### Checks and tests
+
+=== "make"
+
+ ```bash
+ make check # lint, type-check, dependency audit
+ make test # pytest with coverage
+ ```
+
+=== "without make"
+
+ ```bash
+ uv lock --locked
+ uv run pre-commit run -a
+ uv run ty check
+ uv run deptry src
+ uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=xml
+ ```
+
+### Docs
+
+Doc sources live in `docs/`. The site is configured in `zensical.toml`.
+
+=== "make"
+
+ ```bash
+ make docs # serve with live reload at http://localhost:8000
+ make docs-test # strict build - fails on any warning
+ ```
+
+=== "without make"
+
+ ```bash
+ uv run zensical serve
+ uv run zensical build -s
+ ```
+
+---
+
+## Releasing
+
+Releases are published automatically by CI when a version tag is pushed.
+
+1. Ensure all changes are merged to `main`
+2. Tag the commit and push:
+
+```bash
+git tag v0.17.0
+git push origin v0.17.0
+```
+
+CI will build the package (`uv build`), publish it to PyPI, and deploy the docs to GitHub Pages. The version is derived from the git tag via `hatch-vcs` - no manual version bumping needed.
diff --git a/docs/dev.md b/docs/dev.md
deleted file mode 100644
index fd42e5a..0000000
--- a/docs/dev.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Setup
-1. create a virtual environment
-```bash
-python -m venv .venv
-```
-
-1. install requirements + extras
-```bash
-pip install -e .[dev,testing]
-```
-
-
-# Testing
-
-1. Create new test (file name test_*.py) under /tests
-
-1. Run pytest in the project root dir
-```bash
-tox -e test
-```
diff --git a/docs/get-started.md b/docs/get-started.md
new file mode 100644
index 0000000..faef481
--- /dev/null
+++ b/docs/get-started.md
@@ -0,0 +1,114 @@
+# Get Started
+
+This guide walks you from a fresh install to a working end-to-end example.
+
+## Prerequisites
+
+- Python **3.10 or later**
+- `pip` or [`uv`](https://docs.astral.sh/uv/) (recommended)
+
+## Installation
+
+=== "uv (recommended)"
+
+ ```bash
+ uv add oold
+ ```
+
+=== "pip"
+
+ ```bash
+ pip install oold
+ ```
+
+Verify the installation:
+
+```bash
+python -c "import oold; print(oold.__version__)"
+```
+
+---
+
+## Hello World
+
+The following example covers the full core workflow in one script:
+
+1. Define a JSON Schema
+2. Generate a typed Pydantic model
+3. Populate a backend
+4. Resolve objects by IRI
+5. Serialize to JSON-LD
+
+```python
+import importlib
+import datamodel_code_generator
+from pathlib import Path
+from pydantic import ConfigDict
+
+from oold.generator import Generator
+from oold.backend.document_store import SimpleDictDocumentStore
+from oold.backend.interface import SetResolverParam, SetBackendParam, StoreParam, set_resolver, set_backend
+import oold.model.model as model
+
+# 1. Define schemas
+schemas = [
+ {
+ "id": "Person",
+ "title": "Person",
+ "type": "object",
+ "properties": {
+ "id": {"type": "string"},
+ "type": {"type": "array", "items": {"type": "string"}, "default": ["Person"]},
+ "name": {"type": "string"},
+ },
+ },
+]
+
+# 2. Generate the Pydantic model into a file, then reload
+output_path = Path("generated_model.py")
+g = Generator()
+g.generate(Generator.GenerateParams(
+ json_schemas=schemas,
+ main_schema="Person.json",
+ output_model_type=datamodel_code_generator.DataModelType.PydanticV2BaseModel,
+ output_model_path=output_path,
+))
+importlib.reload(model) # pick up the freshly written module
+
+# 3. Create instances and a backend
+store = SimpleDictDocumentStore()
+set_resolver(SetResolverParam(iri="ex", resolver=store))
+set_backend(SetBackendParam(iri="ex", backend=store))
+
+alice = model.Person(id="ex:alice", name="Alice")
+bob = model.Person(id="ex:bob", name="Bob")
+
+store.store(StoreParam(nodes={"ex:alice": alice, "ex:bob": bob}))
+
+# 4. Resolve by IRI
+loaded = model.Person["ex:alice"]
+print(loaded.name) # Alice
+
+# 5. Serialize to JSON-LD
+print(alice.to_jsonld())
+```
+
+```json
+{
+ "@id": "ex:alice",
+ "@type": ["Person"],
+ "name": "Alice"
+}
+```
+
+---
+
+## What's next?
+
+| Topic | Guide |
+|---|---|
+| Generate models from complex schemas | [Code Generation](how-to/codegen.md) |
+| Work with IRI references and lazy resolution | [Object Graph Mapping](how-to/object-graph-mapping.md) |
+| Persist and query with different backends | [Backends](how-to/backends.md) |
+| Export to RDF and run SPARQL queries | [RDF Export](how-to/rdf-export.md) |
+| Separate runtime state from data | [BaseController](how-to/controller.md) |
diff --git a/docs/how-to/backends.md b/docs/how-to/backends.md
new file mode 100644
index 0000000..bbac909
--- /dev/null
+++ b/docs/how-to/backends.md
@@ -0,0 +1,170 @@
+# Backends
+
+Backends are the persistence and resolution layer for IRI-referenced entities. You register a backend for an IRI prefix, and all resolution and storage calls for that prefix are routed to it.
+
+---
+
+## The backend interface
+
+Every backend implements two operations from `oold.backend.interface.Backend`:
+
+- **`resolve_iris`** - fetch entities by IRI and deserialize them into model instances
+- **`store_json_dicts`** - persist entities as JSON dictionaries
+
+You configure which backend handles which IRI prefix using `set_resolver` and `set_backend`:
+
+```python
+from oold.backend.interface import SetResolverParam, SetBackendParam, set_resolver, set_backend
+
+set_resolver(SetResolverParam(iri="ex", resolver=my_backend)) # routes reads for "ex:*"
+set_backend(SetBackendParam(iri="ex", backend=my_backend)) # routes writes for "ex:*"
+```
+
+---
+
+## SimpleDictDocumentStore
+
+An in-memory dictionary store. Optionally persists to a JSON file.
+
+```python
+from oold.backend.document_store import SimpleDictDocumentStore
+from oold.backend.interface import (
+ SetResolverParam, SetBackendParam, StoreParam,
+ set_resolver, set_backend,
+)
+
+# In-memory only
+store = SimpleDictDocumentStore()
+
+# With JSON file persistence
+store = SimpleDictDocumentStore(file_path="./data/entities.json")
+
+set_resolver(SetResolverParam(iri="ex", resolver=store))
+set_backend(SetBackendParam(iri="ex", backend=store))
+```
+
+### Storing entities
+
+```python
+from oold.backend.interface import StoreParam
+
+store.store(StoreParam(nodes={
+ "ex:alice": alice,
+ "ex:bob": bob,
+}))
+```
+
+### Resolving entities
+
+```python
+from oold.backend.interface import ResolveParam
+
+result = store.resolve(ResolveParam(iris=["ex:alice"], model_cls=Person))
+alice_loaded = result.nodes["ex:alice"]
+print(alice_loaded.name) # Alice
+```
+
+### Shorthand via class subscript
+
+Once a resolver is registered, use the class-level `[]` operator:
+
+```python
+alice = Person["ex:alice"]
+```
+
+### Storing via the model instance
+
+```python
+alice.store_jsonld() # stores using the registered backend for the instance's IRI prefix
+```
+
+---
+
+## SqliteDocumentStore
+
+Persists entities in a SQLite database. Drop-in replacement for `SimpleDictDocumentStore`.
+
+```python
+from oold.backend.document_store import SqliteDocumentStore
+
+store = SqliteDocumentStore(file_path="./data/entities.db")
+
+set_resolver(SetResolverParam(iri="ex", resolver=store))
+set_backend(SetBackendParam(iri="ex", backend=store))
+
+# Same API as SimpleDictDocumentStore
+store.store(StoreParam(nodes={"ex:alice": alice}))
+alice = Person["ex:alice"]
+```
+
+---
+
+## LocalSparqlBackend
+
+An in-memory RDF graph (via [rdflib](https://rdflib.readthedocs.io/)) that supports SPARQL queries.
+
+```python
+from oold.backend.sparql import LocalSparqlBackend
+from oold.backend.interface import SetResolverParam, SetBackendParam, set_resolver, set_backend
+
+sparql_store = LocalSparqlBackend()
+set_resolver(SetResolverParam(iri="ex", resolver=sparql_store))
+set_backend(SetBackendParam(iri="ex", backend=sparql_store))
+
+# Store and retrieve
+sparql_store.store(StoreParam(nodes={"ex:alice": alice}))
+alice_loaded = Person["ex:alice"]
+```
+
+The backend serializes each entity to JSON-LD before inserting it into the RDF graph, so all semantic annotations are preserved. See [RDF Export](rdf-export.md) for how to run SPARQL queries directly.
+
+---
+
+## Multiple backends
+
+Register different backends for different IRI prefixes:
+
+```python
+local_store = SimpleDictDocumentStore()
+remote_store = SqliteDocumentStore(file_path="remote.db")
+
+set_resolver(SetResolverParam(iri="local", resolver=local_store))
+set_resolver(SetResolverParam(iri="remote", resolver=remote_store))
+set_backend(SetBackendParam(iri="local", backend=local_store))
+set_backend(SetBackendParam(iri="remote", backend=remote_store))
+
+# "local:*" and "remote:*" IRIs are routed independently
+local_obj = MyModel(id="local:obj1", ...)
+remote_obj = MyModel(id="remote:obj2", ...)
+```
+
+---
+
+## Implementing a custom backend
+
+Subclass `Backend` and implement `resolve_iris` and `store_json_dicts`:
+
+```python
+from oold.backend.interface import Backend, ResolveParam, ResolveResult, StoreParam
+
+class MyCustomBackend(Backend):
+
+ def resolve_iris(self, param: ResolveParam) -> ResolveResult:
+ nodes = {}
+ for iri in param.iris:
+ raw = self._fetch(iri) # your fetch logic here
+ if raw is not None:
+ nodes[iri] = param.model_cls(**raw)
+ return ResolveResult(nodes=nodes)
+
+ def store_json_dicts(self, param: StoreParam) -> None:
+ for iri, entity in param.nodes.items():
+ self._persist(iri, entity.model_dump()) # your persistence logic here
+
+backend = MyCustomBackend()
+set_resolver(SetResolverParam(iri="custom", resolver=backend))
+set_backend(SetBackendParam(iri="custom", backend=backend))
+```
+
+!!! note
+ `resolve_iris` receives a `model_cls` so the backend knows which class to instantiate. When the type is encoded in the JSON document itself (via the `type` array), the backend can also perform type-based dispatch.
diff --git a/docs/how-to/codegen.md b/docs/how-to/codegen.md
new file mode 100644
index 0000000..d9a7eaa
--- /dev/null
+++ b/docs/how-to/codegen.md
@@ -0,0 +1,166 @@
+# Code Generation
+
+oold-python includes a `Generator` that converts OO-LD / JSON Schema definitions into fully typed Pydantic dataclasses using [`datamodel-code-generator`](https://github.com/koxudaxi/datamodel-code-generator) under the hood.
+
+---
+
+## Minimal single-schema example
+
+```python
+import importlib
+import datamodel_code_generator
+from pathlib import Path
+
+from oold.generator import Generator
+import oold.model.model as model
+
+schemas = [
+ {
+ "id": "Item",
+ "title": "Item",
+ "type": "object",
+ "properties": {
+ "id": {"type": "string"},
+ "type": {"type": "array", "items": {"type": "string"}, "default": ["Item"]},
+ "label": {"type": "string"},
+ },
+ }
+]
+
+g = Generator()
+g.generate(Generator.GenerateParams(
+ json_schemas=schemas,
+ main_schema="Item.json",
+ output_model_type=datamodel_code_generator.DataModelType.PydanticV2BaseModel,
+ output_model_path=Path("generated_model.py"),
+))
+importlib.reload(model)
+
+item = model.Item(id="ex:item1", label="My first item")
+print(item.model_dump())
+# {'id': 'ex:item1', 'type': ['Item'], 'label': 'My first item'}
+```
+
+!!! note
+ `importlib.reload(model)` is required after generation so Python picks up the newly written file.
+
+---
+
+## Multi-schema example with references
+
+Schemas can reference each other via `$ref`. The generator resolves the dependency graph automatically.
+
+```python
+schemas = [
+ {
+ "id": "Tag",
+ "title": "Tag",
+ "type": "object",
+ "properties": {
+ "id": {"type": "string"},
+ "type": {"type": "array", "items": {"type": "string"}, "default": ["Tag"]},
+ "name": {"type": "string"},
+ },
+ },
+ {
+ "id": "Article",
+ "title": "Article",
+ "type": "object",
+ "required": ["id", "title"],
+ "properties": {
+ "id": {"type": "string"},
+ "type": {"type": "array", "items": {"type": "string"}, "default": ["Article"]},
+ "title": {"type": "string"},
+ # 'range' marks this field as an IRI reference to a Tag
+ "tag": {"type": "string", "range": "Tag.json"},
+ "tags": {"type": "array", "items": {"type": "string", "range": "Tag.json"}},
+ },
+ },
+]
+
+g = Generator()
+g.generate(Generator.GenerateParams(
+ json_schemas=schemas,
+ main_schema="Article.json",
+ output_model_type=datamodel_code_generator.DataModelType.PydanticV2BaseModel,
+ output_model_path=Path("generated_model.py"),
+))
+importlib.reload(model)
+```
+
+Fields annotated with `"range": ".json"` become IRI-transparent references: you can assign either a full `Tag` instance or an IRI string.
+
+```python
+tag = model.Tag(id="ex:t1", name="python")
+article = model.Article(id="ex:a1", title="Hello World", tag=tag)
+# or by IRI - resolved lazily when accessed
+article2 = model.Article(id="ex:a2", title="Another Post", tag="ex:t1")
+```
+
+---
+
+## Schema inheritance with `allOf`
+
+Use `allOf` to compose schemas:
+
+```python
+schemas = [
+ {
+ "id": "Base",
+ "title": "Base",
+ "type": "object",
+ "properties": {
+ "id": {"type": "string"},
+ "type": {"type": "array", "items": {"type": "string"}, "default": ["Base"]},
+ },
+ },
+ {
+ "id": "Extended",
+ "title": "Extended",
+ "type": "object",
+ "allOf": [{"$ref": "Base.json"}],
+ "properties": {
+ "type": {"type": "array", "items": {"type": "string"}, "default": ["Extended"]},
+ "extra_field": {"type": "string"},
+ },
+ },
+]
+```
+
+The generated `Extended` class inherits all fields from `Base`.
+
+---
+
+## Output model types
+
+| Constant | Pydantic version | Use when |
+|---|---|---|
+| `PydanticV2BaseModel` | v2 (recommended) | new projects |
+| `PydanticBaseModel` | v1 (legacy) | existing v1 codebases |
+
+```python
+import datamodel_code_generator
+
+# Pydantic v2
+output_model_type = datamodel_code_generator.DataModelType.PydanticV2BaseModel
+
+# Pydantic v1 (legacy)
+output_model_type = datamodel_code_generator.DataModelType.PydanticBaseModel
+```
+
+---
+
+## Output path
+
+`output_model_path` accepts any `pathlib.Path`. The generator writes a single `.py` file containing all generated classes.
+
+```python
+from pathlib import Path
+
+Generator.GenerateParams(
+ ...
+ output_model_path=Path("src/mypackage/generated.py"),
+)
+```
+
+Commit the generated file to version control so downstream code has stable imports and the generation step is only re-run when schemas change.
diff --git a/docs/how-to/controller.md b/docs/how-to/controller.md
new file mode 100644
index 0000000..2d5457c
--- /dev/null
+++ b/docs/how-to/controller.md
@@ -0,0 +1,126 @@
+# BaseController
+
+A controller adds runtime behavior - connections, caching, state machines - to a data model. oold-python keeps these concerns separate: the data model is a pure `LinkedBaseModel`, and the controller is a mixin that inherits from both `BaseController` and the data model.
+
+---
+
+## Why a controller?
+
+| Data model | Controller |
+|---|---|
+| Serializable, version-controlled | Lives only at runtime |
+| Stored in the backend | Never persisted |
+| Passed between systems | Machine- or session-local |
+| e.g. `Robot.joint_count` | e.g. `RobotController._socket` |
+
+Keeping them separate means `to_json()` / `to_jsonld()` always produces clean, controller-free documents - and the backend type registry always resolves to the pure data class.
+
+---
+
+## Basic pattern
+
+```python
+from oold.model import BaseController, LinkedBaseModel
+
+class Robot(LinkedBaseModel):
+ id: str
+ name: str
+ joint_count: int = 6
+ connection_url: str = ""
+
+class RobotController(BaseController, Robot):
+ _connected: bool = False # controller-only state (underscore prefix)
+
+ def connect(self) -> None:
+ self._connected = True
+ print(f"Connected to {self.connection_url}")
+
+ def move(self, joint: int, angle: float) -> None:
+ if not self._connected:
+ raise RuntimeError("Not connected")
+ print(f"Joint {joint} → {angle}°")
+
+ctrl = RobotController(
+ id="ex:robot-1",
+ name="arm-1",
+ connection_url="tcp://192.168.1.10:5000",
+)
+ctrl.connect()
+ctrl.move(1, 45.0)
+```
+
+---
+
+## Serialization
+
+`to_json()` and `to_jsonld()` on a controller instance only include fields defined on the underlying data model. Controller state (private `_` attributes and non-model fields) is stripped automatically.
+
+```python
+print(ctrl.to_json())
+```
+
+```json
+{
+ "id": "ex:robot-1",
+ "name": "arm-1",
+ "joint_count": 6,
+ "connection_url": "tcp://192.168.1.10:5000"
+}
+```
+
+`_connected` does not appear in the output.
+
+---
+
+## Type registry behavior
+
+`BaseController` excludes itself from the `_types` lookup. When the backend resolves `"ex:robot-1"`, it returns a plain `Robot` instance, not a `RobotController`. This prevents controller logic from leaking into resolved data objects.
+
+---
+
+## Multi-model controller
+
+A controller can extend multiple data models. Type arrays from all parent models are merged:
+
+```python
+class Sensor(LinkedBaseModel):
+ id: str
+ sensor_type: str = "temperature"
+
+class RobotWithSensor(BaseController, Robot, Sensor):
+ _calibrated: bool = False
+
+ def calibrate(self) -> None:
+ self._calibrated = True
+ print(f"Sensor calibrated: {self.sensor_type}")
+
+combined = RobotWithSensor(
+ id="ex:robot-sensor-1",
+ name="arm-2",
+ sensor_type="force",
+)
+combined.calibrate()
+print(combined.to_json())
+# includes fields from both Robot and Sensor, no controller state
+```
+
+---
+
+## Archiving and state persistence
+
+While the controller itself is not persisted, you can explicitly archive the data model portion at any time:
+
+```python
+# Store only the data model fields
+ctrl.store_jsonld() # writes to the registered backend for ctrl.id's prefix
+```
+
+This is useful for checkpointing state (e.g. saving `joint_count` after a calibration) without persisting the live connection handle.
+
+---
+
+## Guidelines
+
+- Prefix controller-only attributes with `_` to make the distinction explicit
+- Keep `__init__` arguments limited to data model fields - controllers should be constructed from data, not from runtime handles
+- If a controller needs runtime resources (sockets, threads), initialize them in a dedicated `connect()` / `start()` method, not in `__init__`
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
new file mode 100644
index 0000000..7d1b385
--- /dev/null
+++ b/docs/how-to/index.md
@@ -0,0 +1,43 @@
+# How to Use
+
+Practical, task-focused guides for every major feature of oold-python. Each one is self-contained - pick the topic you need, or read them in order to build up the full picture.
+
+New here? Start with [Get Started](../get-started.md) to run your first end-to-end example, then come back for the deep dives.
+
+---
+
+## Guides
+
+
+
+- :material-code-braces:{ .lg .middle } **[Code Generation](codegen.md)**
+
+ ---
+
+ Turn OO-LD / JSON Schema definitions into fully typed Pydantic models - single and multi-schema workflows, schema references, and output model types.
+
+- :material-vector-link:{ .lg .middle } **[Object Graph Mapping](object-graph-mapping.md)**
+
+ ---
+
+ Treat knowledge-graph entities as ordinary Python objects - IRI-transparent fields, lazy resolution across backends, and the `cast()` utility.
+
+- :material-database:{ .lg .middle } **[Backends](backends.md)**
+
+ ---
+
+ Persist and resolve entities anywhere - `SimpleDictDocumentStore`, `SqliteDocumentStore`, `LocalSparqlBackend`, and how to roll your own.
+
+- :material-graph-outline:{ .lg .middle } **[RDF Export](rdf-export.md)**
+
+ ---
+
+ Serialize models to JSON-LD, load them into RDFLib, and query with SPARQL - context injection, cross-object links, and round-trip fidelity.
+
+- :material-tune:{ .lg .middle } **[BaseController](controller.md)**
+
+ ---
+
+ Attach runtime behavior to data models without polluting them - the controller mixin pattern, serialization rules, and multi-model controllers.
+
+
diff --git a/docs/how-to/object-graph-mapping.md b/docs/how-to/object-graph-mapping.md
new file mode 100644
index 0000000..89bce2c
--- /dev/null
+++ b/docs/how-to/object-graph-mapping.md
@@ -0,0 +1,157 @@
+# Object Graph Mapping
+
+oold-python's core feature is *IRI-transparent references*: a field annotated with `range` can hold either a Python object or an IRI string. The library resolves IRIs on first access via the registered backend.
+
+---
+
+## Direct object assignment
+
+The simplest case - pass objects directly:
+
+```python
+from oold.model import LinkedBaseModel
+from pydantic import ConfigDict
+from typing import List, Optional
+
+class Tag(LinkedBaseModel):
+ model_config = ConfigDict(json_schema_extra={"$id": "https://example.com/Tag"})
+ id: str
+ name: str
+
+class Article(LinkedBaseModel):
+ model_config = ConfigDict(json_schema_extra={"$id": "https://example.com/Article"})
+ id: str
+ title: str
+ primary_tag: Optional[Tag] = None
+ tags: List[Tag] = []
+
+python_tag = Tag(id="ex:tag-python", name="python")
+async_tag = Tag(id="ex:tag-async", name="async")
+
+article = Article(
+ id="ex:article-1",
+ title="Async Python Tips",
+ primary_tag=python_tag,
+ tags=[python_tag, async_tag],
+)
+
+print(article.primary_tag.name) # python
+print(article.tags[1].name) # async
+```
+
+---
+
+## IRI string assignment and lazy resolution
+
+Assign IRI strings instead of objects. The backend resolves them on first access.
+
+```python
+from oold.backend.document_store import SimpleDictDocumentStore
+from oold.backend.interface import SetResolverParam, StoreParam, set_resolver
+
+store = SimpleDictDocumentStore()
+set_resolver(SetResolverParam(iri="ex", resolver=store))
+
+# Pre-populate the backend
+store.store(StoreParam(nodes={
+ "ex:tag-python": python_tag,
+ "ex:tag-async": async_tag,
+}))
+
+# Assign IRIs - objects are NOT loaded yet
+article2 = Article(
+ id="ex:article-2",
+ title="Another Post",
+ primary_tag="ex:tag-python", # IRI string
+ tags=["ex:tag-python", "ex:tag-async"],
+)
+
+# First access triggers backend resolution
+print(article2.primary_tag.name) # python - loaded from store on demand
+print(article2.tags[0].name) # python
+```
+
+!!! tip
+ Lazy resolution keeps startup fast: only the entities you actually access are fetched from the backend.
+
+---
+
+## Resolving by IRI directly
+
+Use the class-level `[]` operator as a shorthand:
+
+```python
+tag = Tag["ex:tag-python"] # equivalent to store.resolve(...)
+print(tag.name) # python
+```
+
+---
+
+## Mixing objects and IRIs
+
+You can mix concrete objects and IRIs in a list:
+
+```python
+article3 = Article(
+ id="ex:article-3",
+ title="Mixed References",
+ tags=[python_tag, "ex:tag-async"], # one object, one IRI
+)
+```
+
+---
+
+## `cast()` - converting between model classes
+
+`cast()` converts an instance from one model class to another while preserving `__iris__` references.
+
+```python
+from oold.model import LinkedBaseModel
+
+class ArticleV1(LinkedBaseModel):
+ id: str
+ title: str
+ body: str = ""
+
+class ArticleV2(LinkedBaseModel):
+ id: str
+ title: str
+ content: str = "" # renamed field
+
+v1 = ArticleV1(id="ex:a1", title="Hello", body="Some text")
+
+# Cast to V2; fields not on V2 are dropped, None fields use V2 defaults
+v2 = v1.cast(ArticleV2, remove_extra=True, none_to_default=True)
+print(v2.id) # ex:a1
+print(v2.title) # Hello
+print(v2.content) # "" - default, since 'body' doesn't exist on V2
+```
+
+`cast()` parameters:
+
+| Parameter | Effect |
+|---|---|
+| `remove_extra=True` | Drop fields not defined on the target class |
+| `none_to_default=True` | Replace `None` / empty-list values with the target's defaults |
+| `silent=True` | Suppress warnings about dropped fields (default) |
+
+You can also construct a target instance directly from another model:
+
+```python
+v2 = ArticleV2(v1, content="migrated")
+```
+
+---
+
+## Default IRI values
+
+A field can carry a default IRI that is resolved automatically on instantiation:
+
+```python
+# Schema definition
+{
+ "b_default": {"type": "string", "range": "Tag.json", "default": "ex:tag-python"}
+}
+```
+
+When you instantiate the model without supplying `b_default`, the IRI `"ex:tag-python"` is used and resolved on first access.
diff --git a/docs/how-to/rdf-export.md b/docs/how-to/rdf-export.md
new file mode 100644
index 0000000..70c66bb
--- /dev/null
+++ b/docs/how-to/rdf-export.md
@@ -0,0 +1,143 @@
+# RDF Export
+
+Every `LinkedBaseModel` instance can be serialized to JSON-LD via `to_jsonld()`. The resulting document carries the full semantic context defined in the model's `json_schema_extra`, making it directly importable into RDFLib, triple stores, or any JSON-LD consumer.
+
+---
+
+## Defining a model with semantic context
+
+The `@context` block maps Python field names to RDF predicates. `$id` is the IRI of the class itself.
+
+```python
+from oold.model import LinkedBaseModel
+from pydantic import ConfigDict
+from typing import List, Optional
+
+class Person(LinkedBaseModel):
+ model_config = ConfigDict(
+ json_schema_extra={
+ "@context": {
+ "id": "@id",
+ "type": "@type",
+ "schema": "https://schema.org/",
+ "ex": "https://example.com/",
+ "name": "schema:name",
+ "knows": {"@id": "schema:knows", "@type": "@id"},
+ },
+ "$id": "https://example.com/Person",
+ }
+ )
+ id: str
+ name: str
+ knows: List["Person"] = []
+```
+
+---
+
+## Serializing to JSON-LD
+
+```python
+alice = Person(id="ex:alice", name="Alice")
+bob = Person(id="ex:bob", name="Bob", knows=[alice])
+
+print(bob.to_jsonld())
+```
+
+```json
+{
+ "@context": {
+ "id": "@id",
+ "type": "@type",
+ "schema": "https://schema.org/",
+ "ex": "https://example.com/",
+ "name": "schema:name",
+ "knows": {"@id": "schema:knows", "@type": "@id"}
+ },
+ "@id": "ex:bob",
+ "@type": "https://example.com/Person",
+ "name": "Bob",
+ "knows": ["ex:alice"]
+}
+```
+
+!!! note
+ Nested object references are serialized as IRIs, not as embedded documents. This keeps the JSON-LD graph flat and avoids duplication across documents.
+
+---
+
+## Loading into RDFLib
+
+```python
+from rdflib import Graph
+
+g = Graph()
+g.parse(data=alice.to_jsonld(), format="json-ld")
+g.parse(data=bob.to_jsonld(), format="json-ld")
+
+print(f"Graph has {len(g)} triples")
+```
+
+---
+
+## Querying with SPARQL
+
+```python
+qres = g.query("""
+ PREFIX schema:
+
+ SELECT ?name
+ WHERE {
+ ?person schema:knows ?other .
+ ?other schema:name ?name .
+ }
+""")
+
+for row in qres:
+ print("Bob knows", row.name)
+# Bob knows Alice
+```
+
+---
+
+## Using LocalSparqlBackend for combined store + query
+
+`LocalSparqlBackend` maintains an in-memory RDF graph. Store entities there and query them via SPARQL without leaving Python:
+
+```python
+from oold.backend.sparql import LocalSparqlBackend
+from oold.backend.interface import SetResolverParam, SetBackendParam, StoreParam, set_resolver, set_backend
+
+sparql = LocalSparqlBackend()
+set_resolver(SetResolverParam(iri="ex", resolver=sparql))
+set_backend(SetBackendParam(iri="ex", backend=sparql))
+
+sparql.store(StoreParam(nodes={"ex:alice": alice, "ex:bob": bob}))
+
+# Direct SPARQL on the internal graph
+results = sparql.graph.query("""
+ PREFIX schema:
+ SELECT ?s ?name WHERE { ?s schema:name ?name }
+""")
+for row in results:
+ print(row.name)
+```
+
+---
+
+## Round-trip: JSON-LD → model instance
+
+You can reconstruct a model instance from its JSON-LD representation:
+
+```python
+import json
+from oold.model import LinkedBaseModel
+
+jsonld_str = alice.to_jsonld()
+data = json.loads(jsonld_str)
+
+# Re-hydrate (context is embedded, @id maps to id, @type maps to type)
+alice2 = Person(id=data["@id"], name=data["name"])
+print(alice2.name) # Alice
+```
+
+For more complex round-trips - including nested objects - use a registered backend and resolve by IRI after storing.
diff --git a/docs/index.md b/docs/index.md
index b3bfb11..0d0d117 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,9 +1,28 @@
-# Linked Data Classes (oold)
+---
+title: Object Oriented Linked Data
+hide:
+ - navigation
+ - toc
+---
-Python toolset for abtract and object oriented access to knowledge graphs. This package aims to implemment this functionality independent from the [osw-python](https://github.com/OpenSemanticLab/osw-python) package.
+
-## Concept
+
-
+
Object Oriented Linked Data
- > Illustrative example how the object orient linked data (OOLD) package provides an abstract knowledge graph (KG) interface. First (line 3) primary schemas (Foo) and their dependencies (Bar, Baz) are loaded from the KG and transformed into python dataclasses. Instantiation of foo is handled by loading the respective JSON(-LD) document from the KG and utilizing the type relation to the corresponding schema and dataclass (line 5). Because bar is not a dependent subobject of foo it is loaded on-demand on first access of the corresponding class attribute of foo (foo.bar in line 7), while id as dependent literal is loaded immediately in the same operation. In line 9 baz is constructed by an existing controller class subclassing Foo and finally stored as a new entity in the KG in line 11.
+
Link object-oriented programming with linked data and the semantic web.
+
+
+Define data structure and semantics in a single source by embedding JSON-LD
+contexts within JSON Schema - then reuse that one schema for validation, RDF
+generation, code generation, UIs, and API definitions. oold-python brings it
+all into your Python type system.
+
+
+
+[Get started](get-started.md){ .md-button .md-button--primary }
+[Learn more](about.md){ .md-button }
+
+
+