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:https://schema/module/schema.vektagraf.com/ext/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.