A small command-line tool that looks at your ontology file (a formal description of concepts and how they relate) and suggests the best graph style for each concept.
Think of it as a second opinion before you store knowledge in a database or graph system.
Use this tool when you:
- Have an OWL/RDF model (often a
.ttlTurtle file) and need to choose how to store it - Are deciding between a simple hierarchy, a reasoning-friendly semantic graph, a property graph (like Neo4j-style), or a hypergraph
- Are planning a migration and want a quick, per-class / per-property recommendation
- Want a checklist of odd cases (cycles, complex n-ary relations) before you commit to a design
It is not a full database, UI, or automatic migrator. It only advises.
A single ontology file that rdflib can read, for example:
- Turtle (
.ttl) — most common - Other RDF formats such as RDF/XML or N-Triples (by file type)
The file should describe classes (kinds of things) and properties (relationships or attributes).
For every class and property in the file, it recommends one of these shapes:
| Recommendation | Plain-English meaning |
|---|---|
| Taxonomy (DAG) | A simple “is-a” hierarchy (like Product → DigitalProduct). Store as a tree/DAG. |
| Semantic graph | Needs OWL-style rules (domain/range, inverses, equivalence, and so on). Keep in RDF/OWL where reasoning matters. |
| Labeled property graph | Simple links and literal values (dates, scores, totals). Good fit for property-graph edges and attributes. |
| Hypergraph | One “helper” class tying three or more things together. Often better as one multi-way edge, not many binary links. |
| Needs review | Signals are mixed or too thin — a person should decide. |
It also flags problems such as cycles in the class hierarchy (A is-a B is-a C is-a A), which should not appear in a clean taxonomy.
A readable report with:
- Kind — class or property
- Name — short name
- Shape — recommended graph style
- Reason — one-line explanation
- A summary count per shape
- Any warnings or cycle errors
graph-shape-advisor analyze path/to/model.ttlExample (taxonomy fixture):
Graph Shape Advisor
Source: tests/fixtures/taxonomy.ttl
Kind Name Shape Reason
class Customer TAXONOMY (DAG) Pure is-a hierarchy - model as a DAG/taxonomy.
class DigitalProduct TAXONOMY (DAG) Pure is-a hierarchy - model as a DAG/taxonomy.
class Order TAXONOMY (DAG) Pure is-a hierarchy - model as a DAG/taxonomy.
class PhysicalProduct TAXONOMY (DAG) Pure is-a hierarchy - model as a DAG/taxonomy.
class Product TAXONOMY (DAG) Pure is-a hierarchy - model as a DAG/taxonomy.
class Thing TAXONOMY (DAG) Pure is-a hierarchy - model as a DAG/taxonomy.
Summary: TAXONOMY (DAG): 6
graph-shape-advisor analyze path/to/model.ttl --explainSame table, with fuller plain-English reasons.
graph-shape-advisor analyze path/to/model.ttl --jsonUseful for scripts, CI, or feeding another tool.
Needs Python 3.11+.
pip install -e .For development (includes tests):
pip install -e ".[dev]"# Install
pip install -e .
# Analyze a model
graph-shape-advisor analyze tests/fixtures/taxonomy.ttl
# With explanations
graph-shape-advisor analyze tests/fixtures/taxonomy.ttl --explain
# As JSON
graph-shape-advisor analyze tests/fixtures/taxonomy.ttl --jsonThis is a heuristic helper, not a formal proof of the “best” design. Real models are often ambiguous. When the tool is unsure, it says needs review instead of guessing.
Treat the output as a starting point for modeling discussions — not an automatic migration plan.
- ontoguard-ai — semantic firewall using OWL/SHACL validation.
- owl-portability-layer — nine-platform enterprise ontology adapters.
graph-shape-advisor helps decide how to model a relation before ontoguard-ai enforces it or owl-portability-layer ports it across platforms.
pytestMIT — see LICENSE.