What is Modality?

Modality is a data modeling framework that helps teams define, document, and govern their data models using a simple, version-controlled language called MML (Modality Modeling Language). By bridging high-level design decisions with implementation details, MML enables both engineers and AI agents to transform conceptual data models directly into transformation and semantic layers—making design an active participant in implementation rather than static documentation. Access your models through Git, MCP servers, or APIs.

Overview

In modern data organizations, understanding how data flows through systems, how metrics are calculated, and how entities relate to each other is critical. Modality provides a single source of truth for your data model, making it easy to:

• Document your data architecture
• Define business metrics consistently
• Visualize data relationships
• Version control your data model
• Generate documentation automatically
• Ensure governance and compliance

The Problem

Data teams face several common challenges:

• Scattered Documentation: Data definitions live in wikis, spreadsheets, and tribal knowledge
• Metric Inconsistency: Different teams calculate the same metrics differently
• Complex Dependencies: Hard to understand what data depends on what
• Governance Gaps: Difficult to track changes and maintain compliance
• Onboarding Friction: New team members struggle to understand the data model

The Solution

Modality addresses these challenges by providing:

1. Declarative Language: Define your data model in simple, readable MML files
2. Version Control: Track changes using Git, just like code
3. Automatic Documentation: Generate beautiful docs from your model
4. Visual Diagrams: See your data relationships at a glance
5. Validation: Catch errors and inconsistencies early
6. Integration: Connect to your existing tools and workflows

Key Features

Simple, Readable Syntax

MML is designed to be human-readable and easy to learn:

domain sales {
  name = "Sales"
  description = "Sales and revenue tracking"
}

entity customer {
  type = "dimension"
  description = "Customer master data"

  belongs-to domain.sales
}

entity total_revenue {
  type = "metric"
  description = "Total sales revenue"
  business_logic = "SUM(order.total_amount)"

  belongs-to domain.sales
  derived-from entity.order
}

Version Control First

Your data model lives in Git alongside your code:

• Track every change with commits
• Review model changes with pull requests
• Branch for experiments and features
• Roll back to previous versions
• Maintain a complete history

Automatic Documentation

Generate comprehensive documentation automatically:

• Interactive entity catalog
• Relationship diagrams
• Metric definitions and calculations
• Domain organization
• Lineage tracking

Visual Data Lineage

Understand your data dependencies with interactive diagrams:

• See how entities connect
• Trace metric calculations
• Identify downstream impacts
• Visualize domain boundaries

Team Collaboration

Built for teams working together:

• Pull request reviews for model changes
• Comments and discussions on entities
• Shared understanding across teams
• Consistent definitions organization-wide

Extensible Platform

Integrate with your existing tools:

• Export to JSON, GraphQL, or custom formats
• Connect to BI tools (Looker, Tableau, Power BI)
• Sync with data catalogs (Alation, Collibra)
• Generate dbt models
• API for custom integrations

Design-Driven Implementation

Because of MML, Modality enables engineers, LLMs, and agents to leverage design work to bridge the gap between design macro states and procedural micro states:

• Design Informs Implementation: The data model design process directly informs transformation layers and semantic layers, making design an integral part of implementation rather than separate documentation
• Macro to Micro Translation: High-level design decisions (macro states) automatically inform the procedural details (micro states) of your data transformations
• Machine-Readable Design: MML's structured format allows LLMs and agents to understand and work with your data model programmatically
• Multiple Integration Paths: Access your model through Git for version control, MCP servers for agent interactions, or APIs for custom tooling
• Living Design: Your design remains synchronized with implementation because they share the same source of truth

Use Cases

Data Governance

Maintain a centralized repository of all data definitions:

entity customer_pii {
  type = "dimension"
  description = "Customer personally identifiable information"
  sensitivity = "high"
  retention_period = "7 years"

  belongs-to domain.customer_data
}

• Track sensitive data
• Document retention policies
• Ensure compliance (GDPR, CCPA)
• Audit access and changes

Metric Consistency

Define metrics once, use them everywhere:

entity monthly_recurring_revenue {
  type = "metric"
  description = "MRR from active subscriptions"
  business_logic = """
    SUM(subscription.monthly_amount)
    WHERE subscription.status = 'active'
  """
  owner = "finance-team"

  belongs-to domain.revenue
  derived-from entity.subscription
}

• Single source of truth for metric definitions
• Consistent calculations across tools
• Clear ownership and accountability
• Business logic documentation

Data Discovery

Help team members find and understand data:

domain customer_analytics {
  name = "Customer Analytics"
  description = "Customer behavior, segmentation, and lifetime value"
  color = "#1976D2"
}

entity customer_segment {
  type = "dimension"
  description = "Customer segments based on behavior and demographics"
  examples = ["Enterprise", "SMB", "Self-Serve"]

  belongs-to domain.customer_analytics
}

• Searchable entity catalog
• Clear descriptions and examples
• Domain-based organization
• Relationship visualization

Impact Analysis

Understand downstream effects of changes:

entity base_revenue {
  type = "fact"
  description = "Raw revenue transactions"

  belongs-to domain.sales
}

entity net_revenue {
  type = "metric"
  business_logic = "SUM(base_revenue.amount) - SUM(refunds.amount)"

  derived-from entity.base_revenue
  derived-from entity.refunds
}

entity profit_margin {
  type = "metric"
  business_logic = "(net_revenue - total_costs) / net_revenue"

  derived-from entity.net_revenue
  derived-from entity.total_costs
}

• See what depends on each entity
• Trace upstream sources
• Identify breaking changes
• Plan migrations safely

Data Modeling

Design and iterate on data models:

// Experiment with a new customer scoring model
entity customer_health_score {
  type = "derivation"
  description = "Composite score indicating customer health and risk"
  business_logic = """
    WEIGHTED_AVERAGE(
      usage_score * 0.4,
      payment_score * 0.3,
      engagement_score * 0.3
    )
  """

  belongs-to domain.customer_analytics
  derived-from entity.usage_metrics
  derived-from entity.payment_history
  derived-from entity.engagement_metrics
}

• Document design decisions
• Prototype new models
• Review with stakeholders
• Version and track changes

Who is Modality For?

Analytics Engineers

• Define metrics and transformations
• Document dbt models
• Maintain data quality
• Build reliable pipelines

Data Analysts

• Discover available data
• Understand metric definitions
• Trace data lineage
• Create consistent reports

Data Engineers

• Design data architectures
• Plan migrations
• Document data flows
• Maintain system documentation

Business Intelligence Teams

• Standardize metrics across dashboards
• Document business logic
• Onboard new analysts
• Ensure reporting consistency

Data Governance Teams

• Maintain data catalog
• Enforce data policies
• Track sensitive data
• Ensure compliance

Leadership

• Understand data landscape
• Make informed decisions
• Align teams on definitions
• Demonstrate compliance

Getting Started

Ready to start using Modality? Check out our Getting Started Guide to:

1. Install the Modality CLI
2. Create your first project
3. Write your first MML model
4. Generate documentation
5. Set up version control

Architecture

Modality consists of several components:

┌─────────────────────────────────────────┐
│          MML Files (.mml)               │
│    (Version controlled in Git)          │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│         Modality CLI                    │
│  - Parser                               │
│  - Validator                            │
│  - Generator                            │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│           Outputs                       │
│  - Documentation site                   │
│  - Visual diagrams                      │
│  - JSON/GraphQL exports                 │
│  - Integration APIs                     │
└─────────────────────────────────────────┘

Components

• MML Language: Simple, declarative syntax for defining data models
• CLI Tool: Command-line interface for validation, generation, and builds
• Parser: Converts MML to structured data model
• Validator: Checks for errors and inconsistencies
• Generator: Creates documentation, diagrams, and exports
• Integrations: Connectors for BI tools and data catalogs

Philosophy

Modality is built on several core principles:

1. Simple by Default: Easy to learn, powerful when needed
2. Version Control Native: Data models are code
3. Human-Readable: Anyone can understand MML
4. Tool-Agnostic: Works with your existing stack
5. Collaborative: Built for teams
6. Open: Extensible and hackable

Community and Support

• Documentation: Comprehensive guides and references
• GitHub: Open source, contributions welcome
• Discord: Community chat and support
• Issues: Bug reports and feature requests
• Blog: Best practices and case studies

Next Steps

• Getting Started Guide - Install and create your first model
• MML Syntax - Learn the language
• Domain Blocks - Organize your model
• Entity Blocks - Define your data

Start building better data models today with Modality.