Package Exports
- @ontograph/core
- @ontograph/core/src/action-auditor
- @ontograph/core/src/action-engine
- @ontograph/core/src/action-validator
- @ontograph/core/src/builder/builder.test
- @ontograph/core/src/builder/define
- @ontograph/core/src/builder/index
- @ontograph/core/src/codegen/index
- @ontograph/core/src/codegen/type-generator
- @ontograph/core/src/datasource/index
- @ontograph/core/src/datasource/sync-engine
- @ontograph/core/src/datasource/types
- @ontograph/core/src/diff
- @ontograph/core/src/diff.test
- @ontograph/core/src/examples/objects
- @ontograph/core/src/examples/supply-chain-ontology
- @ontograph/core/src/examples/supply-chain/actions
- @ontograph/core/src/examples/supply-chain/advanced-concepts
- @ontograph/core/src/examples/supply-chain/advanced-relations
- @ontograph/core/src/examples/supply-chain/attributes
- @ontograph/core/src/examples/supply-chain/bms/attributes
- @ontograph/core/src/examples/supply-chain/bms/entities
- @ontograph/core/src/examples/supply-chain/bms/events
- @ontograph/core/src/examples/supply-chain/bms/relations
- @ontograph/core/src/examples/supply-chain/constraints
- @ontograph/core/src/examples/supply-chain/entities
- @ontograph/core/src/examples/supply-chain/epcis-events
- @ontograph/core/src/examples/supply-chain/events
- @ontograph/core/src/examples/supply-chain/index
- @ontograph/core/src/examples/supply-chain/oms/attributes
- @ontograph/core/src/examples/supply-chain/oms/entities
- @ontograph/core/src/examples/supply-chain/oms/events
- @ontograph/core/src/examples/supply-chain/oms/relations
- @ontograph/core/src/examples/supply-chain/relations
- @ontograph/core/src/examples/supply-chain/roles
- @ontograph/core/src/examples/supply-chain/rules
- @ontograph/core/src/examples/supply-chain/sustainability
- @ontograph/core/src/examples/supply-chain/sustainability-relations
- @ontograph/core/src/examples/supply-chain/tms/advanced
- @ontograph/core/src/examples/supply-chain/tms/attributes
- @ontograph/core/src/examples/supply-chain/tms/entities
- @ontograph/core/src/examples/supply-chain/tms/events
- @ontograph/core/src/examples/supply-chain/tms/events-enhanced
- @ontograph/core/src/examples/supply-chain/tms/relations
- @ontograph/core/src/examples/supply-chain/value-types
- @ontograph/core/src/examples/supply-chain/views
- @ontograph/core/src/examples/supply-chain/wms/attributes
- @ontograph/core/src/examples/supply-chain/wms/entities
- @ontograph/core/src/examples/supply-chain/wms/events
- @ontograph/core/src/examples/supply-chain/wms/relations
- @ontograph/core/src/exporters/dot-exporter
- @ontograph/core/src/exporters/er-exporter
- @ontograph/core/src/exporters/json-schema-exporter
- @ontograph/core/src/exporters/mermaid-exporter
- @ontograph/core/src/exporters/owl-exporter
- @ontograph/core/src/exporters/shacl-exporter
- @ontograph/core/src/expression/derived-evaluator
- @ontograph/core/src/expression/evaluator
- @ontograph/core/src/expression/evaluator.bench
- @ontograph/core/src/expression/evaluator.test
- @ontograph/core/src/expression/index
- @ontograph/core/src/expression/types
- @ontograph/core/src/index
- @ontograph/core/src/lineage
- @ontograph/core/src/lineage.test
- @ontograph/core/src/object-model
- @ontograph/core/src/object-validator
- @ontograph/core/src/query/filter-types
- @ontograph/core/src/query/index
- @ontograph/core/src/query/neo4j-engine
- @ontograph/core/src/query/neo4j-engine.test
- @ontograph/core/src/query/object-set
- @ontograph/core/src/query/object-set-impl
- @ontograph/core/src/query/query-engine
- @ontograph/core/src/rule-engine
- @ontograph/core/src/rules
- @ontograph/core/src/security/access-controller
- @ontograph/core/src/security/access-controller.test
- @ontograph/core/src/security/index
- @ontograph/core/src/security/types
- @ontograph/core/src/transformer
- @ontograph/core/src/types
- @ontograph/core/src/validation/index
- @ontograph/core/src/validation/shacl-shapes
- @ontograph/core/src/validation/shacl-validator
- @ontograph/core/src/validation/shacl.test
- @ontograph/core/src/validator
- @ontograph/core/src/versioning
- @ontograph/core/src/versioning.test
Readme
@ontograph/core
TypeScript Ontology Framework — Define your world in code
Define entities, relations, constraints and rules in pure TypeScript — no XML, no Turtle, no OWL. One definition → OWL 2, SHACL, Neo4j Cypher, JSON Schema, Mermaid diagrams.
Inspired by Palantir Ontology, built for the open-source world.
Single runtime dependency: zod
✨ 10-Second Wow
import { defineEntity, defineRelation, MermaidExporter, OWLExporter, JsonSchemaExporter } from "@ontograph/core";
const warehouse = defineEntity("sc:Warehouse", { label: { en: "Warehouse" }, kind: "entity" })
.attr("sc:capacity", { required: true })
.build();
const product = defineEntity("sc:Product", { label: { en: "Product" }, kind: "entity" })
.attr("sc:sku", { identity: true, required: true })
.build();
const storedIn = defineRelation("sc:storedIn", { label: { en: "stored in" } }, "sc:Product", "sc:Warehouse");One ontology, multiple outputs:
| Format | What you get |
|---|---|
new MermaidExporter(ontology).export() |
📊 Mermaid classDiagram — renders in GitHub README |
new OWLExporter(ontology).export() |
🦉 OWL 2 Turtle — W3C standard |
new SHACLExporter(ontology).export() |
✅ SHACL Shapes — W3C validation |
new JsonSchemaExporter(ontology).exportString() |
📋 JSON Schema Draft 2020-12 |
new DotExporter(ontology).export() |
🔵 Graphviz DOT — publication-quality diagrams |
new Neo4jSchemaGenerator().generateConstraintCypher(...) |
🗄️ Neo4j Cypher DDL |
Why @ontograph/core?
| Traditional approach | @ontograph/core |
|---|---|
| OWL/RDF XML configuration, steep learning curve | TypeScript native, IDE autocompletion |
Runtime eval() evaluation, injection risk |
Expr AST safe evaluation, zero eval |
| No type constraints, errors only at runtime | End-to-end type safety, compile-time caught |
| Coupled to specific graph databases | Abstract query layer, pluggable engines |
| Write your own permission logic | Built-in RBAC + row-level security |
| No visualization tooling | Mermaid + DOT + ER diagram export |
Features
- 🏗️ Type-safe ontology modeling — Entity, Relation, Attribute, Constraint with full TypeScript inference
- 🔒 Expr AST safe evaluation — Pure function recursion, no
eval/new Function, prototype pollution and injection prevention - 🔍 Abstract query engine — FilterOp → ObjectSet → Neo4j Cypher compilation
- 🛡️ RBAC access control — Deny-first policy with row-level security conditions
- ✅ SHACL validation — W3C standard Shapes generation and validation
- 🔗 Datasource mapping — Field mapping + SyncEngine + NaN-safe conversion
- 🔧 Fluent Builder API —
defineEntity().attr().rel().constraint().build() - 📦 Multi-format export — OWL 2, SHACL, JSON Schema, Mermaid, DOT, ER diagram
- 📊 Version management & Diff — Ontology versioning and structural diff
- 🕸️ Lineage tracking — Full lineage from datasources to entities
- 🏭 Supply chain reference — 350+ pre-built supply chain ontology (TMS/WMS/OMS/BMS)
Installation
bun add @ontograph/core
# or
npm install @ontograph/coreQuick Start
Define a supply chain ontology
import {
defineEntity,
defineRelation,
OntologyValidator,
Neo4jSchemaGenerator,
} from "@ontograph/core";
// 1. Define entities with the Builder API
const warehouse = defineEntity("sc:Warehouse", {
label: { en: "Warehouse", zh: "仓库" },
kind: "entity",
})
.attr("sc:capacity", { identity: false, required: true })
.attr("sc:location", { required: true })
.rel("sc:stores", { min: 0, max: null })
.constraint("sc:PositiveCapacity")
.build();
const product = defineEntity("sc:Product", {
label: { en: "Product", zh: "产品" },
kind: "entity",
})
.attr("sc:sku", { identity: true, required: true })
.attr("sc:weight", { required: false })
.build();
// 2. Define relations
const storedIn = defineRelation(
"sc:storedIn",
{ label: { en: "stored in" } },
"sc:Product",
"sc:Warehouse",
);
// 3. Validate the ontology
const validator = new OntologyValidator();
const result = validator.validate([warehouse, product], [storedIn]);
if (!result.valid) {
console.error("Validation errors:", result.errors);
}
// 4. Generate Neo4j constraints
const generator = new Neo4jSchemaGenerator();
const cypher = generator.generateConstraintCypher([warehouse, product]);
// → CREATE CONSTRAINT FOR (n:Warehouse) REQUIRE n['@id'] IS UNIQUE ...Safe expression evaluation
import { SafeExpressionEvaluator } from "@ontograph/core";
const evaluator = new SafeExpressionEvaluator();
const expr = {
type: "compare",
op: "gt",
left: { type: "property", path: "quantity" },
right: { type: "literal", value: 100 },
};
const result = evaluator.evaluate(expr, { quantity: 150 });
// → true (pure function recursion, no eval, max depth 50)RBAC access control
import { AccessController } from "@ontograph/core";
const ac = new AccessController({ defaultPolicy: "deny" });
ac.registerRoles([
{
"@id": "role:warehouse-manager",
label: { en: "Warehouse Manager" },
rules: [
{ resource: "objectType", resourceRef: "*", permissions: ["view", "create", "edit"], effect: "allow" },
{ resource: "objectType", resourceRef: "sc:Warehouse", permissions: ["delete"], effect: "deny" },
],
},
]);
const check = ac.check("user:1", ["role:warehouse-manager"], "edit", "objectType", "sc:Warehouse");
// → { allowed: true, matchedRule: "role:warehouse-manager" }
const deny = ac.check("user:1", ["role:warehouse-manager"], "delete", "objectType", "sc:Warehouse");
// → { allowed: false, reason: "Explicitly denied by rule" }Multi-Format Export
Mermaid (renders in GitHub)
import { MermaidExporter } from "@ontograph/core";
const mermaid = new MermaidExporter(ontology).export();
// Paste into GitHub README → instant visual diagramOWL 2 / SHACL
import { OWLExporter, SHACLExporter } from "@ontograph/core";
const owl = new OWLExporter(ontology).export(); // → Turtle format
const shacl = new SHACLExporter(ontology).export(); // → SHACL TurtleJSON Schema
import { JsonSchemaExporter } from "@ontograph/core";
const schema = new JsonSchemaExporter(ontology).exportString();
// → JSON Schema Draft 2020-12 with all entity types in $defsGraphviz DOT
import { DotExporter } from "@ontograph/core";
const dot = new DotExporter(ontology, { layout: "fdp", direction: "LR" }).export();
// → Paste into any Graphviz rendererAPI Overview
| Module | Entry | Description |
|---|---|---|
| Core types | types |
EntityType, RelationType, AttributeDefinition, Constraint |
| Builder API | builder |
defineEntity, defineRelation, defineAttribute |
| Expression evaluation | expression |
SafeExpressionEvaluator, DerivedAttributeEvaluator |
| Query engine | query |
FilterOp, ObjectSet, Neo4jQueryEngine |
| RBAC security | security |
AccessController, RoleDefinition |
| SHACL validation | validation |
SHACLShapeGenerator, SHACLValidator |
| Datasource mapping | datasource |
SyncEngine, DatasourceDefinition |
| OWL export | exporters/owl-exporter |
OWL 2 / JSON-LD output |
| SHACL export | exporters/shacl-exporter |
SHACL Shapes JSON-LD |
| Mermaid export | exporters/mermaid-exporter |
Mermaid classDiagram / graph / flowchart |
| DOT export | exporters/dot-exporter |
Graphviz DOT format |
| ER diagram | exporters/er-exporter |
Mermaid erDiagram |
| JSON Schema | exporters/json-schema-exporter |
JSON Schema Draft 2020-12 |
| Code generation | codegen |
TypeGenerator |
| Rule engine | rule-engine |
RuleEngine (Expr-first evaluation) |
| Version management | versioning |
VersionManager |
| Structural Diff | diff |
DiffEngine |
| Lineage tracking | lineage |
LineageTracker |
Architecture
@ontograph/core
│
├── 📐 Modeling Layer
│ ├── types.ts ── Core type definitions
│ ├── builder/ ── Fluent Builder API
│ └── validator.ts ── Ontology validation
│
├── ⚡ Execution Layer
│ ├── expression/ ── Expr AST + safe evaluator (LRU cache)
│ ├── rule-engine.ts ── Rule engine (Expr-first)
│ └── action-engine.ts ── Action engine
│
├── 🔍 Query Layer
│ ├── query/ ── FilterOp → ObjectSet → Cypher
│ └── datasource/ ── Datasource mapping + SyncEngine
│
├── 🛡️ Security Layer
│ └── security/ ── RBAC AccessController (deny-first)
│
├── ✅ Standards Layer
│ ├── validation/ ── W3C SHACL generation + validation
│ └── exporters/ ── OWL 2 · SHACL · Mermaid · DOT · ER · JSON Schema
│
├── 🔧 Tooling
│ ├── codegen/ ── TypeScript type generation
│ ├── versioning.ts ── Version management
│ ├── diff.ts ── Structural diff
│ └── lineage.ts ── Lineage tracking
│
└── 📦 Examples
└── examples/supply-chain/ ── 350+ supply chain ontology definitionsComparison
| Feature | @ontograph/core | Palantir Ontology | OWL API (Java) |
|---|---|---|---|
| Language | TypeScript | TypeScript (closed source) | Java |
| Open source | ✅ MIT | ❌ | ✅ |
| Type safety | ✅ Compile-time | ✅ | ❌ Runtime |
| Safe evaluation | ✅ Expr AST | ✅ | N/A |
| SHACL | ✅ | ❌ | ✅ |
| OWL export | ✅ | ❌ | ✅ |
| JSON Schema export | ✅ | ❌ | ❌ |
| Mermaid visualization | ✅ | ❌ | ❌ |
| Builder API | ✅ | ✅ | ❌ |
| RBAC | ✅ | ✅ | ❌ |
| Neo4j integration | ✅ | ❌ | ❌ |
| Runtime dependencies | zod | Dozens | Heavyweight |
Development
bun install # Install dependencies
bun run typecheck # Type check (tsc --noEmit)
bun run build # Build to dist/
bun run test # Run tests
bun run lint # Lint with Biome
bun run lint:fix # Lint and auto-fix
bun run format # Format codeContributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
License
MIT © OntoGraph Contributors