ggen
Ontology-Driven Code Generation Framework
Define your domain once in RDF. Generate type-safe code everywhere.
Transform RDF/OWL ontologies into polyglot code using SPARQL queries and Tera templates. Generate consistent, type-safe code across Rust, TypeScript, Python, JavaScript, Go, and more—all from a single source of truth.
v4.0.0 | Deterministic | Type-Safe | Production-Ready | 1,168 Tests Passing
What is ggen?
ggen treats software artifacts as projections of knowledge graphs. Unlike traditional code generators that use string templates, ggen:
- Models domains in RDF/OWL — Standard, queryable ontologies
- Queries with SPARQL — Extract patterns like SQL for graphs
- Projects to any language — Type-safe Rust, TypeScript, Python, etc.
- Guarantees reproducibility — Same input → same output, always
The Result: One ontology → Many languages → Perfect consistency
Schema.org Person Ontology (RDF)
↓ SPARQL Query
┌────┴────┬────────┬────────┐
↓ ↓ ↓ ↓
Rust TypeScript Python Go
struct interface class struct
+ Serde + Zod + Pydantic + JSON tags
Why this matters:
- No more type drift between frontend/backend
- Single domain model, infinite projections
- Ontology changes propagate everywhere automatically
- Standards-based (RDF, SPARQL, OWL)
⚡ Quick Win (60 Seconds)
See the power of ontology-driven generation with one command:
Input: Schema.org Product ontology
@prefix schema: <https://schema.org/> .
schema:Product a rdfs:Class ;
rdfs:label "Product" ;
schema:property schema:name, schema:price, schema:description .
schema:name a rdf:Property ;
rdfs:range schema:Text .
schema:price a rdf:Property ;
rdfs:range schema:Number .
Command:
Output: Type-safe TypeScript + Zod validation
import { z } from 'zod';
// Generated from Schema.org Product ontology
export const ProductSchema = z.object({
name: z.string(),
price: z.number(),
description: z.string().optional(),
});
export type Product = z.infer<typeof ProductSchema>;
// Auto-generated validation
export function validateProduct(data: unknown): Product {
return ProductSchema.parse(data);
}
The magic: Change the ontology once → regenerate → all languages update automatically. Zero manual sync.
🆚 Comparison
ggen vs. Traditional Approaches
| Aspect | Manual Coding | String Templates | ggen (Ontology-Driven) |
|---|---|---|---|
| Type Safety | ❌ Manual sync required | ❌ No type checking | ✅ Guaranteed by ontology |
| Cross-Language | ❌ Rewrite for each language | ⚠️ Templates per language | ✅ One ontology, any language |
| Consistency | ❌ Drift over time | ⚠️ Partial (template only) | ✅ Mathematically guaranteed |
| Maintainability | ❌ High (N × M problem) | ⚠️ Medium (M templates) | ✅ Low (1 ontology) |
| Standards-Based | ❌ Custom schemas | ❌ Proprietary | ✅ RDF, SPARQL, OWL |
| Queryable | ❌ No | ❌ No | ✅ SPARQL queries |
| Reproducible | ❌ No | ⚠️ Maybe | ✅ Cryptographically verified |
| Learning Curve | Low | Medium | Medium-High |
| Best For | One-off scripts | Simple scaffolding | Production systems |
The N × M Problem: With manual coding, you need N types × M languages = exponential work. With ggen: 1 ontology → infinite projections.
🗺️ Documentation Navigator
This README is Reference material (information-oriented lookup). Choose your path based on your goal:
📖 Learn by Doing
Goal: Get hands-on experience Path: Getting Started Guide → 10-Minute Tutorial Time: 30-60 minutes Outcome: Working code generation from RDF ontologies
🛠️ Solve a Specific Problem
Goal: Complete a task right now Path: How-to Guides Time: 5-15 minutes per guide Popular tasks:
💡 Understand the Concepts
Goal: Learn the "why" and "how" Path: Explanations Time: 15-30 minutes per topic Core concepts:
📋 Look Up Technical Details
Goal: Find specific information You're here! Browse sections below:
- Installation — Platform-specific installation
- CLI Reference — All commands with examples
- Architecture — System design and components
- Configuration — TOML config files
- Performance — Benchmarks and SLOs
Installation
Prerequisites
- Rust 1.74+ (for building from source or Cargo install)
- macOS/Linux/Windows (full platform support)
Method 1: Homebrew (macOS/Linux)
Method 2: Cargo (Cross-platform)
Method 3: From Source
Quick Verification (30 seconds)
Confirm ggen works on your system:
# 1. List built-in templates (22 available)
# 2. Load an RDF ontology
# 3. Query with SPARQL
✅ All commands succeeded? You're ready to go! 📖 Next step: 10-Minute Tutorial
CLI Reference
Template Management
# List all 22 built-in templates
# Show template details (variables, metadata)
# Validate template syntax
# Create new template
RDF Graph Operations
# Load ontology (Turtle, RDF/XML, N-Triples)
# Execute SPARQL query
# Export graph to file
# Visualize ontology structure
Ontology Processing
# Extract schema from RDF/OWL file
# Generate code from ontology
# Validate ontology quality
# Initialize new ontology project
Project Scaffolding
# Initialize project with preset
# Generate from template with variables
# Watch for changes (auto-regenerate)
# Generate project plan (preview)
# Apply generation plan
AI-Powered Generation
# Interactive chat
# Generate code with AI
# Analyze existing code
Marketplace
# Search template packages
# Install package
# Publish your package
# View package info
Full command reference: Complete CLI Documentation
Architecture
System Overview
┌─────────────────────────────────────────────────────────┐
│ ggen Architecture │
├─────────────────────────────────────────────────────────┤
│ │
│ User Input (CLI) │
│ ↓ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ ggen-cli │ ───→ │ ggen-domain │ (Pure Logic) │
│ └──────────────┘ └──────────────┘ │
│ ↓ ↓ │
│ ┌──────────────────────────────────────┐ │
│ │ ggen-core (Engine) │ │
│ ├──────────────────────────────────────┤ │
│ │ • RDF Triplestore (Oxigraph) │ │
│ │ • SPARQL Query Engine │ │
│ │ • Template Renderer (Tera) │ │
│ │ • Code Generation Pipeline │ │
│ └──────────────────────────────────────┘ │
│ ↓ │
│ Generated Code (Rust, TypeScript, Python, ...) │
│ │
└─────────────────────────────────────────────────────────┘
Workspace Crates (14)
Core Engine
ggen-core— RDF engine, SPARQL queries, template system (heart of ggen)ggen-domain— Pure business logic (no I/O, framework-agnostic)
Interface Layer
ggen-cli— Command-line interface (clap-noun-verb auto-discovery)ggen-node— Node.js FFI bindings (JavaScript/TypeScript integration)
Feature Modules
ggen-ai— AI integration (genai multi-provider wrapper)ggen-marketplace— Package registry (RDF metadata, post-quantum signatures)
Configuration & Validation
ggen-config— Configuration parser (ggen.toml, gpack.toml)ggen-config-clap— CLI config integrationggen-cli-validation— Input validation and safety checks
Development Tools
ggen-utils— Shared utilities (error handling, logging, git hooks)ggen-macros— Procedural macros (compile-time code generation)ggen-dod— Definition of Done (observability, MAPE-K governance)ggen-test-audit— Test quality auditing (coverage, quality metrics)ggen-test-opt— Test optimization (parallel execution, performance)
Assets
templates/— 22 built-in templates (Rust, TypeScript, Python, etc.)examples/— 48 working examples across all featurestests/— 1,168 integration tests (100% passing)docs/— Diataxis-structured documentation
Technology Stack
| Layer | Technology | Purpose |
|---|---|---|
| Language | Rust 1.74+ (edition 2021) | Type safety, zero-cost abstractions, memory safety |
| RDF Store | Oxigraph 0.5 | SPARQL 1.1 compliant triplestore |
| Templates | Tera 1.20 | Jinja2/Liquid-like syntax with RDF integration |
| CLI | clap-noun-verb 5.3.2 | Plugin-style command auto-discovery |
| AI | genai 0.4+ | Multi-provider LLM support (OpenAI, Anthropic, Ollama) |
| Async | tokio 1.47+ | High-performance async runtime |
| Crypto | ML-DSA | Post-quantum package signatures |
| Observability | OpenTelemetry | Distributed tracing, metrics, spans |
Design Philosophy
| Principle | Implementation |
|---|---|
| Type-First Thinking | Express invariants in types, validate at compile-time |
| Zero-Cost Abstractions | Generics over trait objects, monomorphization |
| Deterministic Outputs | Same inputs → identical outputs (cryptographic hashing) |
| Memory Safety | Rust ownership, no GC pauses, no data races |
| Chicago TDD | State-based testing with real collaborators (no mocks) |
| SPARC Methodology | Specification → Pseudocode → Architecture → Refinement → Completion |
| DfLSS Quality | Design for Lean Six Sigma (prevent defects, not detect) |
📐 Detailed architecture: Architecture Documentation
Configuration
Project Config: ggen.toml
Used for project-wide settings (placed at repository root):
[]
= "my-project"
= "1.0.0"
= "E-commerce domain model"
[]
= "templates/"
= "generated/"
[]
= ["schema/product.ttl", "schema/order.ttl"]
= "turtle" # turtle | rdf-xml | n-triples
[]
= "https://marketplace.ggen.io"
📖 Full reference: ggen.toml Documentation
Package Config: gpack.toml
Used for distributable template packages:
[]
= "rust-microservice-template"
= "2.1.0"
= "Your Name <you@example.com>"
= "Production Rust microservice with OpenTelemetry"
= "MIT"
[]
= [
"service.tmpl",
"dockerfile.tmpl",
"ci.tmpl"
]
[]
= ["ggen >= 4.0.0"]
📖 Full reference: gpack.toml Documentation
Performance
Benchmarks (v4.0.0)
All metrics measured on M1 MacBook Pro, averaged over 1000 runs:
| Metric | SLO Target | Actual | Performance |
|---|---|---|---|
| Template Parsing | <5ms | 115 ns | ✅ 43,480× under budget |
| Incremental Build | <5s | 0.79s | ✅ 6.3× faster than target |
| Cold Startup | <50ms | 2.0ms | ✅ 25× faster than target |
| Binary Size | <5MB | 2.8 MB | ✅ 44% smaller than limit |
| RDF Triple Processing | <10µs | <1µs | ✅ 10× faster than target |
| SPARQL Complex Query | <50ms | <10ms | ✅ 5× faster than target |
| First Build (clean) | <15s | ~12s | ✅ Within target |
| Memory (1K triples) | <100MB | ~45MB | ✅ 55% under budget |
Quality Metrics
- ✅ Tests: 1,168 passing | 0 failing | 10 ignored (optional)
- ✅ Coverage: 80%+ on critical paths (ggen-core, ggen-domain)
- ✅ Linting: Zero clippy warnings (pedantic + nursery enabled)
- ✅ Security: Zero cargo-audit vulnerabilities
📊 Detailed metrics: PERFORMANCE.md
Features
Production-Ready Capabilities
| Feature | Technology | Status |
|---|---|---|
| RDF/OWL Processing | Oxigraph triplestore | ✅ Production |
| SPARQL 1.1 Queries | Full spec compliance | ✅ Production |
| Template Engine | Tera with 22+ templates | ✅ Production |
| Polyglot Generation | Rust, TS, Python, Go, JS | ✅ Production |
| CLI Auto-Discovery | clap-noun-verb pattern | ✅ Production |
| AI Integration | OpenAI, Anthropic, Ollama | ✅ Production |
| Package Marketplace | RDF metadata + ML-DSA signatures | ✅ Production |
| Deterministic Builds | Lockfiles + SHA-256 hashing | ✅ Production |
| Graph Visualization | GraphViz DOT output | ✅ Production |
| Delta Projections | Incremental updates | ✅ Production |
Built-in Templates (22)
Starter Templates
hello.tmpl— Minimal examplerust.tmpl— Rust project scaffoldpython.tmpl— Python project scaffold
Production Templates
rust-service-with-placeholders.tmpl— Microservice with OTELdatabase-with-migrations.tmpl— Schema + migrationssafe-error-handling.tmpl— Result<T, E> patterns
Domain Templates
ai-ontology.tmpl— E-commerce domain exampleai-sparql.tmpl— Complex SPARQL queries
Quality Templates
production-readiness-demo.tmpl— Deployment checklist
View all: Run ggen template list
Use Cases
What ggen Excels At
Type-Safe Multi-Language Development
Input: Schema.org Product ontology (RDF)
Output: • Rust struct with Serde
• TypeScript interface with Zod
• Python Pydantic model
• Go struct with JSON tags
• GraphQL schema
Specific Applications:
-
Full-Stack Type Safety Generate matching types for frontend (TypeScript) and backend (Rust) from one ontology
-
API-First Development Define API contracts in RDF/OWL, generate OpenAPI specs + server stubs + client SDKs
-
Database Schema Management Ontology → SQL migrations + ORM models + repository patterns
-
CLI Tool Scaffolding Generate clap-noun-verb CLIs with auto-discovery and completions
-
Microservices Architecture Consistent service scaffolds (Rust, Docker, CI/CD, OTEL) from templates
-
Knowledge Graph → Code Query existing knowledge graphs (DBpedia, Wikidata) to extract code patterns
Target Users
| Role | Use Case |
|---|---|
| Backend Developers | Generate type-safe APIs from domain ontologies |
| Full-Stack Teams | Eliminate type drift between frontend/backend |
| DevOps Engineers | Scaffold microservices with consistent structure |
| Data Engineers | Transform RDF knowledge graphs into queryable APIs |
| AI/ML Engineers | Integrate LLMs into code generation workflows |
| OSS Maintainers | Distribute template packages via marketplace |
| Enterprise Architects | Implement ontology-driven system architecture |
Examples
Browse examples/ directory (48 working projects):
| Category | Count | Examples |
|---|---|---|
| Basic | 8 | basic-template-generation/, simple-project/ |
| Advanced | 12 | advanced-rust-api-8020/, advanced-sparql-graph/ |
| AI Integration | 6 | ai-code-generation/, ai-microservice/ |
| CLI Tools | 7 | clap-noun-verb-demo/, cli-advanced/ |
| Lifecycle | 4 | lifecycle-complete/, advanced-lifecycle-demo/ |
| Ontologies | 5 | knowledge-graph-builder/, fastapi-from-rdf/ |
| SPARQL | 3 | sparql-engine/, advanced-sparql-graph/ |
| Full-Stack | 3 | comprehensive-rust-showcase/, microservices-architecture/ |
Each example includes:
- ✅ Working code (tested in CI)
- ✅ README with explanation
- ✅ Sample ontology/templates
- ✅ Expected output
🔍 Browse examples: examples/
🌐 Community & Ecosystem
Related Projects
Official Ecosystem:
- ggen-templates — Curated community template collection
- ggen-vscode — VS Code extension (syntax highlighting, snippets)
- ggen-playground — Browser-based playground for experimentation
Integrations:
- Schema.org — Use official schemas directly
- FOAF — Friend-of-a-Friend ontology support
- Dublin Core — Metadata standards integration
- Oxigraph — High-performance RDF triplestore
- Tera — Jinja2/Liquid-like template engine
Community Tools (via marketplace):
- graphql-to-rdf — Convert GraphQL schemas to RDF
- openapi-to-rdf — OpenAPI → RDF ontology converter
- rdf-visualizer — Interactive ontology browser
- ggen-watch — Advanced file watcher with smart regeneration
Getting Help
| Channel | Purpose | Response Time |
|---|---|---|
| 📚 Documentation | Self-service guides | Immediate |
| 💬 GitHub Discussions | Q&A, ideas, show & tell | <24 hours |
| 🐛 GitHub Issues | Bug reports, feature requests | <48 hours |
| 📖 Examples | Working code samples | Immediate |
Before asking:
- Check the FAQ below
- Search existing discussions
- Try the 10-minute tutorial
Contributing
We welcome contributions! Here's how to get involved:
Code Contributions:
- 🐛 Fix bugs (check good first issue)
- ✨ Add features (discuss in Discussions first)
- 📝 Improve docs (especially examples!)
- 🧪 Write tests (increase coverage)
Non-Code Contributions:
- 🎨 Create templates (publish to marketplace)
- 📚 Write tutorials or blog posts
- 🗣️ Give talks or presentations
- 🌍 Translate documentation
Quick start: See CONTRIBUTING.md for full guidelines.
Development
For Contributors
Essential Reading (in order):
- CONTRIBUTING.md — Workflow, PR guidelines, code of conduct
- CLAUDE.md — Development constitution (SPARC + Chicago TDD + DfLSS)
- TESTING.md — Testing philosophy and requirements
Quick Reference
# Development cycle
# Before commit
# CI simulation
Spec-First Workflow (Required)
ggen uses GitHub Spec Kit for all features:
# One-time setup
# For each feature
# All specs: .specify/specs/NNN-feature-name/
# Evidence: .specify/specs/NNN-feature/evidence/
Branch naming: NNN-feature-name (e.g., 042-shacl-validation)
Evidence required: Tests + benchmarks + OTEL spans
Constitution: .specify/memory/constitution.md
Development Principles
- ✅ ALWAYS use
cargo make(never directcargocommands) - ✅ Chicago TDD: State-based tests with real collaborators (no mocks)
- ✅ No
unwrap()/expect()in production code (useResult<T, E>) - ✅ Type-first: Express invariants in types, not runtime checks
- ✅ Stop on errors: Andon signal (RED/YELLOW/GREEN status)
Links
- 📦 Crates.io: https://crates.io/crates/ggen-cli-lib
- 🐙 GitHub: https://github.com/seanchatmangpt/ggen
- 🐛 Issues: https://github.com/seanchatmangpt/ggen/issues
- 💬 Discussions: https://github.com/seanchatmangpt/ggen/discussions
- 📚 Documentation: docs/
License
MIT License — see LICENSE for details
❓ FAQ
Traditional generators (Yeoman, Plop, Hygen) use string templates with variable substitution. They can't:
- Understand relationships between types
- Query your domain model
- Guarantee consistency across languages
- Leverage existing ontologies (Schema.org, FOAF)
ggen treats your domain as a knowledge graph. You can query it with SPARQL, traverse relationships, and generate code that respects your domain's semantics.
Example: Traditional tools can't automatically generate matching validation rules for a "Person must have at least one email" constraint. ggen extracts this from OWL restrictions.
Short answer: No, to get started. Yes, to unlock full power.
Getting started (no RDF knowledge needed):
- Use
ggen template listto see built-in templates - Generate from existing Schema.org ontologies
- Scaffold projects with presets
Intermediate (basic RDF, ~2 hours learning):
- Create your own domain ontologies in Turtle format
- Use simple SPARQL queries (like SQL)
- Customize templates
Advanced (deep knowledge):
- OWL restrictions for validation rules
- Complex SPARQL queries
- Custom template functions
📚 Resources: RDF for Programmers
Yes! ggen supports several integration patterns:
- Standalone generation: Generate into
generated/directory, import as library - Partial file generation: Use markers like
// BEGIN GENERATED/// END GENERATED - Delta updates: Regenerate only changed parts (incremental)
- Watch mode: Auto-regenerate on ontology changes
Best practice: Treat generated code as read-only. Put custom logic in separate files that import generated code.
Built-in templates: Rust, TypeScript, Python, JavaScript, Go
Easy to add: Any language via Tera templates. Community templates available for:
- Java
- C#
- GraphQL schemas
- OpenAPI specs
- SQL migrations
- Kubernetes manifests
Template marketplace: Browse community templates with ggen marketplace search
Blazing fast (see Performance):
- Template parsing: 115 nanoseconds
- Simple generation: <100ms
- Complex ontology (1000+ classes): <2 seconds
- Incremental updates: <100ms
Why so fast? Rust, zero-copy parsing, HNSW indexing for SPARQL, template caching.
Yes. ggen v4.0.0 is production-ready:
- ✅ 1,168 passing tests (0 failures)
- ✅ 80%+ code coverage on critical paths
- ✅ Zero clippy warnings (pedantic mode)
- ✅ Zero security vulnerabilities (cargo-audit)
- ✅ Deterministic builds (lockfiles + SHA-256)
- ✅ Semantic versioning commitment
- ✅ Used in production by early adopters
Stability: Core APIs stable. Marketplace and AI features actively evolving.
From manual coding:
- Model your types in RDF/OWL (start simple, use Schema.org types)
- Generate code with
ggen ontology generate - Replace manual types incrementally
From GraphQL codegen:
- Convert GraphQL schema to RDF (tool:
graphql-to-rdf) - Use ggen to generate types + resolvers
- Bonus: Generate other languages from same ontology
From Prisma/TypeORM:
- Model database in RDF ontology
- Generate both schema migrations + ORM types
- Keep database + application in sync
📖 Migration guides: docs/how-to/migration/
Absolutely! We welcome community templates.
Process:
- Create your template package (
gpack.toml) - Test thoroughly (
ggen template lint) - Publish:
ggen marketplace publish - (Optional) Submit to curated list via PR
Popular needs:
- Industry-specific ontologies (healthcare, finance, IoT)
- Framework-specific generators (Django, Rails, Spring)
- Infrastructure templates (Terraform, CloudFormation)
💡 Guide: Creating Marketplace Packages
Timeline (for developers comfortable with types):
- Day 1: Install, run quick start, understand basic flow (2 hours)
- Week 1: Create first ontology, generate TypeScript + Rust (5 hours)
- Month 1: Proficient with RDF, SPARQL, custom templates (20 hours)
- Month 3: Advanced patterns, marketplace publishing (40 hours)
Compared to:
- Easier than: Learning GraphQL from scratch
- Similar to: Learning Terraform or Kubernetes basics
- Harder than: Using Yeoman or Plop
Payoff: Scales exponentially. One ontology → infinite languages.
Why ggen?
Traditional code generators: String templates + search-replace = fragile, inconsistent, hard to maintain
ggen philosophy:
- ✅ Ontologies define domain truth (not brittle templates)
- ✅ SPARQL extracts patterns (not regex/string manipulation)
- ✅ Type systems enforce correctness (compile-time, not runtime)
- ✅ Determinism guarantees reproducibility (cryptographic hashing)
- ✅ Standards-based interoperates with existing ontologies (Schema.org, FOAF, Dublin Core)
The paradigm shift:
Old Way: Code → Templates → More Code (copy/paste hell)
New Way: Ontology → SPARQL → Projections (single source of truth)
Result: Code generation that feels like compilation, not macro expansion.
📖 Learn more: Explanations
Built with Rust 🦀 | Powered by RDF 🔗 | Tested with 1,168 passing tests ✅
Deterministic. Ontology-driven. Production-ready.
ggen v4.0.0 — Define once. Generate everywhere.