Skip to content

OntoSQL Dependency Ecosystem Assessment

Overview

This document evaluates Python dependencies for ontosql as a semantic mapper and session layer over SQL, with JSON-LD/RDF export as a derivative. OntoSQL sits in an ecosystem with TripleModel and SparqlModel — see ECOSYSTEM.md.

The goal is a small core, optional extras, and Pythonic APIs — not a heavyweight semantic-web framework.

Dependency philosophy

  • Small, stable core (semantic + map + session + export)
  • SQLModel for physical tables only; Pydantic for semantic entities
  • TripleModel as the RDF serialization and CURIE expansion backend
  • Optional extras for FastAPI, SparqlModel (graph sync), advanced JSON-LD
  • No magical 1:1 table-to-ontology inference

Core dependencies

Pydantic v2

  • Semantic models (OntoModel, validation, partial updates)
  • JSON schema for OpenAPI enrichment (0.3+)
  • Primary type surface for application code

SQLModel

  • Physical models (table=True)
  • SQLAlchemy engine and session integration
  • Familiar ergonomics for FastAPI teams

SQLAlchemy 2.x

  • Accessed via SQLModel
  • Column expressions, joins, and compiled statements for OntoSession
  • Core of the mapper compile path

typing-extensions

  • Typing compatibility on Python 3.10+

TripleModel

  • Core RDF dependency (replaces RDFLib)
  • expand_curie() — backing PrefixRegistry.expand()
  • Store, bind_namespaces, serialize() — OntoModel.to_jsonld() / to_rdf()
  • pyoxigraph graph engine (transitive via TripleModel)
  • Shared vocabulary and serialization conventions with SparqlModel

OntoSQL does not require apps to subclass TripleModel. Export builds a graph from OntoModel instances at serialization time.

Ecosystem dependencies (optional)

SparqlModel (ontosql[sparql])

  • Graph-native ORM sibling to OntoSQL
  • SPARQLSession, SPARQL query DSL, cascade put/delete
  • Shipped: OntoGraphSync adapter in ontosql.sync.sparql — push/pull between SQL session results and SPARQL stores (HYBRID.md)
  • Depends on TripleModel; installing ontosql[sparql] pulls both SparqlModel and its TripleModel pin

FastAPI ecosystem (optional extra)

FastAPI + orjson (ontosql[fastapi])

  • OntoRouter CRUD routes with content negotiation (0.3+); 0.5+ async-only via onto_async_session_lifespan + AsyncSessionDep
  • onto_session_lifespan / SessionDep for custom sync routes only
  • orjson for fast JSON-LD response bodies

See SPECS.md for production limitations of OntoRouter.

JSON-LD ecosystem (optional extra)

PyLD (ontosql[jsonld])

  • Compaction and framing beyond TripleModel/pyoxigraph basics
  • compact_jsonld / frame_jsonld helpers (0.3+)

Semantic validation (ontosql[shacl])

pySHACL

  • Validate graphs generated from maps + session (shipped in 0.4)
  • validate_instance() and shape generation in ontosql.shacl

Graph database integrations (future)

SPARQLWrapper

  • Remote SPARQL endpoints (may overlap with SparqlModel HttpStore)

Neo4j Python driver

  • Hybrid SQL + property graph architectures

Remote endpoint and Neo4j adapters remain on the ROADMAP. In-process graph sync via StoreSyncTarget and SparqlModel OntoGraphSync shipped in 0.4.

AI and LLM ecosystem (long-term)

Instructor / PydanticAI

  • Structured extraction into OntoModel instances
  • Aligns with semantic-layer-first design

DeepOnto

  • Ontology alignment and embeddings (research-oriented)

Developer tooling

Package Role
pytest Tests
pytest-asyncio Async session tests
pytest-cov Coverage
pytest-xdist Parallel runs
ty Static typing (src/ontosql)
ruff Lint and format
httpx FastAPI integration tests
hatchling Wheel build
aiosqlite Async SQLite tests
greenlet SQLAlchemy async support in tests

| mkdocs-material + mkdocstrings | Documentation site (Read the Docs) |

Install: pip install ontosql[docs] or pip install -e ".[dev]".

Extras in pyproject.toml

[project.optional-dependencies]
fastapi = ["fastapi>=0.100", "orjson>=3.9"]
jsonld = ["PyLD>=3.0"]
sparql = ["sparqlmodel>=0.13.1"]
shacl = ["pyshacl>=0.29"]
dev = [
    "pytest>=8",
    "pytest-asyncio>=0.24",
    "pytest-cov>=5",
    "pytest-xdist>=3.8",
    "ty>=0.0.37",
    "ruff>=0.4",
    "httpx>=0.27",
    "fastapi>=0.100",
    "orjson>=3.9",
    "aiosqlite>=0.20",
    "greenlet>=3.0",
    "PyLD>=3.0",
    "pyshacl>=0.29",
    "sparqlmodel>=0.13.1",
]

Install examples:

pip install ontosql
pip install ontosql[fastapi]
pip install ontosql[jsonld]
pip install ontosql[sparql]
pip install ontosql[shacl]
pip install -e ".[dev]"

Layer → dependency map

flowchart LR
    Pydantic["Pydantic\nsemantic"]
    SQLModel["SQLModel\nphysical"]
    Session["OntoSession\ncompile"]
    TripleModel["TripleModel\nexport + CURIEs"]
    SparqlModel["SparqlModel\noptional graph"]
    FastAPI["FastAPI\noptional"]

    Pydantic --> Session
    SQLModel --> Session
    Session --> TripleModel
    SparqlModel -.-> TripleModel
    Session --> FastAPI
    TripleModel --> FastAPI

Strategic recommendations

Strongest foundational dependencies:

  • Pydantic (semantic)
  • SQLModel + SQLAlchemy (physical + compile)
  • TripleModel (export + shared RDF stack with SparqlModel)

Highest-value optional integrations:

  • FastAPI + orjson
  • SparqlModel (hybrid SQL + graph)
  • PyLD (framing)
  • pySHACL (validation — ontosql[shacl])

Highest long-term opportunities:

  • OntoSQL ↔ SparqlModel graph sync (shipped in 0.4.0)
  • PydanticAI / Instructor
  • Graph DB adapters
  • Polars for ETL pipelines over semantic rows

OntoSQL should expose semantic model and session APIs; TripleModel remains the RDF implementation detail except when calling to_rdf() / to_jsonld() or using FastAPI negotiation helpers.