Schema Architecture and Design Rationale
Vektagraf schemas are composed of module schemas and application schemas. This design was chosen for several reasons:
- Composability — Modules encapsulate reusable domain components.
- Namespacing — Modules avoid collision of types and models.
- Incremental evolution — Modules can version independently.
- Clarity — The application schema integrates modules into a coherent domain.
- Deterministic resolution — Imports and references are resolved systematically.
Module Schemas
Module schemas define:
- Reusable type definitions
- Reusable enums
- Reusable models
- Fundamental constraints
- Namespaces
- Cross-module references
These modules behave like packages or libraries in a programming language but are purely declarative and contain no executable code.
Design decision:
Keep modules purely structural. They should not embed behavior, so they remain portable and deterministic.
Example (excerpt only):
{
"$schema": "vektagraf://schema/module/v1",
"namespace": "ecommerce_core",
"types": [
{ "name": "money", "base_type": "json" }
],
"models": { ... }
}
Application Schema
The application schema integrates:
- Models
- Relationships
- Validation
- Provenance
- Vector fields
- File storage fields
- Encryption rules
- Multi-tenancy settings
- System logs, sessions, jobs
- Plugin declarations
- Indexing
Design decision:
The application schema is the single source of truth for the entire backend.
This allows Vektagraf to generate a complete runtime environment without human-written glue code.