Modelable

Modelable is a compiler and language server for versioned, domain-owned data models. Define canonical models and projections in .mdl files, then validate their compatibility, inspect field-level lineage, detect governance gaps, and generate artifacts for the systems that consume them.

Why Modelable?

Data contracts often become fragmented across application types, database schemas, API definitions, and catalog metadata. Modelable keeps the semantic contract in one versioned source and derives target-specific representations without losing ownership, classification, lineage, or compatibility context.

.mdl sources -> validate and resolve -> plan and govern -> generate artifacts

How it fits together

A canonical entity, its compiler-expanded db/request/reply/event projections, a hand-authored cross-domain projection, and the artifacts and (deferred) streaming path they can drive:

flowchart TB
    subgraph CUSTOMER["Domain: customer (owner: customer-platform)"]
        V1["entity Customer @1<br/>additive"] --> V2["entity Customer @2<br/>additive"]
    end

    subgraph AUTO["Auto projections — compiler-expanded from Customer @2"]
        direction LR
        DB["CustomerDb @2<br/>persistence contract"]
        REQ["CustomerRequest @2<br/>write model"]
        REP["CustomerReply @2<br/>read model"]
        EVT["CustomerEvent @2<br/>created / updated / deleted"]
    end

    V2 --> DB
    V2 --> REQ
    V2 --> REP
    V2 --> EVT

    subgraph BILLING["Domain: billing (owner: billing-platform)"]
        JOIN["projection BillingCustomer @1<br/>from customer.Customer @2 as c<br/>join orders.Order @3 as o"]
    end

    V2 -. "field-level lineage" .-> JOIN

    subgraph PIPE["Compiler pipeline"]
        direction LR
        PARSE["Parse .mdl"] --> VALIDATE["Validate, resolve versions,<br/>check compatibility"] --> PLAN["Plan document (JSON)"]
    end

    DB --> PARSE
    REQ --> PARSE
    REP --> PARSE
    EVT --> PARSE
    JOIN --> PARSE

    subgraph ARTIFACTS["Generated artifacts"]
        direction LR
        JSONSCHEMA["JSON Schema"]
        TYPES["TypeScript, C#, Java,<br/>Python, Rust, Go"]
        SQLDDL["SQL DDL,<br/>dbt schema.yml"]
        PROTO["Protobuf / gRPC"]
        GOV["OpenLineage, OpenMetadata,<br/>ODCS, FHIR R4"]
    end

    PLAN --> JSONSCHEMA
    PLAN --> TYPES
    PLAN --> SQLDDL
    PLAN --> PROTO
    PLAN --> GOV

    subgraph FUTURE["Streaming runtime — Phase 5, deferred, not implemented"]
        direction LR
        ENVELOPE["Change event envelope"] --> SUBSCRIPTION["Subscription"] --> MATERIALIZED["Materialized replica<br/>Postgres / Kafka"]
    end

    EVT -.-> ENVELOPE

Loading

Everything above the "Streaming runtime" box is implemented by the local compiler today. subscription, adapter-driven materialization, and the runtime engine parse and validate but do not execute yet — see Architecture and system specification for the exact implemented/deferred boundary of every concept in the diagram.

Install

Modelable requires Python 3.14.

uv tool install modelable
modelable --version

For an isolated one-off command:

uvx modelable --help

Define a model

domain customer {
  owner: "customer-platform"

  entity Customer @ 1 (additive) {
    @key customerId: uuid
    @pii email?: string
    displayName: string
  }
}

Save the definition as customer.mdl, then validate and compile it:

modelable validate customer.mdl --strict
modelable compile customer.mdl --target json-schema --out generated/schema
modelable compile customer.mdl --target typescript --out generated/types

Capabilities

• Parse and validate versioned models, projections, annotations, and workspace definitions.
• Resolve exact versions and compatible version ranges.
• Detect additive and breaking contract changes and affected projections.
• Trace projection fields to canonical source fields.
• Report structurally missing access and classification metadata.
• Expand automatic database, request, reply, and event projections.
• Generate JSON Schema, Markdown, TypeScript, C#, Java, Python, Rust, Go, SQL DDL, dbt schema.yml, FHIR R4 profile, OpenMetadata JSON, and OpenLineage event, ODCS, Protobuf, and Scalable-oriented gRPC artifacts.
• Provide diagnostics, completion, hover, navigation, references, rename, formatting, and other editor features through the language server.
• Import or assist with models through optional LLM provider integrations.

The local compiler and language-server toolchain are the supported 1.0 stable surface. Apicurio JSON Schema artifact publish/pull and Marquez-compatible OpenLineage event sync are available for derived artifacts. Live catalog publishing, distributed synchronization, OpenLineage runtime event collection, and runtime materialization remain future candidates.

Browser playground

The static Modelable playground runs the compiler locally in the browser. Its Phase 3a workspace supports creating, importing, renaming, deleting, selecting, and editing multiple .mdl files, then validates or generates JSON Schema from the complete workspace.

The one local workspace is restored automatically from IndexedDB. Source text never leaves the page; compiler output is not persisted. If browser storage is unavailable, editing continues in memory with an explicit status. Invalid or incompatible stored data is left untouched until the user exports it or resets the workspace. Protocol v2 now provides 300 ms live diagnostics plus browser-native completion, hover, go-to-definition, references, and rename over the complete local workspace. These can use the last parseable semantic snapshot while current text contains a syntax error; stale results are discarded. Diagnostics, completion results, and hover content remain derived in-memory state and are never persisted.

1.0 stable surface

Modelable 1.0 stabilizes the local compiler and language-server toolchain.

In scope for 1.0:

• .mdl language: syntax, types, projections, ownership, classification, and access metadata.
• CLI: validate, compile, check, generate, attach, spec, and the language server.
• Generated artifacts: JSON Schema, TypeScript, C#, Java, Python, Rust, Go, SQL DDL, dbt schema.yml, Markdown, FHIR R4 profile, OpenMetadata JSON, OpenLineage event, ODCS, Protobuf, and Scalable-oriented gRPC formats.
• Compatibility, lineage, and governance report output.
• Apicurio JSON Schema registry artifact push/pull.
• Marquez-compatible OpenLineage event sync via modelable sync --lineage.
• VS Code extension shipped as a VSIX companion artifact with the 1.0 release.

Deferred from 1.0:

• VS Code Marketplace distribution (post-1.0).
• Live OpenMetadata catalog synchronization and runtime OpenLineage collection.
• Remote tracked-spec polling and authenticated source access.
• Runtime subscriptions, adapters, replay, and materialization.
• Distributed registry synchronization beyond the current file-first model.

Development

cd cli
uv sync --extra dev --frozen
uv run pytest tests/ --tb=short
uv run modelable validate ../samples/mvp --strict

See CONTRIBUTING.md for the complete contributor workflow.

Documentation

Hosted: https://ktjn.github.io/modelable/

• Documentation index
• Language reference
• Tooling reference
• Architecture and system specification
• Getting started and migration
• Sample models
• Changelog
• Roadmap
• Project governance

License

Licensed under the Apache License 2.0.