Orthograph

Graph data governance for Python: one declared contract for your property graph, continuously checked against your data, your queries, and your live database.

Orthograph is a contract and governance layer for property graph applications — not another graph ORM. Property graphs are schema-flexible by design, so the intended model — which labels exist, which properties are required, what cardinalities hold — is usually never written down anywhere the application can read. Orthograph gives that intent a home: declare the contract once in Python or YAML, then validate data against it, govern a typed Cypher query catalogue, and detect drift as the live database evolves. It sits above your database, driver, and any ORM, and never owns a connection.

pip install orthograph

With Orthograph you can:

  1. Define the contract once — node types, relationship types, properties, and cardinalities — in Python or YAML.

  2. Validate in-memory data against the contract before it touches a database.

  3. Govern a typed Cypher query catalogue — parameters, outputs, language correctness, and domain match, all without executing the queries.

  4. Detect drift between the contract and a whole query set, or a live database, as either evolves.


Quick start

Define the contract:

from typing import Optional

from orthograph.definition import (
    GraphDefinition,
    NodeModel,
    RelationshipModel,
    validate_data,
)

class Person(NodeModel):
    __label__ = "Person"
    __uid_field__ = "name"
    name: str
    born: Optional[int] = None

class Movie(NodeModel):
    __label__ = "Movie"
    __uid_field__ = "title"
    title: str
    year: int

class ActedIn(RelationshipModel):
    __label__ = "ACTED_IN"
    __source_label__ = "Person"
    __target_label__ = "Movie"
    role: str

definition = GraphDefinition(
    name="Filmography",
    node_types=[Person, Movie],
    relationship_types=[ActedIn],
)

Validate in-memory data against the contract before writing to the database:

nodes = [
    {"__label__": "Person", "name": "Alice", "born": 1985},
    {"__label__": "Movie", "title": "Inception", "year": 2010},
]
relationships = [
    {"__label__": "ACTED_IN", "__source_uid__": "Alice",
     "__target_uid__": "Inception", "role": "Lead"},
]

result = validate_data(definition, nodes, relationships)
print(result.is_valid)                    # True / False
for issue in result.issues:
    print(issue.code, issue.message)      # structured, typed error codes

Govern a typed Cypher query — declared parameters, validated against the contract without executing it:

from pydantic import BaseModel

from orthograph.queries import new_catalogue, simple_query, validate_catalogue

class FindPersonParams(BaseModel):
    name: str

catalogue = new_catalogue()
catalogue.register_cypher_query(
    simple_query(
        name="find_person_by_name",
        cypher_template="MATCH (p:Person {name: $name}) RETURN p",
        params=FindPersonParams,
    )
)

# Drift detection: is the whole query set still consistent with the contract?
drift = validate_catalogue(catalogue, definition)
print(drift.is_valid)

Detect drift against a live database (requires the neo4j extra):

from neo4j import GraphDatabase

from orthograph.compare import profile_to_definition
from orthograph.profile import inspect_neo4j

driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))
profile = inspect_neo4j(driver)
result = profile_to_definition(profile, definition)

print(result.is_valid)
for issue in result.issues:
    print(issue.code, issue.message)

What Orthograph does

Define the contract

Declare node types, relationship types, properties, and cardinalities once — in Python or YAML — as the single source of truth. → Tutorials

Validate data

Validate in-memory graph data against the contract before it touches a database. Get a structured result with typed error codes. → How-To

Govern queries

Register typed Cypher queries. Validate parameter and result shapes, language correctness, and domain match against the contract — without executing them. → Reference

Detect drift

Compare a whole query set, or a live database profile, against the contract — so schema evolution never silently desynchronises them from your declared truth. → How-To

Query governance and drift detection are distinct concerns. Governance keeps individual queries honest against the contract at registration time; drift detection answers whether whole sets — the query catalogue, the live database — have diverged from the contract over time.


Where to start

User

Learn by doing. Work through the tutorials to go from zero to a validated graph definition. → Tutorials

Developer

Use Orthograph as a library dependency. Start with How-To guides and the API reference. → How-To · → Reference

Contributor

Understand the design before modifying code. The Explanation section maps the architecture; CONTRIBUTING.md covers setup and the test matrix. → Architecture · → Explanation · → Contributing